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:

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

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:

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

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.

ghostty-config

NPX Install

Tags

SKILL.md Content