Ghostty

Configure, theme, and extend Ghostty — the fast, native, GPU-accelerated terminal emulator by Mitchell Hashimoto. Zero required configuration; everything below is optional enhancement.

Core Philosophy

1. Zero config is a valid config. Ghostty works out of the box with JetBrains Mono, sensible defaults, and built-in Nerd Fonts. Configure only what you actually want different.
2. Read the config reference in-terminal. ghostty +show-config --default --docs is the authoritative source for your exact installed version. Use it before guessing at option names.
3. Themes are just config files. Any config option can go in a theme. Load them with theme = Name and override individual settings in the main config after.
4. Shell integration unlocks the terminal. Enable it; it costs nothing and enables prompt jumping, smart cursor, CWD tracking, and SSH/sudo wrapping.
5. Platform differences are real. global: keybinds are macOS-only. Quick terminal needs Wayland on Linux. macos-option-as-alt is critical for vim/emacs. Know your platform.

Quick-Start

"Change my font and theme"

font-family = "Fira Code"
font-size = 14
font-feature = -calt,-liga    # disable ligatures if unwanted
theme = dark:Catppuccin Frappe,light:Catppuccin Latte

See references/themes-and-appearance.md for 460+ theme names and custom theme authoring.

"Set up tmux-style splits with Ctrl+W"

keybind = ctrl+w>v=new_split:right
keybind = ctrl+w>s=new_split:down
keybind = ctrl+w>h=goto_split:left
keybind = ctrl+w>l=goto_split:right
keybind = ctrl+w>j=goto_split:down
keybind = ctrl+w>k=goto_split:up
keybind = ctrl+w>z=toggle_split_zoom

See references/keybindings-and-input.md for full action catalog and key tables.

"Make Option key work in vim/zsh (macOS)"

macos-option-as-alt = left    # or true for both Option keys

"Set up a global drop-down terminal (Quake-style)"

keybind = global:super+grave=toggle_quick_terminal
quick-terminal-position = top
quick-terminal-autohide = true

global: requires Accessibility permission on macOS. Linux requires Wayland.

"Fix SSH showing 'unknown terminal type'"

Option A — enable SSH wrapping in shell integration:

shell-integration-features = cursor,sudo,ssh

Option B — copy terminfo to remote once:

infocmp -x ghostty | ssh remote-host -- "mkdir -p ~/.terminfo && tic -x -"

See references/shell-integration-features.md.

"Make transparent background"

background-opacity = 0.92
background-blur-radius = 20

Bind toggle: keybind = ctrl+shift+t=toggle_background_opacity

CLI Tools Decision Tree

User Says	Command
What options exist?	ghostty +show-config --default --docs
List my fonts	ghostty +list-fonts
List themes	ghostty +list-themes
What are my keybinds?	ghostty +list-keybinds
What version?	ghostty +version
Is my config valid?	ghostty +show-config 2>&1 | grep -i error

Or run bash scripts/show-config.sh help for an interactive wrapper.

What Belongs Where

Task	Reference
Font, window, cursor, scrollback, clipboard options	references/config-reference.md
Theme names, custom themes, background images, transparency	references/themes-and-appearance.md
Keybind syntax, all actions, key sequences, key tables	references/keybindings-and-input.md
Shell integration setup, SSH, $TERM, splits workflow	references/shell-integration-features.md
macOS vs Linux, migrating from kitty/iTerm2/WezTerm	references/platform-migration.md

Reference Files

File	Contents
references/config-reference.md	Config file locations and format, fonts (family/size/features/variation), window and appearance, cursor, scrollback, mouse, clipboard, shell command, notifications, custom shaders, CLI utilities
references/themes-and-appearance.md	Built-in theme system (500+ from iterm2-color-schemes), applying and listing themes, light/dark auto-switching, custom theme authoring, background images and transparency, color palette, cursor styles, alpha blending, community theme tools
references/keybindings-and-input.md	Keybind syntax, modifiers and trigger prefixes (all:/global:/unconsumed:/performable:), key sequences, key tables (modal mode), complete action catalog by category, tmux-style split recipes, quick terminal setup, font size bindings
references/shell-integration-features.md	Auto-injection for zsh/bash/fish/elvish, manual setup snippets, feature flags (cursor/sudo/ssh/title), SSH and sudo wrapping, env variables (GHOSTTY_RESOURCES_DIR/BIN_DIR), $TERM and terminfo, OSC sequences, command finish notifications, verification
references/platform-migration.md	macOS-specific config (option-as-alt, titlebar, global keybinds, AppleScript), Linux GTK (single-instance mode, Wayland/X11, adwaita feature matrix, FreeType rendering), community tools (ghostty.nvim, ghostty-ghost converter, ghostty.style), migration tables from iTerm2/kitty/alacritty/WezTerm

Scripts

Script	Usage
scripts/show-config.sh	bash show-config.sh <config|defaults|fonts|themes|keybinds|diff|search|version>