Ghostty Config Management

The Iron Law

ALWAYS CHECK DOCS VIA MCP TOOL BEFORE GIVING CONFIG ADVICE.
NEVER ASSUME A VALUE'S TYPE, UNIT, OR BEHAVIOR FROM ITS NAME.

Config File Location

• macOS: ~/Library/Application Support/com.mitchellh.ghostty/config
  • This path takes priority over XDG. Both can coexist, macOS path wins.
• Linux: ${XDG_CONFIG_HOME:-~/.config}/ghostty/config

The config is a plain text file named config (no extension) inside the directory.

Config Syntax

• key = value — spaces around = optional
• # comments only at line start — font-size = 14 # comment is WRONG, # comment becomes part of the value
• Empty value resets to default: font-size =
• Multi-value: repeat the key (e.g. font-family for fallback chain)
• Clear then set: font-family = "" then font-family = NewFont
• keybind = (empty) removes ALL keybinds including defaults — this does NOT reset to defaults
• Use ctrl+slash not ctrl+/ in keybinds — / is parsed as key table separator

Core Workflow: Changing Any Config Option

1. ghostty_get_config_option → read full docs for the option
2. Check the value type and unit — e.g. scrollback-limit is bytes, not lines
3. Edit the config file
4. ghostty_validate_config → verify syntax
5. Most settings hot-reload; theme changes with light:X,dark:Y syntax may need full restart on macOS

Workflows

Theme

1. ghostty_list_themes — filter with color="dark" or "light"
2. Set theme = <name> — manual color settings (background, foreground) override theme colors
3. Dual theme: theme = light:catppuccin-latte,dark:catppuccin-mocha
4. After changing themes, if tab bar looks wrong → restart Ghostty (known macOS reload bug)

Font

1. ghostty_list_fonts → name must match exactly (case-sensitive)
2. For fallback: repeat font-family on multiple lines
3. ghostty_show_face → verify which font renders specific characters
4. macOS CJK users: explicitly set a CJK font (e.g. PingFang SC) to avoid oversized fallback

Keybind

1. ghostty_list_actions → available actions
2. ghostty_list_keybinds → current bindings
3. Format: keybind = super+shift+c=copy_to_clipboard
4. Chord: keybind = ctrl+a>ctrl+b=action
5. Unbind: keybind = super+c=unbind

Troubleshooting "Config Not Working"

1. ghostty_validate_config → check syntax errors
2. ghostty_show_current_config with changes_only=true → see what's actually set
3. Check for inline # comments (they become part of the value)
4. Check for conflicting settings (manual colors override theme)
5. Try opening a new window — some settings need new window or full restart
6. macOS: check both config paths — macOS path takes priority over XDG

Red Flags — STOP and Check Docs First

• "I know what this option does" → check anyway, units may surprise you
• "The value should be about 10000" → is it bytes? pixels? lines? check docs
• "This is similar to other terminals" → Ghostty syntax has unique rules
• "Just set it to true/false" → some options use default, false, or specific enum values

Critical Gotchas (Inline)

• scrollback-limit = bytes, not lines. Default 10000000 = 10 MB. Setting 10000 gives only ~10 KB
• background-opacity has color blending bugs with light themes (premultiplied alpha). Tab appearance may break on Linux
• macos-titlebar-style = transparent silently reverts to native when background ≤ #0c0c0c
• Linux fractional scaling (125%, 150%): fonts will be blurry, no config workaround
• copy-on-select = true on macOS is effectively a no-op (no selection clipboard). Use clipboard to get "select to copy" on macOS

See references/config-gotchas.md for the complete list with details and workarounds. See references/config-recipes.md for curated config patterns and combos (visual optimization, font tuning, macOS experience).