ghostty-tui 0.1.0

A terminal UI for managing Ghostty terminal emulator settings

Ghostty Settings TUI

A terminal user interface for managing Ghostty terminal emulator configuration.

Overview

Ghostty Settings TUI provides an intuitive, interactive terminal-based interface for viewing and editing your Ghostty configuration. Instead of manually editing the config file, you can navigate through categorized options, search for specific settings, and make changes with real-time validation. Built with Textual, it offers a modern experience for managing terminal settings.

Features

• Category Navigation: Browse options organized into logical categories (Font, Colors, Cursor, Window, Shell, Keybindings, macOS, Linux, X11, Wayland, and more)
• Real-time Search: Fuzzy search across all configuration options, descriptions, and categories
• Type-Aware Display: View and understand all option types including booleans, strings, integers, floats, colors, enums, paths, and keybindings
• Smart Validation: Type-specific validation for configuration values
• Configuration Management: Read and write to Ghostty config file with automatic backup support
• Keyboard Navigation: Full keyboard-driven interface with intuitive shortcuts
• Environment-Aware: Respects XDG_CONFIG_HOME and standard Ghostty config locations
• Dracula Theme: Beautiful Dracula-inspired color scheme

Requirements

• Python 3.10 or higher
• Ghostty terminal emulator installed and accessible in PATH
• Terminal with at least 80x24 characters

Installation

From PyPI (Recommended)

pip install ghostty-tui

From Source

git clone https://github.com/necoli1822/ghostty-tui.git
cd ghostty-tui
pip install -e .

Development Setup

pip install -e ".[dev]"

Usage

Basic Usage

# Launch the TUI
ghostty-tui

# Or using Python module
python -m ghostty_tui

Command Line Options

ghostty-tui --help                              # Show help message
ghostty-tui --version                           # Show version
ghostty-tui --config /path/to/custom/config    # Use custom config file
ghostty-tui --schema-file /path/to/schema.txt  # Use schema from file (testing)

Keyboard Shortcuts

Key	Action
Tab / Shift+Tab	Navigate between widgets (search input, category list, options panel)
↑ / ↓	Scroll through categories or options
Enter / Space	Select a category
Ctrl+S	Save configuration to file
/	Focus search input to filter options
Escape	Clear search query and return to category view
?	Display help screen
Ctrl+Q	Quit application

Workflow Examples

Browse by Category

1. Launch ghostty-tui
2. Use arrow keys to navigate category list
3. Press Enter to select a category
4. View all options in that category with their current values, defaults, and descriptions

Search for an Option

1. Press / to focus the search input
2. Type a partial option name (e.g., "font-size", "cursor", "background")
3. Results appear instantly, sorted by relevance
4. Press Escape to clear search and return to category view

View Option Details

Each option displays:

• Name: The configuration option identifier
• Type: The expected value type (boolean, string, integer, color, enum, etc.)
• Current Value: What's currently set (or empty if using default)
• Default Value: The built-in default
• Valid Options: For enum types, the list of valid values
• Description: Explanation of what the option does
• Status: An asterisk (*) indicates modified values

Configuration

The application reads and writes to your Ghostty config file location:

• Linux/Unix: ~/.config/ghostty/config (respects $XDG_CONFIG_HOME)
• macOS: ~/.config/ghostty/config

If the config file doesn't exist, it will be created when you save changes.

Config File Format

# Ghostty configuration - standard format
font-family = "Monospace"
font-size = 14
cursor-style = bar
background = #1a1b26
foreground = #c0caf5

# Comments and blank lines are preserved
keybind = super+c=copy_to_clipboard
keybind = super+v=paste_from_clipboard

Development

Setup Development Environment

# Install with development dependencies
pip install -e ".[dev]"

Running Tests

pytest

Type Checking

mypy src/ghostty_tui

Code Formatting and Linting

# Check code style
ruff check src/ghostty_tui tests

# Format code
ruff format src/ghostty_tui tests

Project Structure

ghostty_setting_tui/
├── src/ghostty_tui/
│   ├── __init__.py                # Package initialization and public API
│   ├── __main__.py                # CLI entry point with argument parsing
│   ├── app.py                     # Main Textual application and UI logic
│   ├── models.py                  # Data classes for options, config, and app state
│   ├── parser.py                  # Ghostty schema parser
│   ├── config_manager.py          # Config file read/write operations
│   ├── categories.py              # Category definitions and sorting logic
│   ├── search.py                  # Search functionality
│   ├── exceptions.py              # Custom exception classes
│   ├── widgets/                   # Custom Textual widgets
│   │   ├── __init__.py
│   │   ├── sidebar.py            # Category sidebar widget
│   │   ├── option_panel.py       # Options display panel
│   │   ├── option_row.py         # Individual option row
│   │   ├── option_input.py       # Text input widget for options
│   │   ├── option_select.py      # Dropdown/enum selector widget
│   │   └── option_toggle.py      # Boolean toggle widget
│   ├── screens/                   # Textual screens
│   │   ├── __init__.py
│   │   ├── main_screen.py        # Main application screen
│   │   └── help_screen.py        # Help/keybindings screen
│   └── styles/                    # CSS styling files
│       └── app.tcss              # Textual CSS stylesheet
├── tests/                         # Test suite
├── sample_data/                   # Sample config and schema files for testing
└── pyproject.toml                 # Project configuration and dependencies

Configuration Categories

Options are automatically organized into these categories:

• Font: Font family, size, and styling
• Colors: Color palette and color scheme settings
• Theme: Theme and appearance customization
• Cursor: Cursor style and behavior
• Window: Window size, position, and decoration
• Mouse: Mouse behavior and interactions
• Clipboard: Copy and paste behavior
• Scrollback: Scrollback buffer configuration
• Shell: Shell command and working directory settings
• Terminal: Terminal behavior and emulation
• Keybindings: Custom keyboard shortcuts
• Links: URL and link handling
• Behavior: General behavior settings
• macOS: macOS-specific configuration
• GTK/Linux: GTK and Linux-specific settings
• X11: X11-specific configuration
• Wayland: Wayland-specific settings
• Advanced: Advanced/internal settings
• Other: Miscellaneous settings

Supported Option Types

The application understands and displays information about these option types:

• Boolean: True/false values
• String: Text values
• Integer: Whole numbers
• Float: Decimal numbers
• Color: Hex color codes (e.g., #1a1b26)
• Enum: Predefined set of valid values
• Path: File system paths
• Keybind: Keyboard shortcuts

Error Handling

The application handles common errors gracefully:

• Ghostty Not Found: If Ghostty is not installed, you'll be notified with instructions
• Config File Missing: The config directory will be created when saving if needed
• Schema Parsing Errors: Detailed error messages help diagnose schema issues
• Permission Errors: Clear feedback if config file can't be read or written
• Terminal Size: Application requires minimum 80x24 terminal dimensions

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Roadmap

Potential future enhancements:

• Profile management (save/load configuration profiles)
• Diff view (see what changed before saving)
• Theme preview (live preview of color changes)
• Configuration validation against Ghostty's type system
• Integration with Ghostty's live reload feature

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Ghostty - The amazing terminal emulator
• Textual - Modern TUI framework for Python
• Community contributors and testers

Links

• Ghostty Official Website
• Ghostty Documentation
• Ghostty Configuration Reference
• Textual Documentation
• Python Terminal UIs