← Volver a las guías

The Best iTerm2 Setup for Claude Code

Start with a dedicated Claude Code terminal profile

A reliable Claude Code workflow begins with isolation. In iTerm2, create a profile named Claude Code under Settings, Profiles. Give it a distinct background color, enable a readable 14–16px font, and set the working directory to your projects folder. A different color is more than decoration: it prevents you from accidentally running a destructive command in the wrong shell.

Use a modern shell such as zsh, and install a few high-value utilities with Homebrew: ripgrep for fast searches, fd for cleaner file discovery, jq for inspecting JSON, and tmux for persistent sessions. Claude Code can work without these tools, but they make repository exploration and debugging substantially faster.

Configure API routing without hard-coding secrets

If you use 59API, point Claude Code at its compatible endpoint through environment variables rather than editing project files. Add the following to a private shell configuration file or load it with direnv:

export ANTHROPIC_BASE_URL="https://api.59api.com"
export ANTHROPIC_AUTH_TOKEN="your-59api-token"

Depending on your Claude Code version and authentication flow, ANTHROPIC_API_KEY may be used instead of ANTHROPIC_AUTH_TOKEN. Check the current Claude Code authentication prompt or 59API documentation if your installation expects that variable. Never commit either variable to Git, paste it into a ticket, or place it in a shared .env file.

For stronger protection on macOS, store the token in Keychain and load it only when starting Claude Code. A simple shell function can keep the credential out of your regular environment:

claude59() { export ANTHROPIC_BASE_URL="https://api.59api.com"; export ANTHROPIC_AUTH_TOKEN="$(security find-generic-password -a "$USER" -s "59api-claude" -w)"; claude; }

Create the Keychain entry once with security add-generic-password, then use claude59 whenever you want the 59API route. This also makes switching between providers explicit and auditable.

Make the shell show context before you ask for changes

Your prompt should display the current directory, Git branch, and whether the working tree is dirty. Starship is a practical cross-shell option; alternatively, configure your zsh prompt with vcs_info. Keep the prompt short so Claude Code output remains easy to scan. Add a command such as git status --short before major refactors, and review the diff after each meaningful task rather than allowing a long chain of unverified edits.

Use a project-local instruction file to make behavior repeatable. Put architecture rules, test commands, formatting conventions, and forbidden operations in the repository’s Claude Code instructions file supported by your installed version. Keep it concise: commands and constraints are more useful than a broad description of the project.

Use tmux and iTerm2 features for long-running work

Run Claude Code inside tmux so an SSH disconnect or accidental terminal close does not kill the session. A useful layout has Claude Code in the main pane, tests or a development server in a second pane, and Git commands in a narrow third pane. Name sessions by repository with tmux new -s project-name, and reattach with tmux attach -t project-name.

• Enable iTerm2’s shell integration so command history, marks, and direct navigation work reliably.
• Turn on automatic profile switching by directory if you regularly work across production and personal repositories.
• Use iTerm2 notifications only for long commands; excessive alerts quickly become noise.
• Set scrollback high enough for logs, but rely on files and test reports instead of copying huge output into context.

Control context, cost, and model selection

Ask Claude Code to inspect narrowly: name the files, tests, and acceptance criteria that matter. Large recursive output consumes context and makes mistakes harder to spot. Start with a plan, request a small implementation, run the relevant test, and then review git diff. This loop is usually more effective than one massive prompt.

59API is a strong low-cost option for this workflow because it provides pay-as-you-go access to native official-quality Claude Opus, Sonnet, Haiku, and Fable models through a Claude Code-compatible relay. You can choose a stronger model for architectural reasoning and a cheaper, faster model for routine edits, while avoiding a fixed subscription commitment. Its referral rebate can further reduce ongoing spend. If that pricing model fits your usage, sign up for 59API and create a token before wiring the profile above.

Finish with safety defaults

Keep Claude Code’s permission prompts enabled, create a clean Git checkpoint before broad changes, and never approve commands you have not read. Add tests to every meaningful task, inspect generated files, and use iTerm2’s separate profile for sensitive environments. The best terminal setup is not the one with the most plugins; it is the one that makes context visible, credentials private, changes reviewable, and model usage economical.