# Ghostty Configuration Personal [[Ghostty]] 1.2.3 terminal emulator setup on macOS. GPU-accelerated, minimal config, ==Catppuccin Mocha== theme to match [[Tmux Configuration|tmux]] and [[Neovim Configuration|Neovim]]. Config file: `~/.config/ghostty/config` > [!info] What is Ghostty? > Ghostty is a cross-platform, GPU-accelerated terminal emulator built by Mitchell Hashimoto (HashiCorp co-founder). It uses Metal on macOS for rendering, supports modern terminal features like OSC 52 clipboard, shell integration, and has built-in themes. Config is a flat key-value format (no TOML/YAML/JSON) — settings apply on save, no restart needed. ## Key Settings | Setting | Value | Why | |---------|-------|-----| | Font | `JetBrainsMono Nerd Font Mono` | Icons for neo-tree, lualine, which-key | | Font size | 14 | Comfortable default | | Theme | Catppuccin Mocha | Matches tmux and Neovim | | Window padding | 4px | Slight breathing room | | Cursor | Block, no blink | Visible and still | | Shell integration | zsh | Prompt markers, command tracking | | Clipboard | Read + write + copy-on-select | Seamless clipboard access | | Mouse | Hide while typing | Less distraction | | `unfocused-split-opacity` | `0.85` | Dims inactive cmux splits to show focus | | `split-divider-color` | `#585b70` | Catppuccin Mocha surface2 — themed divider | | `font-feature = calt` | enabled | JetBrains Mono programming ligatures | | `font-feature = liga` | enabled | Standard ligature support | | `font-thicken` | `true` | Better rendering on Retina displays | | `macos-titlebar-style` | `hidden` | cmux sidebar replaces titlebar, reclaims 28px | | `window-padding-balance` | `true` | Centers content with asymmetric padding | | `window-padding-color` | `extend` | Background extends into padding | | `link-url` | `true` | Clickable URLs in terminal output | ## Config File The full config at `~/.config/ghostty/config`: ```ini # --- Font --- font-family = JetBrainsMono Nerd Font Mono font-size = 14 # --- Theme --- theme = Catppuccin Mocha # --- Split Pane Styling (cmux inherits these) --- unfocused-split-opacity = 0.85 split-divider-color = #585b70 # --- Typography --- font-feature = calt font-feature = liga font-thicken = true adjust-cell-height = 2 # --- Window --- window-padding-x = 4 window-padding-y = 4 window-decoration = true window-padding-balance = true macos-titlebar-style = hidden window-padding-color = extend # --- Cursor --- cursor-style = block cursor-style-blink = false # --- Shell integration --- shell-integration = zsh shell-integration-features = cursor,sudo,title,path # --- Clipboard --- clipboard-read = allow clipboard-write = allow copy-on-select = clipboard # --- Mouse --- mouse-hide-while-typing = true # --- Link detection --- link-url = true ``` > [!tip] Config Format > Ghostty uses a flat `key = value` format with no file extension. Comments start with `#`. Changes are picked up on save — no restart needed. ## Useful Commands | Command | Description | |---------|-------------| | `ghostty +list-fonts` | List all available fonts | | `ghostty +list-fonts --family="JetBrains"` | Search fonts by family | | `ghostty +list-themes` | List built-in themes | | `ghostty +list-keybinds` | Show current keybinds | | `ghostty +list-keybinds --default` | Show default keybinds | | `ghostty +validate-config` | Validate config file | | `ghostty +version` | Show version | | `man ghostty` | Full documentation | ## Built-in Keybindings | Keys | Action | |------|--------| | `Cmd+N` | New window | | `Cmd+T` | New tab | | `Cmd+W` | Close tab | | `Cmd+D` | Split right | | `Cmd+Shift+D` | Split down | | `Cmd+]` / `Cmd+[` | Next / previous split | | `Cmd+Shift+Enter` | Toggle fullscreen | | `Cmd+,` | Open config (if editor is set) | | `Cmd+Shift+,` | Reload config | | `Cmd+C` | Copy | | `Cmd+V` | Paste | > [!note] tmux Prefix > `Ctrl+Space` is **not** bound by Ghostty by default, so the tmux prefix passes through without any additional configuration. ## Custom Keybindings Ghostty keybindings that send sequences to tmux (pass-through pattern): | Keys | Sends | Action | |------|-------|--------| | `Cmd+X` *(selection only)* | Copy to clipboard | Conditional: copies when text is selected, passes `Ctrl+X` otherwise | | `Shift+Arrow` *(no selection)* | Pass-through to TUI | Allows Claude Code / Neovim to receive shift+arrow without triggering Ghostty selection | | `Cmd+Shift+E` | `\x00e` (prefix + e) | Open `$EDITOR` in a tmux split for the cf codebase | | `Cmd+Shift+O` | `\x00o` (prefix + o) | Open VS Code / Zed for the cf codebase | > [!info] tmux prefix passthrough > `\x00` is NUL (Ctrl+Space) — the tmux prefix key. `text:\x00e` sends NUL followed by `e`, which tmux interprets as `prefix + e`. This is how Ghostty shortcuts map to tmux keybindings without a separate tmux plugin. The `Cmd+Shift+E` / `Cmd+Shift+O` shortcuts require the [[Claude Focus Workflow|cf]] workflow — they invoke `cf-open-editor` via the tmux keybinding and only work inside a cf session. ## Font Setup The ==JetBrains Mono Nerd Font== is required for Neovim icons to display correctly. It was installed via: ```bash brew install --cask font-jetbrains-mono-nerd-font ``` To verify the font is available: ```bash ghostty +list-fonts | grep "JetBrains" ``` The Nerd Font variant (`Mono`) is important — it uses single-width glyphs for icons, preventing alignment issues in terminal UIs. ## Shell Integration Ghostty's shell integration for zsh provides: - **Prompt marking**: Ghostty knows where each command starts/ends - **Semantic prompts**: Visual distinction between input and output - **Command tracking**: Ghostty can report the last command's exit status - **Cursor positioning**: Jump between prompts with keybinds The integration is automatic — Ghostty injects a small zsh hook on startup. No `.zshrc` changes needed. ## cmux Integration [[cmux Configuration|cmux]] reads this config file directly — every setting here applies to cmux surfaces too. Key settings that specifically affect cmux: - `unfocused-split-opacity = 0.85` — dims inactive cmux workspace splits - `split-divider-color = #585b70` — themed divider between cmux panes - `macos-titlebar-style = hidden` — cmux's workspace sidebar replaces the macOS titlebar ## Theme Consistency ==Catppuccin Mocha== is configured across all tools for a unified visual experience: | Tool | Config Location | Setting | |------|----------------|---------| | **Ghostty / [[cmux Configuration\|cmux]]** | `~/.config/ghostty/config` | `theme = Catppuccin Mocha` | | **[[Tmux Configuration\|tmux]]** | `~/.tmux.conf` | `@catppuccin_flavor 'mocha'` | | **[[Neovim Configuration\|Neovim]]** | `~/.config/nvim/init.lua` | `flavour = 'mocha'` | Ghostty includes Catppuccin as a built-in theme (no plugin needed). Available flavors: Latte, Frappe, Macchiato, Mocha. ## True Color Verification ```bash # Should show a smooth orange gradient (not banded) printf "\x1b[38;2;255;100;0mTRUECOLOR\x1b[0m\n" ``` If the text appears orange, true color is working. Ghostty supports true color natively — no terminal override needed.