Ghostty Configuration

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

XDG Path (All Platforms):

• $XDG_CONFIG_HOME/​ghostty/​config
• Defaults to ~/​.config/​ghostty/​config if XDG_CONFIG_HOME undefined

macOS Additional Path:

• ~/​Library/​Application Support/​com.mitchellh.ghostty/​config
• If both XDG and macOS paths exist, both are loaded with macOS path taking precedence

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

Listing Commands

Other Commands

Launching with Options

Every config key works as a CLI flag:

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.

Prefixes

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

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

if [ -n "${GHOSTTY_RESOURCES_DIR}" ]; then
    builtin source "${GHOSTTY_RESOURCES_DIR}/​shell-integration/​bash/​ghostty.bash"
fi

Zsh:

source ${GHOSTTY_RESOURCES_DIR}/​shell-integration/​zsh/​ghostty-integration

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 the script.

Common Configuration Patterns

Theme with Light/​Dark Mode

theme = light:catppuccin-latte,dark:catppuccin-mocha

Quick Terminal (Drop-down)

quick-terminal-position = top
quick-terminal-size = 50%
quick-terminal-autohide = true
keybind = global:super+backquote=toggle_quick_terminal

Custom Colour Palette

palette = 0=#1d2021
palette = 1=#cc241d
# ... (0-255 supported)

Font Configuration

font-family = "JetBrains Mono"
font-family-bold = "JetBrains Mono Bold"
font-size = 14
font-feature = -calt        # Disable ligatures
font-feature = -liga

Background Transparency

background-opacity = 0.9
background-blur = true      # macOS, KDE Plasma only

Platform-Specific Notes

macOS Only:

• window-position-x/​y, window-save-state, window-step-resize
• window-vsync, window-colorspace
• macos-titlebar-style, toggle_window_float_on_top
• font-thicken, font-thicken-strength
• toggle_visibility, undo, redo, check_for_updates
• Global keybindings require Accessibility permissions

Linux/​GTK Only:

• window-title-font-family, window-subtitle
• window-titlebar-background/​foreground (requires window-theme = ghostty)
• window-show-tab-bar, gtk-single-instance
• toggle_maximize, toggle_window_decorations
• toggle_tab_overview, toggle_command_palette
• prompt_surface_title

Linux Wayland Only:

• quick-terminal-keyboard-interactivity
• gtk-quick-terminal-layer, gtk-quick-terminal-namespace

FreeType (Linux) Only:

• freetype-load-flags

Reference Files

For complete option and keybinding references, load:

• references/​options.md - All config options by category (font, colour, window, etc.)
• references/​keybindings.md - All keybinding actions with parameters

Load these when you need specific option details, valid values, or keybinding action syntax.