Claude Code turns your terminal into an AI pair-programming environment. Instead of copying code into a browser or switching between your IDE and a chat window, you run claude directly in your project directory — and get an assistant that already knows your codebase. It reads files, understands the structure, fixes bugs, writes tests, and makes commits.
Let's walk through how to install Claude Code on a Mac from scratch, the three installation methods, how to pick the right one, and what happens after your first claude.
What Is Claude Code
Claude Code is a CLI tool from Anthropic, the company behind the Claude language model. It runs locally in your terminal: bash, zsh, any compatible shell. When launched inside a project folder, the agent scans the repository, reads the directory structure and git history, and is then ready to answer questions about the code and make changes.
This isn't just a code chat. Claude Code can autonomously execute multi-step tasks: receive an assignment, locate the relevant files, write code, run tests, fix any errors that appear, and only then propose a commit. The developer approves, confirms, or asks for corrections at each step.
The current version is 2.x. Available on macOS (10.15+, Intel and Apple Silicon), Linux, and Windows via WSL.
What You Need Before Installing
A paid Anthropic account. The free Claude.ai plan doesn't work with Claude Code. You need one of the paid options:
- Claude Pro — $20/month. Enough for most developers: personal projects, freelance work, working with a single repository.
- Claude Max — $100 or $200/month. For those using Claude Code several hours a day or running it in CI/CD pipelines.
- Anthropic Console — direct API access. You pay per token with no fixed subscription. Good for automation and teams that want to manage usage through the API.
Hardware and OS. macOS 10.15 Catalina or newer. Works on Intel and Apple Silicon with no extra steps. Minimum 4 GB RAM; 8 GB+ recommended for comfortable work with large projects. Around 200–300 MB of disk space.
Git. Not strictly required, but without it Claude Code can't see commit history and loses part of the project context. Install via Xcode Command Line Tools:
xcode-select --install
Three Installation Methods
Method 1: Native Installer (One curl — Done)
Anthropic recommends this approach. No dependencies, no Node.js conflicts, background auto-updates without any action on your part. The binary is signed by Anthropic and notarized by Apple — Gatekeeper won't complain.
curl -fsSL https://claude.ai/install.sh | bash
The script installs the binary to ~/.local/bin/ and adds the path to ~/.zshrc. Once done:
source ~/.zshrc
claude --version
If you see a version number — installation succeeded. Next step: authentication.
Method 2: Homebrew
If you already use Homebrew to manage tools on your Mac:
brew install --cask claude-code
Works correctly, but auto-updates are disabled. New versions require a manual brew upgrade claude-code. If you tend to forget about updating tools, the native installer is more convenient.
Method 3: npm (Deprecated, Still Supported)
Anthropic continues to support npm installation but considers it deprecated. Use it only if you need to pin a specific version or work in an environment where npm is the standard.
Requirement: Node.js 18+. Install via nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.zshrc
nvm install 22 && nvm use 22
Then:
npm install -g @anthropic-ai/claude-code
No sudo rule: never write sudo npm install -g. It breaks permissions on the npm directory. If you see EACCES, configure the prefix instead:
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
Authentication
The first claude run in any directory opens a browser for OAuth authentication through your Anthropic account. Log in to your Claude.ai account, confirm — and the token is saved locally in ~/.claude/config.json.
The token stays active for 30 days without use. If you're in a browserless environment (remote server, Docker):
claude auth login --headless
The terminal shows a URL — open it manually, authenticate, and enter the code back in the terminal.
To work with an API key directly:
export ANTHROPIC_API_KEY=sk-ant-your-key
Add this to ~/.zshrc so the key loads automatically.
Run this to diagnose everything:
claude doctor
Shows: authentication status, version, PATH state, configuration issues. Run it first whenever something seems off.
First Project
Navigate to any folder with code:
cd ~/Projects/my-app
claude
Claude Code scans the repository in a few seconds and opens an interactive mode in the terminal. Start asking right away:
> how is authentication structured in this project?
> where are API errors handled?
> add logging to the createOrder function
For single tasks without the interactive mode:
claude -p "write unit tests for the payment.js module"
The CLAUDE.md File: Context That Sticks
Create a CLAUDE.md file in your project root — Claude Code reads it on every launch. Describe everything the agent should know: how to run the project, architectural decisions, coding conventions.
## How to run
- `npm run dev` — dev server on port 3000
- `npm test` — Jest tests
- `npm run lint` — ESLint
## Stack
- Next.js 15, App Router
- PostgreSQL + Prisma
- Auth: NextAuth.js
## Rules
- TypeScript strict, no `any`
- Server components by default, `use client` only when necessary
- Commit messages in English, imperative mood
Commit CLAUDE.md to the repository — all team members get the same context.
Common Issues
command not found: claude — PATH hasn't updated in the current terminal session. Run source ~/.zshrc or open a new terminal tab. If that doesn't help, check that ~/.zshrc contains the path to claude.
Gatekeeper blocks the launch — the native binary is Apple-notarized and shouldn't be blocked. If it is, you likely have an old npm version. Reinstall using the native installer.
Claude Code takes a long time to start — large project with node_modules or a heavy .git. Create .claudeignore in the root (same syntax as .gitignore) and exclude the noise:
node_modules/
dist/
build/
.next/
*.log
EACCES on npm install — don't use sudo. Configure the npm prefix: mkdir -p ~/.npm-global && npm config set prefix '~/.npm-global'.
Resources:
- Official Claude Code Documentation
- Claude Pro and Max Subscriptions
- Anthropic Console
- npm: @anthropic-ai/claude-code
FAQ:
Does Claude Code work on M1/M2/M3/M4?
Yes. The native binary is compiled for arm64 and runs natively without Rosetta 2.
Can I use the free Claude.ai plan?
No. Claude Code requires a paid plan — minimum Claude Pro at $20/month.
Is Node.js required?
Only for the npm installation method (deprecated). The native installer and Homebrew have no dependencies.
How do I update Claude Code?
The native installer updates automatically in the background. Homebrew — brew upgrade claude-code. npm — npm update -g @anthropic-ai/claude-code.
Does my code get sent somewhere?
Model requests go to Anthropic with the context you explicitly include in a query. Project files aren't transmitted automatically in full — only what the agent explicitly includes in a request when executing a task.
