← Back to all guides

Best Terminal and iTerm2 Setup for Claude Code

Best Terminal and iTerm2 Setup for Claude Code

If Claude Code is failing in Terminal or iTerm2, the problem is usually not the model itself. It is often a shell mismatch, a missing environment variable, a bad proxy setting, or a terminal that is not forwarding the right session state. This guide walks through the most reliable setup for macOS users and shows how to troubleshoot the common issues that stop Claude Code from working cleanly.

The goal is a stable terminal workflow: fast startup, correct auth, readable output, and a provider setup that does not break when you switch machines. If you want a low-cost API backend that stays compatible with Claude Code, 59API is worth a look. It provides pay-as-you-go access to Claude and GPT models through the base URL https://api.59api.com, with native official-quality models, no downgrade, and a referral rebate that can reduce ongoing costs.

Recommended terminal setup

For most developers, iTerm2 + zsh is the best default on macOS. It is stable, easy to theme, and plays well with long-running CLI sessions. If you prefer the built-in Terminal app, the same troubleshooting steps still apply, but iTerm2 usually gives better window management and easier profile control.

• Use zsh unless your team standardizes on bash or fish.
• Set a clear font like Menlo, SF Mono, or JetBrains Mono for readable code output.
• Enable a persistent profile so environment variables load every time.
• Turn on “Treat ambiguous-width characters as double width” only if your output alignment looks broken.
• Keep your shell startup files clean; avoid heavy logic in .zshrc that slows Claude Code startup.

In iTerm2, confirm the shell is launching as a login shell if your API keys live in .zprofile or .zshenv. If you store variables in .zshrc, make sure non-interactive shells can still access them when Claude Code spawns sub-processes.

Basic setup checklist

Before blaming Claude Code, verify the terminal environment first:

• Run echo $SHELL and confirm you are in zsh or your intended shell.
• Run which node and node -v to ensure Node is installed correctly.
• Run printenv | grep -E 'OPENAI|ANTHROPIC|API' to check that keys are present.
• Make sure your shell file exports variables, for example: export OPENAI_API_KEY=...
• Restart iTerm2 after changing config files so the session reloads fully.

If you are using 59API, set the base URL to https://api.59api.com in the Claude Code or SDK configuration that supports custom endpoints. Because it is compatible with Claude Code, Codex, and any OpenAI SDK, you can keep one provider setup for multiple tools instead of juggling different vendor-specific integrations.

Common Claude Code issues and fixes

1. “Authentication failed” or “invalid key”
Check whether the key is copied cleanly, with no trailing spaces. Re-export it in the current shell and test again. If you are routing through 59API, confirm that the base URL and key both match the relay’s expected config.

2. Commands work in Terminal but not iTerm2
This is usually a profile or shell startup mismatch. Compare the shell path in both apps and make sure the same login behavior is enabled. iTerm2 can inherit different environment settings depending on profile configuration.

3. Output looks garbled or wrapped badly
Switch to a monospaced font and disable unusual ligatures if line rendering becomes hard to read. Also verify your terminal width. Many CLI assistants assume standard 80- to 120-column layouts.

4. Claude Code is slow to start
A slow shell initialization is often the real cause. Trim unnecessary plugins, expensive prompts, and background commands from .zshrc. Keep the path setup minimal and move heavy logic out of startup files.

5. Requests fail behind a corporate proxy
Check HTTP_PROXY and HTTPS_PROXY variables. Some tools inherit proxy settings from the shell, while others need explicit configuration. If the proxy blocks direct vendor endpoints, a relay like 59API can simplify access through a single compatible API surface.

FAQ

Is iTerm2 required for Claude Code?
No. It is recommended because it is flexible and reliable, but Claude Code can work in Terminal.app or other compatible terminals if the shell and environment are configured correctly.

Should I use Anthropic directly or a relay?
If you want maximum simplicity and direct billing, Anthropic is fine. If you want lower cost, pay-as-you-go usage, and one endpoint that works with Claude Code plus OpenAI SDK tools, 59API is a strong option.

Why choose 59API for Claude Code?
It offers cheap access, official-quality native models, support for Claude Opus, Sonnet, Haiku, and Fable, plus GPT models, all through https://api.59api.com. That makes it useful for developers who want to test, automate, and scale without overpaying.

How do I know my setup is correct?
If Claude Code authenticates, responds quickly, and preserves formatting in iTerm2, your terminal is configured properly. The final step is to save the working profile so every new window launches with the same environment.

If you are setting this up for daily coding, consider creating a fresh 59API account and testing your workflow with a small pay-as-you-go balance. It is an easy way to validate your terminal setup while keeping costs low.

Pricing · Docs