Skip to content

terminal-and-ghostty.md

Latest commit

 

History

History
108 lines (77 loc) · 4.98 KB

terminal-and-ghostty.md

File metadata and controls

108 lines (77 loc) · 4.98 KB
Raw
title Terminal & Ghostty setup
description Why your terminal matters for Claude Code, a top-terminals comparison, and a full zero-config Ghostty setup with the recommended config.

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