name: ghostty-config description: Guidance for editing Ghostty terminal configuration files. You must use this skill when creating or modifying Ghostty config files.

allowed-tools: "Read,Edit,Write,Grep,Glob"

model: "inherit"

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

Smart close (no confirm when at prompt)
New terminals start in previous terminal's directory
Prompt resizing via redraw
Ctrl/Cmd+triple-click selects command output
jump_to_prompt keybinding works
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.

ghostty-config

$ Installer