ghostty-config
Guidance for editing Ghostty terminal configuration files. You must use this skill when creating or modifying Ghostty config files.
When & Why to Use This Skill
This Claude skill provides comprehensive guidance for configuring and optimizing the Ghostty terminal emulator. It assists developers in managing configuration files, customizing advanced keybindings, setting up shell integrations, and applying platform-specific optimizations for a high-performance terminal experience.
Use Cases
- 1. Visual Environment Customization: Configure themes, background transparency, font ligatures, and window styles to create a personalized and ergonomic workspace.
- 2. Advanced Productivity Mapping: Set up complex keybinding sequences, leader keys, and global shortcuts to trigger terminal actions or system-wide commands.
- 3. Seamless Shell Integration: Enable and troubleshoot auto-injection for Bash, Zsh, and Fish to unlock features like prompt-aware navigation and smart directory persistence.
- 4. Cross-Platform Configuration: Manage terminal settings across macOS and Linux, handling path differences and platform-specific features like background blur or GTK themes.
- 5. Configuration Validation and Debugging: Use built-in CLI commands to validate syntax, list available fonts/themes, and inspect the effective configuration to resolve conflicts.
| 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/configif 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 keybindingskeybind = ctrl+a=unbind- Remove specific bindingkeybind = 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_promptkeybinding 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-resizewindow-vsync,window-colorspacemacos-titlebar-style,toggle_window_float_on_topfont-thicken,font-thicken-strengthtoggle_visibility,undo,redo,check_for_updates- Global keybindings require Accessibility permissions
Linux/GTK Only:
window-title-font-family,window-subtitlewindow-titlebar-background/foreground(requireswindow-theme = ghostty)window-show-tab-bar,gtk-single-instancetoggle_maximize,toggle_window_decorationstoggle_tab_overview,toggle_command_paletteprompt_surface_title
Linux Wayland Only:
quick-terminal-keyboard-interactivitygtk-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.