Terminal & Ghostty setup

Claude Code runs in your terminal, so the terminal decides how good the experience feels. The right one gives you multi-line prompts, desktop notifications, and image paste out of the box.

Why the terminal matters

Three things separate a great Claude Code terminal from a frustrating one:

• Shift+Enter for multi-line prompts. You constantly write prompts spanning several lines. A terminal that sends Shift+Enter as a newline (instead of submitting) makes this effortless.
• Native desktop notifications. When Claude finishes a long task or needs your input, a real OS notification means you don't have to babysit the window.
• Image paste. Drop a screenshot straight into the prompt (a failing UI, a stack trace, a design) without saving a file first.
• Fast GPU rendering. Claude streams tokens quickly; a slow renderer stutters on long output.

Top terminals compared

Terminal	Platforms	Shift+Enter	Notifications	Image paste	Notes
Ghostty (recommended)	macOS, Linux	Native	Native	Ctrl+V	Zero-config, fast GPU rendering. Not over SSH.
iTerm2	macOS	Needs setup	Yes	Yes	Run /terminal-setup; set Option key to Esc+. Well documented.
WezTerm	macOS, Linux, Windows	Native	Yes	Yes	Built-in multiplexer, cross-platform.
Kitty	macOS, Linux	Native	Yes	Yes	Excellent on Linux.
Warp	macOS, Linux	—	No	—	Avoid: its block model fights streaming output; no native notifications.

TIP

On macOS in 2026, Ghostty is the easiest path: native Shift+Enter, native notifications, and a great default with almost no configuration.

Install Ghostty

brew install --cask ghostty

The bootstrap script ../../setup.sh installs Ghostty (plus JetBrains Mono) and writes the config below for you. To do it by hand, read on.

The recommended config

Config lives at ~/.config/ghostty/config. This is the exact block ../../setup.sh writes:

# ~/.config/ghostty/config — generated by claude-code-guide/setup.sh
# Catppuccin auto dark/light. Reload in Ghostty: Cmd+Shift+,

theme = dark:Catppuccin Mocha,light:Catppuccin Latte
font-family = JetBrains Mono
font-size = 14
font-thicken = true
background-opacity = 0.96
background-blur = 20
window-padding-x = 14
window-padding-y = 14
window-padding-balance = true
macos-titlebar-style = tabs
cursor-style = block
mouse-hide-while-typing = true
copy-on-select = clipboard

The theme line follows your macOS appearance: Catppuccin Mocha in dark mode, Catppuccin Latte in light mode.

Reload, themes, and the Title-Case gotcha

After editing the config, reload it in place with Cmd+Shift+, — no restart needed.

List every available theme:

ghostty +list-themes

WARNING

Theme-name gotcha (Ghostty 1.2.0+): theme names are Title Case with spaces, e.g. Catppuccin Mocha, not catppuccin-mocha. If a theme silently fails to apply, the name casing is almost always why. Always confirm the exact spelling with ghostty +list-themes.

Paste an image

Copy any image to the clipboard, then press Ctrl+V in the Claude Code prompt. Ghostty hands the image to Claude directly.

Tabs and splits

Action	Shortcut
New tab	Cmd+T
New split	Cmd+D
Reload config	Cmd+Shift+,

Edit long prompts in your editor

Wrote a long, multi-line prompt and want to fix something in the middle? You can't click to reposition the cursor in a terminal prompt — but you don't have to arrow-key back like a robot either. Press Ctrl+G in the Claude Code prompt and the current text opens in your $EDITOR, with full mouse support, undo, and multi-line editing. Save and close the file, and the edited prompt returns to Claude.

Set your editor once in ~/.zshrc. The --wait / -w flag is essential — it makes the editor block until you close the file, so Claude waits for you instead of thinking you're done immediately:

export EDITOR="subl --wait"   # Sublime Text
# export EDITOR="code -w"     # VS Code
# export EDITOR="vim"         # vim (already blocks)
# export EDITOR="nano"        # nano

TIP

If subl (or code) isn't on your PATH, symlink its CLI into a directory that is — e.g. ln -s "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" ~/.local/bin/subl. Then open a new terminal (or source ~/.zshrc) and restart claude so it picks up $EDITOR.

Next steps

• Run the one-command setup to install Ghostty and everything else in one go.
• Learn to monitor cost and rate limits once you're working.