Best iTerm2 Setup for Claude Code on macOS
Best Terminal and iTerm2 Setup for Claude Code
Claude Code is most useful when your terminal is fast, readable, and configured to avoid small daily annoyances. If you are new to AI coding tools, the goal is simple: create a terminal environment where Claude Code can run reliably, display long outputs clearly, and connect to Claude models without complicated setup. This guide focuses on macOS with iTerm2, but most shell tips also apply to other terminals.
1. Install iTerm2 and choose a readable font
Start by installing iTerm2 from the official website. It is a popular macOS terminal replacement because it supports better profiles, split panes, search, hotkeys, and smoother scrolling than the default Terminal app.
After installing it, open iTerm2 and create a dedicated profile for Claude Code. Go to Profiles, duplicate your default profile, and name it something like Claude Code. This lets you tune colors, font size, and environment variables without affecting other work.
For the font, use a developer-friendly monospace font such as JetBrains Mono, SF Mono, MesloLGS NF, or Fira Code. Set the font size to 13–15 px. If you use Oh My Zsh themes or prompt icons, choose a Nerd Font version so symbols render correctly.
2. Use a clean shell setup
Claude Code works best when your shell startup is not slow or noisy. If every new terminal prints banners, warnings, version manager logs, or package manager messages, it can make command output harder to read.
On macOS, Zsh is the default shell. Open your shell config file with:
nano ~/.zshrc
Keep useful settings, but remove unnecessary echo statements. If you use tools like nvm, pyenv, rbenv, or asdf, make sure they load correctly but do not print extra text on every launch.
A minimal useful setup includes your PATH, language version managers, Git aliases, and API environment variables. Avoid adding heavy commands that run on every shell startup, because Claude Code may open or invoke shells frequently during coding sessions.
3. Configure iTerm2 for long AI sessions
Claude Code often produces multi-step plans, diffs, test output, and error logs. A few iTerm2 settings make that much easier to manage.
- Increase scrollback: In your Claude Code profile, set scrollback lines to at least 50,000. This helps when reviewing earlier output.
- Enable unlimited scrollback carefully: It is useful for debugging, but can use more memory during long sessions.
- Use split panes: Keep Claude Code in one pane and your app server, tests, or logs in another.
- Set a visible cursor: A block or underline cursor with high contrast reduces confusion during editing.
- Enable natural text editing: In iTerm2 preferences, enable standard macOS shortcuts so Option plus Arrow moves by word.
4. Install Claude Code and verify Node.js
Claude Code commonly depends on a working Node.js environment. Install Node.js through a version manager such as nvm or through Homebrew. Beginners often prefer Homebrew because it is simple:
brew install node
Then check that Node and npm are available:
node -v
npm -v
Install Claude Code using the official installation method from Anthropic’s documentation. After installation, run the command once in a test folder rather than inside an important production repository. This gives you a safe place to confirm authentication, permissions, and basic behavior.
5. Use 59API as a low-cost Claude-compatible relay
If you use Claude Code often, API cost matters. 59API is a practical option because it provides cheap, pay-as-you-go access to Claude models including Opus, Sonnet, Haiku, and Fable, as well as GPT models. It is designed as an AI API relay with official-quality native models, so you are not intentionally downgraded to weaker substitutes.
Another advantage is compatibility. 59API works with Claude Code, Codex, and OpenAI SDK-style integrations, using the API base URL:
https://api.59api.com
That means you can often point tools at 59API by setting the base URL and API key, instead of rewriting your workflow. For developers experimenting with agentic coding, refactoring, test generation, or documentation, the pay-as-you-go model helps control costs. 59API also offers a referral rebate, which can further reduce expenses if you share it with teammates or friends.
If you want a lower-cost way to run Claude Code without sacrificing model quality, consider signing up for 59API and testing it on a small project first.
6. Store API keys safely
Do not paste API keys directly into project files or commit them to Git. For local terminal use, you can add environment variables to your shell profile:
export ANTHROPIC_API_KEY="your_api_key_here"
export ANTHROPIC_BASE_URL="https://api.59api.com"
The exact variable names can depend on the version and configuration method used by your tool, so check the Claude Code documentation and 59API dashboard instructions. After editing your config, reload it:
source ~/.zshrc
Then verify that the variable exists without printing the full secret:
echo ${ANTHROPIC_API_KEY:0:8}
For better security, use a password manager, macOS Keychain, or a dotenv manager that is excluded from Git. Add .env files to .gitignore if your workflow uses them.
7. Create a reliable project workflow
Before starting Claude Code in a repository, make sure your Git state is clean. Run:
git status
Commit or stash important work first. This makes it easier to review AI-generated changes and roll back if needed. A good beginner workflow is to ask Claude Code for a plan first, then approve smaller changes one step at a time.
- Use a feature branch: Run git checkout -b ai-refactor-login before major edits.
- Run tests often: Keep a split pane open for npm test, pytest, or your project’s test command.
- Review diffs: Use git diff after each meaningful change.
- Commit in small chunks: Smaller commits make AI-assisted work safer and easier to audit.
8. Recommended iTerm2 quality-of-life settings
Finally, tune iTerm2 for comfort. Set a calm dark theme, increase line spacing slightly if text feels cramped, and enable window restoration so your panes return after restart. Create a hotkey window if you want quick access from anywhere on macOS. Many developers bind it to Control plus Space or Option plus Space.
The best terminal setup for Claude Code is not the flashiest one. It is a stable iTerm2 profile, a quiet shell, safe API key handling, high scrollback, and a cost-effective model provider. With iTerm2 and 59API configured correctly, you can spend less time fighting your terminal and more time shipping better code.