ghostty-configuration

Ghostty Terminal Configuration

Guide for configuring Ghostty terminal emulator with local documentation access.

When to Use This Skill

Use this skill when:

• Working with Ghostty configuration files
• Looking up valid configuration options
• Troubleshooting Ghostty settings
• Finding available fonts or themes
• Understanding Ghostty-specific features

Quick Reference

Access Local Documentation

Ghostty includes comprehensive built-in documentation:

Full configuration reference with inline docs:

ghostty +show-config --default --docs

List available fonts:

ghostty +list-fonts

Search for specific config options:

ghostty +show-config --default --docs | grep -A 10 "keyword"

Configuration File Location

In this dotfiles repository, Ghostty config is managed at:

• Source: config/ghostty/config
• Installed: ~/.config/ghostty/config

Common Configuration Patterns

Font configuration:

# List available fonts first
ghostty +list-fonts

# Then configure in config file
font-family = Maple Mono NF
font-size = 14

Theme/Colors:

# Search for color-related options
ghostty +show-config --default --docs | grep -i "color"

Key bindings:

# Search for keybind options
ghostty +show-config --default --docs | grep -i "keybind"

Searching Documentation

Find specific option documentation:

# Example: Find all font-related options
ghostty +show-config --default --docs | grep -B 2 -A 20 "^font-"

Search by keyword:

# Example: Find clipboard options
ghostty +show-config --default --docs | grep -i "clipboard" -A 10

List all available options:

# Get just the config keys without docs
ghostty +show-config --default | grep "^[a-z]" | cut -d= -f1

Validation

Test configuration syntax:

# Ghostty will report errors on startup
ghostty --config-file=path/to/config

View current configuration:

# Shows active config (after applying defaults + user config)
ghostty +show-config

Common Configuration Categories

Key categories (use documentation search for complete details):

• Font: font-family, font-size, font-style, font-feature
• Colors: background, foreground, palette, theme
• Window: window-padding-x/y, window-theme, window-decoration
• Shell: shell-integration-features, command, working-directory
• Keybinds: keybind = trigger=action[:parameter]
• Bell: bell-features, bell-audio-path, bell-audio-volume
• Performance: renderer, vsync
• macOS: macos-titlebar-style, macos-option-as-alt

Example: Adding a Font

1. List available fonts:

   ghostty +list-fonts | grep -i "JetBrains"
   

2. Check font configuration docs:

   ghostty +show-config --default --docs | grep -A 40 "^font-family"
   

3. Add to config:

   font-family = JetBrains Mono
   font-family = Apple Color Emoji  # Fallback for emoji
   font-size = 14
   

4. Reload config (Ghostty auto-reloads, or use ctrl+c>r keybind if configured)

Example: Custom Keybindings

1. Find keybind documentation:

   ghostty +show-config --default --docs | grep -B 10 -A 30 "^keybind ="
   

2. Keybind syntax:

   keybind = [prefix:]trigger=action[:parameter]
   

3. Add custom bindings:

   keybind = ctrl+shift+c=copy_to_clipboard
   keybind = ctrl+shift+v=paste_from_clipboard
   keybind = ctrl+c>v=new_split:right
   

Example: Configuring Bell

1. Search bell documentation:

   ghostty +show-config --default --docs | grep -A 50 "^# Bell features"
   

2. Available bell features:

   • system - System notification (GTK only)
   • audio - Custom sound (GTK only)
   • attention - Bounce dock icon on macOS (default: enabled)
   • title - Add 🔔 emoji to title (default: enabled)
   • border - Display border (GTK only)

3. Configure bell:

   # Only show title emoji, no dock bounce
   bell-features = no-attention,title
   

Configuration Format

Basic syntax:

# Comments start with hash
key = value

# Boolean values
some-feature = true
other-feature = false

# Multiple values - repeat the key
font-family = JetBrains Mono
font-family = Apple Color Emoji

# Empty value = use default
font-family =

No quotes needed for most values (unlike TOML/YAML):

# Correct
font-family = JetBrains Mono

# Also works, but unnecessary
font-family = "JetBrains Mono"

Keybind prefixes:

• global: - System-wide (requires accessibility permissions)
• all: - Apply to all surfaces
• unconsumed: - Pass to program if not consumed
• performable: - Only if action can be performed

Tips

• Ghostty automatically reloads configuration on file changes
• Use ghostty +show-config to verify active settings
• All documentation is built-in - no internet required
• Config format is custom (not TOML/YAML/INI)
• Comments start with #
• Boolean values: true or false
• Multiple values: repeat the key multiple times
• Empty value (key =) means "use default"

Troubleshooting

Config not loading:

• Check file location: ~/.config/ghostty/config
• Verify syntax: generally no quotes needed
• Check Ghostty logs for errors
• Unknown fields are silently ignored

Font not found:

• Use ghostty +list-fonts to find exact font name
• Names are case-sensitive
• Some fonts require full family name (e.g., "Maple Mono NF" not "Maple Mono")

Colors not working:

• Verify hex format: #RRGGBB or #RRGGBBAA
• Check terminal theme compatibility
• Use ghostty +show-config to see active values

Keybindings not working:

• Check for conflicts with system/other apps
• Verify action name is correct (use docs to find valid actions)
• Some actions are platform-specific (GTK only, macOS only)
• Global keybinds require accessibility permissions

Additional Resources

• Built-in docs: ghostty +show-config --default --docs
• Man pages: man ghostty
• This repo's config: config/ghostty/config
• List fonts: ghostty +list-fonts
• Show active config: ghostty +show-config