# Ghostty Settings TUI

A terminal user interface for managing Ghostty terminal emulator configuration.

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Python](https://img.shields.io/badge/python-3.10+-blue.svg)

## 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](https://textual.textualize.io/), 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)

```bash
pip install ghostty-tui
```

### From Source

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

### Development Setup

```bash
pip install -e ".[dev]"
```

## Usage

### Basic Usage

```bash
# Launch the TUI
ghostty-tui

# Or using Python module
python -m ghostty_tui
```

### Command Line Options

```bash
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

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

### Running Tests

```bash
pytest
```

### Type Checking

```bash
mypy src/ghostty_tui
```

### Code Formatting and Linting

```bash
# 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](https://ghostty.org) - The amazing terminal emulator
- [Textual](https://textual.textualize.io) - Modern TUI framework for Python
- Community contributors and testers

## Links

- [Ghostty Official Website](https://ghostty.org)
- [Ghostty Documentation](https://ghostty.org/docs)
- [Ghostty Configuration Reference](https://ghostty.org/docs/config/reference)
- [Textual Documentation](https://textual.textualize.io)
- [Python Terminal UIs](https://textual.textualize.io)
