ghostty-config

What this skill does

# Ghostty Configuration

Guidance for configuring the Ghostty terminal emulator. Ghostty uses text-based config files with sensible defaults and zero required configuration.

## Config File Locations

Since Ghostty 1.2.3 the config file is named `config.ghostty` (the `.ghostty` extension lets editors apply syntax highlighting). The extensionless `config` name is still loaded for backwards compatibility.

**XDG Path (All Platforms):**
- `$XDG_CONFIG_HOME/ghostty/config.ghostty`
- `$XDG_CONFIG_HOME/ghostty/config`
- `XDG_CONFIG_HOME` defaults to `~/.config` if undefined

**macOS Additional Path:**
- `~/Library/Application Support/com.mitchellh.ghostty/config.ghostty`
- `~/Library/Application Support/com.mitchellh.ghostty/config`

**Loading order:** all matching files are loaded, later files overriding earlier ones. Within a location `config.ghostty` loads before `config`. On macOS all macOS-path files load *after* all XDG-path files, so the macOS path wins on conflicts. Config is optional; with no file Ghostty uses its defaults.

## Config Syntax

```
# Comments start with #
background = 282c34
foreground = ffffff
font-family = "JetBrains Mono"
keybind = ctrl+z=close_surface
font-family =                     # Empty value resets to default
```

**Rules:**
- Keys are **case-sensitive** (use lowercase)
- Whitespace around `=` is flexible
- Values can be quoted or unquoted
- Empty values reset to defaults
- Every config key works as CLI flag: `ghostty --background=282c34`

## Config Loading & Includes

Files processed sequentially - later entries override earlier ones.

```
# Include additional configs
config-file = themes/dark.conf
config-file = ?local.conf       # ? prefix = optional (no error if missing)
```

**Critical:** `config-file` directives are processed at the file's end. Keys appearing after `config-file` won't override the included file's values.

## Runtime Reloading

- **Linux:** `ctrl+shift+,`
- **macOS:** `cmd+shift+,`

Some options cannot be reloaded at runtime. Some apply only to newly created terminals.

## CLI Commands

Ghostty provides CLI actions via `ghostty +<action>`. Use `ghostty +<action> --help` for action-specific help.

### Configuration Commands

| Command                                 | Description                            |
|-----------------------------------------|----------------------------------------|
| `ghostty +show-config`                  | Show current effective configuration   |
| `ghostty +show-config --default`        | Show default configuration             |
| `ghostty +show-config --default --docs` | Show defaults with documentation       |
| `ghostty +validate-config`              | Validate configuration file for errors |
| `ghostty +edit-config`                  | Open config file in default editor     |

### Listing Commands

| Command                            | Description                           |
|------------------------------------|---------------------------------------|
| `ghostty +list-fonts`              | List available fonts (fixed-width)    |
| `ghostty +list-themes`             | List available colour themes          |
| `ghostty +list-keybinds`           | Show current keybindings              |
| `ghostty +list-keybinds --default` | Show default keybindings              |
| `ghostty +list-colors`             | List available colour names           |
| `ghostty +list-actions`            | List all available keybinding actions |

### Other Commands

| Command                 | Description                  |
|-------------------------|------------------------------|
| `ghostty +version`      | Show version information     |
| `ghostty +help`         | Show help                    |
| `ghostty +show-face`    | Show font face information   |
| `ghostty +ssh-cache`    | Manage SSH terminfo cache    |
| `ghostty +crash-report` | Generate crash report        |
| `ghostty +new-window`   | Open new window (Linux only) |
| `ghostty +boo`          | Easter egg                   |

### Launching with Options

Every config key works as a CLI flag:
```bash
ghostty --background=282c34 --font-size=14
ghostty -e top                              # Run command in terminal
```

**macOS Note:** The `ghostty` CLI is a helper tool. To launch the terminal use `open -na Ghostty.app` or `open -na Ghostty.app --args --font-size=14`.

## Keybinding Syntax

Format: `keybind = trigger=action`

### Triggers

**Modifiers:** `shift`, `ctrl`/`control`, `alt`/`opt`/`option`, `super`/`cmd`/`command`

```
keybind = ctrl+a=select_all
keybind = ctrl+shift+t=new_tab
keybind = super+backquote=toggle_quick_terminal
```

**Physical keys (W3C codes):** `KeyA`, `key_a`, `Digit1`, `BracketLeft`
- Physical keys have higher priority than unicode codepoints
- Use for non-US keyboard layouts

**Key sequences (leader keys):**
```
keybind = ctrl+a>n=new_window      # Press ctrl+a, release, press n
keybind = ctrl+a>ctrl+n=new_window # Both with ctrl
```
Sequences wait indefinitely for next key.

**Named key tables (Ghostty 1.3+):** Switch into a modal set of bindings with `activate_key_table:name` / `activate_key_table_once:name`, leave with `deactivate_key_table`. Use `end_key_sequence` to flush a partial sequence to the terminal. In-terminal search (`search`, `start_search`, `navigate_search`, `end_search`) is also available. See `references/keybindings.md`.

### Prefixes

| Prefix         | Effect                                                                                |
|----------------|---------------------------------------------------------------------------------------|
| `global:`      | System-wide (macOS: needs Accessibility permissions; Linux: needs XDG Desktop Portal) |
| `all:`         | Apply to all terminal surfaces                                                        |
| `unconsumed:`  | Don't consume input (passes through)                                                  |
| `performable:` | Only consume if action succeeds                                                       |

Combine prefixes: `global:unconsumed:ctrl+a=reload_config`

**Note:** Sequences cannot be used with `global:` or `all:` prefixes.

### Special Values

- `keybind = clear` - Remove ALL keybindings
- `keybind = ctrl+a=unbind` - Remove specific binding
- `keybind = ctrl+a=ignore` - Prevent processing by Ghostty and terminal

## Shell Integration

Auto-injection for: **bash**, **zsh**, **fish**, **elvish**

```
shell-integration = detect    # Default - auto-detect shell
shell-integration = none      # Disable auto-injection
shell-integration = fish      # Force specific shell
```

### Shell Integration Features

```
shell-integration-features = cursor,sudo,title
shell-integration-features = no-cursor    # Disable specific feature
```

| Feature        | Description                   |
|----------------|-------------------------------|
| `cursor`       | Blinking bar at prompt        |
| `sudo`         | Preserve terminfo with sudo   |
| `title`        | Set window title from shell   |
| `ssh-env`      | SSH environment compatibility |
| `ssh-terminfo` | Auto terminfo on remote hosts |

### What Shell Integration Enables

1. Smart close (no confirm when at prompt)
2. New terminals start in previous terminal's directory
3. Prompt resizing via redraw
4. Ctrl/Cmd+triple-click selects command output
5. `jump_to_prompt` keybinding works
6. Alt/Option+click repositions cursor at prompt

### Manual Setup (if auto-injection fails)

**Bash** (add to `~/.bashrc` at top):
```bash
if [ -n "${GHOSTTY_RESOURCES_DIR}" ]; then
    builtin source "${GHOSTTY_RESOURCES_DIR}/shell-integration/bash/ghostty.bash"
fi
```

**Zsh:**
```zsh
source ${GHOSTTY_RESOURCES_DIR}/shell-integration/zsh/ghostty-integration
```

**Fish:**
```fish
source "$GHOSTTY_RESOURCES_DIR"/shell-integration/fish/vendor_conf.d/ghostty-shell-integration.fish
```

**macOS Note:** `/bin/bash` does NOT support automatic shell integration. Install Bash via Homebrew or manually source th