ghostty-config

Original：🇺🇸 English
Translated

Guidance for editing Ghostty terminal configuration files. You must use this skill when creating or modifying Ghostty config files.

12installs
Sourcesammcj/agentic-coding
Added on

NPX Install

npx skill4agent add sammcj/agentic-coding ghostty-config

Tags

Translated version includes tags in frontmatter
ghostty-configurationterminal-emulatorcli-commandskeybinding-setupshell-integration

SKILL.md Content

View Translation Comparison →

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

CommandDescription
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

CommandDescription
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

CommandDescription
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:
bash
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

PrefixEffect
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
FeatureDescription
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):
bash
if [ -n "${GHOSTTY_RESOURCES_DIR}" ]; then
    builtin source "${GHOSTTY_RESOURCES_DIR}/shell-integration/bash/ghostty.bash"
fi
Zsh:
zsh
source ${GHOSTTY_RESOURCES_DIR}/shell-integration/zsh/ghostty-integration
Fish:
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.