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:

bash

ghostty +show-config --default --docs

List available fonts:

bash

ghostty +list-fonts

Search for specific config options:

bash

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:

bash

# List available fonts first
ghostty +list-fonts

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

Theme/Colors:

bash

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

Key bindings:

bash

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

Searching Documentation

Find specific option documentation:

bash

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

Search by keyword:

bash

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

List all available options:

bash

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

Validation

Test configuration syntax:

bash

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

View current configuration:

bash

# 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

•

List available fonts:

bash

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

•

Check font configuration docs:

bash

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

•

Add to config:

code

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

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

Example: Custom Keybindings

•

Find keybind documentation:

bash

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

•

Keybind syntax:

code

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

•

Add custom bindings:

code

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

Example: Configuring Bell

•

Search bell documentation:

bash

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

•
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)

•

Configure bell:

code

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

Configuration Format

Basic syntax:

code

# 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):

code

# 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