wezztershier

⚡ Beta v0.2.0

GUI configuration manager for WezTerm terminal emulator

Create visual interfaces from decorated Lua configs. Add simple annotations to your WezTerm config and get automatic GUI generation with sliders, color pickers, and more.

GitHub Get Started

Quick Start

wezztershier generates visual controls from decorated WezTerm configs. Add special comments to your Lua config and get an instant GUI.

Basic Example

$cat ~/.config/wezterm/wezterm.lua

local config = {} -- <<TUNER-START>> -- @ui: slider(min=10, max=42, step=1) type=int config.font_size = 18 -- <<TUNER-END>> return config

$wezztershier

[GUI window opens with font size slider]

Installation

From RPM

DNF

$sudo dnf install wezztershier

$wezztershier --version

wezztershier 0.2.0

From Source

pip

$git clone https://github.com/espadonne/wezztershier.git

$cd wezztershier && pip install -e .

$wezztershier

Dependencies

Requirements

Python 3.10-3.12
PyQt6 >= 6.5.0 - GUI framework
WezTerm - Terminal emulator

First Steps

Add decorators to your WezTerm config:

local config = {}

-- <<TUNER-START>>

-- @ui: slider(min=10, max=42, step=1) type=int
config.font_size = 18

-- @ui: slider(min=0.5, max=2.0, step=0.1) type=float
config.line_height = 1.29

-- @ui: color_picker(format="hex", alpha=false) type=color
config.colors = config.colors or {}
config.colors.background = "#333333"

-- <<TUNER-END>>

return config

Run wezztershier and adjust settings visually!

Decoration Syntax

Decorators define how settings appear in the GUI.

Basic Format

-- @ui: <widget_type>(<parameters>) type=<data_type>
config.setting = value

Markers

Decorators must be between tuner markers:

-- <<TUNER-START>>
-- Your decorated config here
-- <<TUNER-END>>

Only content between markers is modified by wezztershier.

Widget Examples

Slider

-- @ui: slider(min=10, max=42, step=1) type=int
config.font_size = 18

Color Picker

-- @ui: color_picker(format="hex", alpha=false) type=color
config.colors = config.colors or {}
config.colors.background = "#333333"

Dropdown

-- @ui: select(options="JetBrains Mono, Fira Code, Cascadia Code") type=string
config.font = wezterm.font("JetBrains Mono")

Numerical Input

-- @ui: numerical(min=100, max=10000, step=100) type=int
config.scrollback_lines = 3500

CLI Options

Option	Type	Default	Description
`--version`	flag	false	Show version and exit
`--debug`	flag	false	Enable debug mode with verbose logging
`--check-widgets`	flag	false	Check widget registration and exit
`--config PATH`	path	~/.config/wezterm/wezterm.lua	Path to WezTerm config file
`--backup-dir PATH`	path	~/.local/share/wezztershier/backups	Backup directory
`--test-config`	flag	false	Test config parsing without launching GUI

Overview

wezztershier is a static-decorator-built GUI tuner for WezTerm. Add simple annotations to your Lua config and automatically generate visual controls.

Key Features

Automatic GUI generation from decorated configs
8 widget types (sliders, color pickers, dropdowns, etc.)
Real-time config preview
Automatic backup with deduplication
Supports nested config tables
PyQt6-based visual interface

Widget Types

8 widget types for different configuration needs:

Option	Type	Default	Description
`slider`	widget	-	Float/integer slider with min/max/step
`int_slider`	widget	-	Integer-only slider (alias)
`numerical`	widget	-	Direct number input with spin buttons
`text`	widget	-	Text input field for strings
`select`	widget	-	Dropdown menu with predefined options
`theme_select`	widget	-	Specialized theme selector
`color_picker`	widget	-	Visual color picker with preview
`color_scheme`	widget	-	Color scheme selector

System Overview

wezztershier is a Python application using PyQt6 with a modular architecture.

