Claude Code is Anthropic's AI agent that runs directly in your terminal. Not an IDE extension, not a browser chat — a full command-line tool that reads your entire repository, understands the project architecture, makes coordinated changes across multiple files, and commits the result. Launch it with claude from any project folder.
This guide covers three installation methods for macOS, their differences, how to authenticate, configure your first project, and what to do when things go wrong. Valid for macOS 10.15 Catalina and later — Intel Mac to Apple Silicon.
Prerequisites
Claude Code requires a paid Anthropic account. The free Claude.ai plan doesn't work with Claude Code. Available options: Claude Pro — $20/month, covers most development tasks; Claude Max — $100 or $200/month, for intensive use with higher rate limits; Anthropic Console — API access with account balance, suitable for automation and CI/CD.
System requirements: macOS 10.15+, 4 GB RAM minimum (8 GB+ for comfortable work with large repositories), 200–300 MB free disk space. Git is recommended — Claude Code uses commit history to understand project context.
Check your macOS version:
sw_vers -productVersion
Method 1: Native Binary (Recommended by Anthropic)
This is the officially recommended approach. The native installer requires no Node.js, doesn't conflict with other packages, and auto-updates in the background.
Open Terminal (Spotlight → Terminal or Applications → Utilities → Terminal) and run one command:
curl -fsSL https://claude.ai/install.sh | bash
The script downloads a signed binary, installs it to ~/.local/bin/claude or ~/.claude/bin/claude, and automatically adds the path to ~/.zshrc (or ~/.bashrc depending on your shell).
After installation, restart your terminal or run:
source ~/.zshrc
Verify the installation succeeded:
claude --version
claude doctor
The claude doctor command diagnoses your configuration — checks PATH, permissions, authentication state, and MCP server health. Run it first whenever something feels off.
The macOS binary is signed by Anthropic PBC and notarized by Apple — no Gatekeeper warnings on launch.
Method 2: Homebrew
For those already using Homebrew who prefer managing tools through it:
brew install --cask claude-code
Homebrew installs Claude Code as a cask. It works correctly, but there's one downside: auto-updates don't work. New versions require manual installation:
brew upgrade claude-code
If you don't keep up with updates regularly, you'll find yourself on an outdated version within a few months. Inconvenient for active use.
Method 3: npm (Legacy, Still Works)
This method still works, but Anthropic officially marks it as deprecated. Use it only if you have a specific reason — for example, you need to pin a particular version or work in an environment where npm is the standard.
Requirement: Node.js 18 or higher. Check:
node --version
If Node.js isn't installed or the version is below 18, install via nvm (recommended) or from nodejs.org:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.zshrc
nvm install 22
nvm use 22
nvm (Node Version Manager) lets you maintain multiple Node.js versions and switch between them. Version 22 LTS is the current recommendation for Claude Code.
Install Claude Code globally:
npm install -g @anthropic-ai/claude-code
Important: never use sudo with this command. sudo npm install -g breaks permissions on the npm directory and creates security issues that are painful to clean up. If you see an EACCES error, configure npm to use a directory inside your home folder:
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
Then retry the installation without sudo.
Authentication
After installation by any of the three methods, run:
claude
Claude Code will try to open a browser for OAuth authentication through your Anthropic account. If the browser opens — log into your Claude.ai account and confirm access.
If the browser doesn't open automatically (headless environments, SSH, Docker) — use the --headless flag:
claude auth login --headless
The terminal displays a URL — copy it, open it in a browser on any device, authenticate, and paste the code back into the terminal.
The auth token is stored in ~/.claude/config.json (AES-256 encryption) and stays active for 30 days without use. If you're working with a direct API key:
export ANTHROPIC_API_KEY=sk-ant-...
Add this line to ~/.zshrc so the key loads automatically in every session.
Verify authentication:
claude doctor
The output should show: Authentication: ✓ Logged in.
First Launch
Navigate to your project folder and start Claude Code:
cd ~/Projects/my-project
claude
Claude Code analyzes the repository structure in 2–5 seconds (for projects under 50,000 files) and greets you with an interactive terminal interface. Ask questions about your code immediately.
A few commands to get started:
claude "explain the architecture of this project"
claude "find all error handling locations"
claude "add a unit test for the processPayment function"
For non-interactive use (scripts, CI/CD):
claude -p "check for SQL injection vulnerabilities in controllers/" --output-format json
Configuring CLAUDE.md
CLAUDE.md is a file in your project root that Claude Code reads on every launch. Use it to describe context the AI should know about your project: run commands, coding conventions, architectural decisions.
Create it in the project root:
nano CLAUDE.md
Commit CLAUDE.md to version control — this gives every team member the same context.
In monorepos, add CLAUDE.md to each subdirectory: root-level rules apply everywhere, subdirectory rules apply only when working in that directory.
Common Issues on macOS
command not found: claude after installation. PATH hasn't updated in the current terminal session. Restart Terminal or run source ~/.zshrc. If that doesn't help — check that ~/.zshrc contains the path export line (the installer adds it automatically, but may write to the wrong file if you have a non-standard shell configuration).
Gatekeeper blocks the launch. The native binary is Apple-notarized and shouldn't be blocked. If it is — you probably have an npm installation of an old version. Reinstall using the native method.
EACCES on npm install. Don't use sudo. Configure the npm prefix as described above, or switch to the native installer.
Slow start or hangs on project analysis. Large node_modules, a .git with extensive history, or monorepos with tens of thousands of files. Add .claudeignore to the project root (same syntax as .gitignore):
node_modules/
dist/
.next/
*.log
Authentication doesn't work. Run claude auth login --headless and authenticate manually via the browser.
Useful Links:
- Official Claude Code Documentation
- Claude Pro Subscription
- Anthropic Console (API keys)
- npm package @anthropic-ai/claude-code
FAQ:
Is Claude Code free? No. It requires a paid account: Claude Pro ($20/mo), Claude Max ($100–200/mo), or balance in Anthropic Console. The free Claude.ai plan doesn't grant access to Claude Code.
Is Node.js required for installation? Only for the npm method (deprecated). The native installer and Homebrew require no Node.js at all.
Does it work on Apple Silicon (M1/M2/M3/M4)? Yes, the native binary ships as arm64. Installs and runs natively without Rosetta 2.
How do I update Claude Code? The native installer updates automatically in the background. For Homebrew: brew upgrade claude-code. For npm: npm update -g @anthropic-ai/claude-code.
Can I use it with private repositories? Yes. Claude Code works locally with files on your computer. Only model requests go to Anthropic — not entire file contents, only the context you explicitly include in a query.