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

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:

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

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

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.