By Avinash, GenAI Practice Lead | Part 1 | Part 2 | Part 3 | Part 4 | Part 5 of 6

The terminal environment around Claude Code matters as much as Claude Code itself. You spend hours in this environment — the less friction it has, the more thinking you can direct at the actual work.

This part covers everything outside Claude Code: iTerm2, tmux, starship, fzf, and zsh plugins.

iTerm2

Replace macOS Terminal with iTerm2. The reasons that matter for this setup specifically are true 24-bit color rendering (ANSI color gradients in the statusline render correctly), better escape code support (the blinking compaction warning needs this), and mouse support in tmux.

brew install --cask iterm2

Two settings to configure immediately after installing:

Font — install JetBrains Mono Nerd Font for starship icons and powerline segments:

brew install --cask font-jetbrains-mono-nerd-font

Then in iTerm2: Settings → Profiles → Text → Font → set to JetBrainsMono Nerd Font, size 13.

Terminal type — in iTerm2: Settings → Profiles → Terminal → Report Terminal Type → set to xterm-256color.

Color theme — download and import the tokyo-night theme:

curl -L -o ~/Downloads/tokyo-night.itermcolors "https://raw.githubusercontent.com/folke/tokyonight.nvim/main/extras/iterm/tokyonight_night.itermcolors"

Then Settings → Profiles → Colors → Color Presets → Import → select the file → apply.

tmux

tmux is a terminal multiplexer. For Claude Code development the value is twofold: persistent sessions that survive terminal restarts, and multiple panes visible simultaneously without switching tabs.

brew install tmux

My standard 3-pane layout:

┌─────────────────────┬──────────────┐
│                     │  Logs/Watch  │
│    Claude Code      ├──────────────┤
│                     │     Git      │
└─────────────────────┴──────────────┘

Claude Code runs in the large left pane. Test output or log watching runs top right. Git and manual commands run bottom right. Everything visible at once — no tab switching mid-flow.

Essential config — add to ~/.tmux.conf:

set -g mouse on              # trackpad scrolling
set -g history-limit 50000   # large scrollback buffer
set -sg escape-time 0        # no delay for escape key — important for Claude Code

Session persistence — install tmux-resurrect and tmux-continuum:

git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

Add to ~/.tmux.conf:

set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'
set -g @continuum-restore 'on'
set -g @resurrect-capture-pane-contents 'on'
run '~/.tmux/plugins/tpm/tpm'

Press Ctrl+B then I inside tmux to install plugins. Save layout with Ctrl+B then Ctrl+S. After this, closing iTerm2 and reopening it restores your exact layout — pane positions, working directories, and running processes.

Starship Prompt

The default macOS prompt tells you almost nothing. Starship shows git branch, git status, Python version, and time directly in your prompt:

ocr-eval-framework on  main [x!?] via 🐍 v3.12.9  18:43

The [x!?] git status indicators: x = staged changes, ! = unstaged modifications, ? = untracked files. At a glance you know your exact repo state without running git status.

brew install starship
starship preset tokyo-night -o ~/.config/starship.toml
echo 'eval "$(starship init zsh)"' >> ~/.zshrc
source ~/.zshrc

fzf

fzf replaces linear Ctrl+R command history search with an interactive fuzzy finder. Type any fragment of a previous command and it filters in real time across your entire history. For long evaluation commands with specific flags you ran three sessions ago, this is invaluable.

brew install fzf
$(brew --prefix)/opt/fzf/install  # say y to all three prompts
source ~/.zshrc

Three shortcuts now available:

• Ctrl+R — fuzzy search command history
• Ctrl+T — fuzzy search files, paste path to prompt
• Alt+C — fuzzy search directories and cd into selected

zsh Plugins

Two additions that change daily terminal use immediately:

zsh-autosuggestions shows previous commands in grey as you type based on history. Right arrow to accept the suggestion. After a day of use your muscle memory adapts and you stop retyping long paths from scratch.

zsh-syntax-highlighting colors commands green (valid) or red (invalid) as you type. Catches typos before you press Enter.

brew install zsh-autosuggestions zsh-syntax-highlighting
echo 'source /opt/homebrew/share/zsh-autosuggestions/zsh-autosuggestions.zsh' >> ~/.zshrc
echo 'source /opt/homebrew/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh' >> ~/.zshrc
source ~/.zshrc

The Full Visual Stack

With everything configured, your terminal looks like this:

• Dark navy tokyo-night background in iTerm2
• JetBrains Mono Nerd Font rendering icons cleanly
• tmux status bar at the bottom showing session name and time
• Starship prompt showing directory, git branch, git status, Python version
• Claude Code statusline above the prompt showing tokens, cost, rate limits
• Grey autosuggestions completing commands as you type
• Green/red syntax highlighting on every command

Every layer of information has a deliberate place. Nothing is decorative.

All configuration files are at https://github.com/ai-with-avinash/claude-code-best-setup.

← Back to Part 4 | Continue to Part 6 → Dotfiles and Wrap-up