wezztershier/
├── src/wezztershier/
│   ├── cli.py              # CLI entry point
│   ├── core/
│   │   ├── parser.py       # Recursive descent parser
│   │   └── backup.py       # Backup management
│   ├── gui/
│   │   └── main_window.py  # Main application window
│   └── widgets/
│       ├── factory.py      # Widget factory pattern
│       ├── sliders.py      # Slider widgets
│       ├── inputs.py       # Input widgets
│       ├── selectors.py    # Selection widgets
│       └── color.py        # Color widgets

Widget Reference

Complete reference for all available widgets.

slider / int_slider

Continuous value selection with mouse or keyboard.

-- @ui: slider(min=10, max=42, step=1) type=int
config.font_size = 18

-- @ui: slider(min=0.5, max=5.5, step=0.01) type=float
config.line_height = 1.29

Parameters

min - Minimum value (required)
max - Maximum value (required)
step - Step size (required)
precision - Decimal places (default: 2)
type - "float" or "int"

numerical

Direct number input with spin buttons.

-- @ui: numerical(min=100, max=10000, step=100) type=int
config.scrollback_lines = 3500

text

Text input field for string values.

-- @ui: text() type=string
config.my_string = "default value"

select

Dropdown menu with predefined options.

-- @ui: select(options="true, false") type=string
config.hide_tab_bar_if_only_one_tab = true

-- @ui: select(options="JetBrains Mono, Fira Code") type=string
config.font = wezterm.font("JetBrains Mono")

color_picker

Visual color picker with preview.

-- @ui: color_picker(format="hex", alpha=false) type=color
config.colors = config.colors or {}
config.colors.background = "#333333"

-- Nested tables automatically initialized:
-- @ui: color_picker(format="hex", alpha=false) type=color
config.colors = config.colors or {}
config.colors.tab_bar = config.colors.tab_bar or {}
config.colors.tab_bar.background = "#444444"

Parameters

format - "hex", "rgb", or "rgba"
alpha - Enable alpha channel (true/false)
preview_size - Preview box size in pixels

Troubleshooting

Common issues and solutions.

No annotations found

Problem: GUI shows "No configuration annotations found."

Solution: Ensure your config has markers:

-- <<TUNER-START>>
-- @ui: slider(min=10, max=42, step=1) type=int
config.font_size = 18
-- <<TUNER-END>>

Widget doesn't appear

Problem: Decorated setting doesn't show in GUI.

Solution: Check widget registration:

Debug

$wezztershier --check-widgets

✓ slider ✓ numerical ✓ color_picker ...

$wezztershier --test-config

Test parsing without GUI

Changes not persisting

Problem: Changes don't save after closing.

Solution: Click "Apply Changes" button before closing. If closed without applying, temp backup auto-reverts.

Color picker not working

Problem: Colors not saving correctly.

Solution: Ensure table initialization:

-- @ui: color_picker(format="hex", alpha=false) type=color
config.colors = config.colors or {}
config.colors.background = "#333333"

wezztershier automatically generates table init for nested paths.

Parser errors

Problem: Decorator syntax errors.

Solution: Keep decorators simple:

Single-level nesting for lists/dicts only
Escape quotes in strings: \"text\"
Use commas between parameters

Debug Mode

Run with --debug for verbose output:

Debug

$wezztershier --debug

Widget registration status: ✓ slider ✓ numerical ✓ color_picker ... Parsing config... Creating widgets... [Detailed logging]

Getting Help

GitHub Issues: Report bugs or request features
Documentation: Check GRAMMAR.md for syntax reference

wezztershier

Quick Start

Installation

From RPM

From Source

Dependencies

Requirements

First Steps

Decoration Syntax

Basic Format

Markers

Widget Examples

Slider

Color Picker

Dropdown

Numerical Input

CLI Options

Overview

Key Features

Decoration Syntax

Grammar

Markers

Widget Types

Profile Management

Separate Backups

WezTerm Integration

System Overview

Core Modules

Parser (Wexler)

Parsing Features

Widget Factory

Backup System

Backup Features

Data Flow

Widget Reference

slider / int_slider

Parameters

numerical

text

select

color_picker

Parameters

Troubleshooting

No annotations found

Widget doesn't appear

Changes not persisting

Color picker not working

Parser errors

Debug Mode

Getting Help