Ghostty Config

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

Since Ghostty 1.2.3 the config file is named config.ghostty (the .ghostty extension lets editors apply syntax highlighting). The extensionless config name is still loaded for backwards compatibility.

XDG Path (All Platforms):

• $XDG_CONFIG_HOME/ghostty/config.ghostty
• $XDG_CONFIG_HOME/ghostty/config
• XDG_CONFIG_HOME defaults to ~/.config if undefined

macOS Additional Path:

• ~/Library/Application Support/com.mitchellh.ghostty/config.ghostty
• ~/Library/Application Support/com.mitchellh.ghostty/config

Loading order: all matching files are loaded, later files overriding earlier ones. Within a location config.ghostty loads before config. On macOS all macOS-path files load after all XDG-path files, so the macOS path wins on conflicts. Config is optional; with no file Ghostty uses its defaults.

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

Listing Commands

Other Commands

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.

Named key tables (Ghostty 1.3+): Switch into a modal set of bindings with activate_key_table:name / activate_key_table_once:name, leave with deactivate_key_table. Use end_key_sequence to flush a partial sequence to the terminal. In-terminal search (search, start_search, navigate_search, end_search) is also available. See references/keybindings.md.

Prefixes

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

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
• toggle_secure_input, toggle_background_opacity, reset_window_size
• 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, show_gtk_inspector, show_on_screen_keyboard

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 configuration schema reference

You can find the latest Ghostty configuration schema (including those supported by the tip releases) at: https://raw.githubusercontent.com/sammcj/vscode-ghostty-config-syntax/refs/heads/main/schema/ghostty-config-syntax.schema.json - this can be quite large, so it's best to pass it programmatically to avoid having to read it in full.

When updating it, update the SKILL.md file to update the date the skill was updated to the latest config schema.

Ghostty Keybinding Actions Reference

Complete reference of keybinding actions available in Ghostty.

Format: keybind = trigger=action or keybind = trigger=action:parameter

---

Meta Actions

keybind = ctrl+c=ignore          # Disable ctrl+c in Ghostty
keybind = ctrl+shift+c=unbind    # Remove default copy binding

---

Terminal Output Actions

