Ghostty Best Practices

macOS-only, tuned for tmux + vim workflows and heavy Claude Code usage (long outputs, splits, tabs, logs). Opinionated, minimal, and easy to maintain.

macOS tmux vim Claude Code single-page
Report

TL;DR

Do this first (15 minutes)

  • Keep config tiny: theme + font + padding + scrollback + a few cmd/opt keybinds.
  • Use Ghostty introspection: ghostty +list-fonts, ghostty +list-themes, ghostty +show-config --default --docs.
  • Split your config using config-file + optional includes (?work.ghostty).

Don’t do this

  • Don’t bind lots of Ctrl combos (tmux/vim/TUIs will suffer). Prefer ⌘/⌥.
  • Don’t over-tune: Ghostty aims to be great with defaults; if something feels “necessary”, consider filing a discussion.

Principles (why this guide looks like this)

  • Defaults-first. Ghostty explicitly encourages trying it with no config and only changing subjective preferences (theme/font). If you need non-subjective knobs, it might be a product default opportunity.
  • tmux is the window manager. Let tmux own pane management and terminal app ergonomics; let Ghostty own macOS windowing, tabs, and fast splits when you’re not inside tmux.
  • Claude Code = long output. Optimize for scrollback, readability, and quick “open new surface” patterns.

Config: file locations, syntax, reload

Config path
On macOS, Ghostty loads config.ghostty (and legacy config) from ~/Library/Application Support/com.mitchellh.ghostty/ and also supports the XDG path (~/.config/ghostty/). If multiple exist, later files override earlier ones.
Syntax
Simple key = value. Keys are case-sensitive and typically lowercase. Values may be quoted or unquoted.
Modular
Use config-file = … to include other config files; prefix with ? to make includes optional (great for machine/work overrides).
Reload
Default reload is ⌘+⇧+, on macOS. Not every option hot-reloads, but many do.

Introspection commands (use these constantly)

ghostty +list-fonts
ghostty +list-themes
ghostty +show-config --default --docs

Treat these as your “safe API” for config exploration: they prevent typos and help you stay aligned with your installed version.

Keybindings (tmux/vim-safe defaults)

Guideline: avoid binding Ctrl combos that are commonly used by terminal apps and tmux. Prefer ⌘ and ⌥ on macOS.

Recommended Ghostty-level bindings

  • New tab: ⌘+T
  • Next/prev tab: ⌘+] / ⌘+[
  • Split right / down: ⌘+D / ⌘+⇧+D
  • Reload config: keep default ⌘+⇧+,

Let tmux own these

  • Pane navigation/resizing
  • Split semantics while inside a tmux session
  • Copy mode + selection workflows

Reason: tmux gives consistent behavior across SSH, local shells, and different terminals.

Fonts & fallbacks (CJK/emoji/symbols)

Ghostty supports repeating font-family multiple times to build a fallback list. This is the clean way to handle mixed glyph coverage (e.g., English code + Chinese + symbols). Ghostty also documents emoji defaults (macOS uses Apple Color Emoji by default unless overridden).

Practical fallback chain (example)

font-family = "JetBrains Mono"
font-family = "PingFang SC"         # CJK fallback
# Optional: if you want emoji to come from a specific font
# font-family = "Apple Color Emoji"

Use ghostty +list-fonts to confirm the exact names installed on your machine.

Claude Code workflow tips

  • Scrollback matters. Increase scrollback-limit so long Claude outputs and diffs don’t get truncated.
  • One “scratch” surface. Keep one Ghostty tab/pane as a scratchpad for Claude Code, and do actual work inside tmux sessions (per repo).
  • Fast context switching. Use tabs for “projects” and tmux windows for “tasks”.

Starter config (copy/paste)

Drop this into ~/Library/Application Support/com.mitchellh.ghostty/config.ghostty (or XDG). It’s conservative and tmux/vim-safe.

# ===== Ghostty: macOS + tmux + vim + Claude Code =====

# Theme & font
theme = "TokyoNight"
font-family = "JetBrains Mono"
font-size = 14

# Readability
window-padding-x = 10
window-padding-y = 10
window-padding-balance = true

# Claude Code / logs (tune up/down)
scrollback-limit = 20000000

# Tabs (macOS-friendly)
keybind = cmd+t=new_tab
keybind = cmd+]=next_tab
keybind = cmd+[=previous_tab

# Splits (useful outside tmux)
keybind = cmd+d=new_split:right
keybind = cmd+shift+d=new_split:down

# Optional: config layering
# config-file = ?work.ghostty
# config-file = ?machine.ghostty

Common pitfalls

  • Typos in theme/font names → always validate with +list-themes / +list-fonts.
  • Too many Ctrl keybinds → breaks TUIs and tmux muscle memory.
  • Expecting all settings to hot-reload → some options require a full app restart (the reference docs call these out).

References

Generated for a practical terminal workflow. If you want, we can add a second page for “tmux+vim recommended keybind map” and a section on shell integration once you confirm your shell (zsh/fish) and whether you use iTerm-style copy mode.