keybind = ctrl+r=csi:0m                    # Reset text styling
keybind = ctrl+l=esc:c                     # Send ESC c (reset)
keybind = ctrl+shift+enter=text:\x1b[13;2u # Send modified enter

---

Terminal Control Actions

---

Clipboard Actions

---

Font Actions

keybind = ctrl+plus=increase_font_size:2
keybind = ctrl+minus=decrease_font_size:2
keybind = ctrl+0=reset_font_size
keybind = ctrl+1=set_font_size:14

---

Selection Actions

Directions for `adjust_selection`:

• left, right, up, down
• page_up, page_down
• home, end
• beginning_of_line, end_of_line

keybind = shift+left=adjust_selection:left
keybind = shift+end=adjust_selection:end

---

Scrolling Actions

keybind = shift+page_up=scroll_page_up
keybind = ctrl+up=scroll_page_lines:-3
keybind = ctrl+down=scroll_page_lines:3
keybind = ctrl+shift+up=scroll_page_fractional:-0.5

---

Navigation Actions

Offset: positive=forward, negative=backward

keybind = ctrl+shift+up=jump_to_prompt:-1     # Previous prompt
keybind = ctrl+shift+down=jump_to_prompt:1    # Next prompt

---

Search Actions

Available since Ghostty 1.3. Search has its own GUI in the terminal surface.

keybind = ctrl+shift+f=start_search
keybind = ctrl+f=search_selection
keybind = ctrl+g=navigate_search:next
keybind = ctrl+shift+g=navigate_search:previous
keybind = escape=end_search

---

File Export Actions

Actions: copy (path to clipboard), paste (path as terminal input), open (open in default app)

keybind = ctrl+shift+s=write_scrollback_file:open
keybind = ctrl+shift+e=write_selection_file:copy

---

Window Actions

keybind = super+shift+bracket_left=goto_window:previous
keybind = super+shift+bracket_right=goto_window:next

---

Tab Actions

keybind = ctrl+1=goto_tab:1
keybind = ctrl+9=last_tab
keybind = ctrl+shift+left=move_tab:-1
keybind = ctrl+shift+right=move_tab:1

---

Title Actions

A tab title set via set_tab_title or prompt_tab_title overrides any title the terminal application sets, and persists across focus changes.

---

Split Actions

Directions for `new_split`: right, down, left, up, auto (larger axis)

Targets for `goto_split`: right, down, left, up, previous, next

keybind = ctrl+d=new_split:right
keybind = ctrl+shift+d=new_split:down
keybind = alt+left=goto_split:left
keybind = alt+right=goto_split:right
keybind = ctrl+alt+right=resize_split:right,50
keybind = ctrl+alt+left=resize_split:left,50
keybind = ctrl+shift+z=toggle_split_zoom
keybind = ctrl+shift+e=equalize_splits

---

Window Management Actions

---

Inspector & Development Actions

Modes for `inspector`: toggle, show, hide

keybind = ctrl+shift+i=inspector:toggle

---

Configuration Actions

keybind = ctrl+comma=open_config
keybind = ctrl+shift+comma=reload_config

---

Closing Actions

keybind = ctrl+w=close_surface
keybind = ctrl+shift+w=close_tab

---

Application Actions

Reversible actions for undo/redo: new/close window, tab, split

keybind = global:super+backquote=toggle_quick_terminal
keybind = super+h=toggle_visibility
keybind = super+q=quit

---

Testing Actions

Threads: main, io, render

---

Key Table & Sequence Actions

Available since Ghostty 1.3. Named key tables let a trigger switch into a different set of bindings (a modal layer), similar to Vim modes or tmux prefix tables. The named tables themselves are defined in the keybind configuration; these actions activate and deactivate them.

# Enter a modal "resize" table, then deactivate it with escape
keybind = ctrl+a>r=activate_key_table:resize
# Flush ctrl+w to the program instead of waiting for the next key in a sequence
keybind = ctrl+w>escape=end_key_sequence

If a named table does not exist, the activate actions have no effect and report performable as false.

---

Default Keybindings

View all default keybindings:

ghostty +list-keybinds --default

Common Defaults (Platform Dependent)

---

Keybinding Tips

Remove All Default Bindings

keybind = clear

Vim-style Navigation

keybind = ctrl+h=goto_split:left
keybind = ctrl+j=goto_split:down
keybind = ctrl+k=goto_split:up
keybind = ctrl+l=goto_split:right

tmux-style Leader Key

keybind = ctrl+a>c=new_tab
keybind = ctrl+a>n=next_tab
keybind = ctrl+a>p=previous_tab
keybind = ctrl+a>|=new_split:right
keybind = ctrl+a>-=new_split:down
keybind = ctrl+a>z=toggle_split_zoom
keybind = ctrl+a>x=close_surface

Global Quick Terminal

keybind = global:super+backquote=toggle_quick_terminal

macOS: Requires Accessibility permissions Linux: Requires XDG Desktop Portal (KDE 5.27+, GNOME 48+)

Ghostty Configuration Options Reference

Complete reference of Ghostty configuration options organised by category.

Format: option-name - Type - Default - Description. Valid values and platform notes where applicable.

---

Font Options

Font Family

Use ghostty +list-fonts to see available fonts.

Font Style

Font Size & Features

Variable Fonts

Common axes: wght (weight), slnt (slant), ital, opsz, wdth, GRAD

Font Mapping

FreeType (Linux Only)

---

Colour & Display

Basic Colours

Transparency & Images

Custom Shaders

Cursor

Selection

Search Colours

Contrast & Splits

Scrollbar

---

Cell Adjustments

All accept Integer or Percentage (e.g., 20%, -15%).

---

Command & Shell

---

Scrollback & Clipboard

---

Links & Images

---

Keybindings & Input Remapping

---

Mouse & Input

---

Bell

---

Notifications

---

Window

Size & Position

Padding

Appearance

Behaviour

Tabs & Splits

---

Resize Overlay

---

Quick Terminal

---

Application

---

macOS Platform

Window & Titlebar

Input

Security

Icon

Behaviour

---

GTK/Linux Platform

GTK Appearance

GTK Custom Styling

GTK Rendering

Linux System

---

Terminal Behaviour

---

Miscellaneous

---

Colour Format Reference

All colour options accept:

• #RRGGBB - Hex with hash
• RRGGBB - Hex without hash
• X11 colour names (e.g., red, steelblue, coral)
• Special values for cursor/selection: cell-foreground, cell-background

Duration Format Reference

Duration options accept combinations of:

• y (years), d (days), h (hours), m (minutes)
• s (seconds), ms (milliseconds), us/µs (microseconds), ns (nanoseconds)

Examples: 1h30m, 45s, 100ms, 750ms

Full Ghostty configuration schema reference

You can find the latest Ghostty configuration schema (including those supported by the tip releases) at: https://raw.githubusercontent.com/sammcj/vscode-ghostty-config-syntax/refs/heads/main/schema/ghostty-config-syntax.schema.json - this can be quite large, so it's best to pass it programmatically to avoid having to read it in full.