Claude Code is Anthropic’s agentic coding tool that lives in your terminal. Unlike copy-paste AI assistants, it reads your codebase, understands project context, writes multi-file edits, runs tests, manages Git workflows, and submits PRs, all through natural language.

This guide covers everything from system requirements to your first coding session, with platform-specific instructions for macOS, Windows, and Linux.

System Requirements

Before you start, make sure your machine meets these requirements:

RequirementMinimumRecommended
OSmacOS 10.15+ / Windows 10+ / Linux (Ubuntu 18.04+)Latest stable release
RAM4 GB16 GB
Disk500 MB free1 GB free
NetworkInternet connectionStable broadband
Node.jsNot required (native installer)Only for legacy npm method

Step 1: Install Claude Code

The native installer is self-contained, no Node.js, no package manager dependencies. It auto-updates in the background.

macOS / Linux / WSL:

curl -fsSL https://claude.ai/install.sh | bash

macOS via Homebrew:

brew install --cask claude-code

Homebrew offers two casks: claude-code (stable, ~1 week behind) and claude-code@latest (bleeding edge). Homebrew versions don’t auto-update — run brew upgrade claude-code periodically.

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Windows WinGet:

winget install Anthropic.ClaudeCode

Tip: If you see The token '&&' is not a valid statement separator, you’re in PowerShell — use the irm command instead. If you see 'irm' is not recognized, you’re in CMD — use the curl command.

Option B: npm (Legacy)

If your workflow specifically requires npm:

npm install -g @anthropic-ai/claude-code

This requires Node.js 18.0+. We recommend migrating to the native installer when possible.

Migrating from npm to Native

Already on npm? Migration is one command:

claude install

This automatically downloads the native binary, migrates your config, and replaces the npm installation. Your ~/.claude/settings.json and project .claude/ directories are preserved.

Step 2: Verify Installation

claude --version

You should see the current version printed to your terminal. If this works, Claude Code is installed correctly.

Step 3: Configure Authentication

Claude Code requires one of these authentication methods:

claude config

This opens a one-time OAuth flow. Sign in with your Claude Pro or Claude Max account, and you’re set.

Option 2: API Key (Pay-Per-Use)

Get your key from console.anthropic.com, then:

export ANTHROPIC_API_KEY="your-api-key-here"

Make it persistent by adding this line to your shell profile:

# For Bash
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

# For Zsh
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

API vs Claude Max: Which Should You Choose?

FactorAPI (Pay-Per-Use)Claude Max Subscription
BillingPer tokenFixed monthly
Best forOccasional useDaily coding
RiskCosts can spikePredictable
RecommendationStart with ~$20 to testSwitch if you use CC 2+ hours/day

Pro tip: If you plan to use Claude Code for multiple hours daily or on large codebases, the Claude Max subscription is almost always more economical.

Step 4: Choose Your Model

Claude Code supports multiple models. Set your preferred model via environment variable:

# Best coding model — recommended for daily use
export ANTHROPIC_MODEL="claude-sonnet-4-6"

# Maximum capability for complex architecture
export ANTHROPIC_MODEL="claude-opus-4-6"

# Budget option (limited — see caveats below)
export ANTHROPIC_MODEL="claude-3-5-haiku-20241022"

Or specify per-session:

claude --model claude-sonnet-4-6

Model Comparison

ModelBest ForSpeedCostQuality
Sonnet 4.6Daily coding, multi-file editsFast$$4/5
Opus 4.6Architecture, complex debuggingSlower$$$$5/5
Haiku 3.5Simple single-file editsFastest$2/5

** Haiku limitations:** Struggles with multi-step planning, large codebases, and complex frameworks. Only use for quick syntax fixes or learning the basics.

Step 5: VS Code Integration

  1. Open VS Code → Extensions (Cmd+Shift+X / Ctrl+Shift+X)
  2. Search “Claude Code” → Install
  3. Click the Spark icon in the sidebar to open Claude Code
  4. Requires VS Code 1.98.0+

Features you get:

  • Inline diffs — see changes before accepting
  • Plan mode — review Claude’s plan before execution
  • Auto-accept — optionally auto-apply safe edits
  • File picker — Cmd+Option+K (Mac) or Alt+Ctrl+K (Windows/Linux) to add file context
  • Conversation history — resume past sessions

JetBrains Plugin

Search “Claude Code” in the JetBrains Marketplace, install, and restart your IDE. Supports IntelliJ IDEA, PyCharm, WebStorm, and more.

Terminal Integration

For a pure terminal workflow, simply run claude in your project directory:

cd your-project
claude

Step 6: Your First Session

Go to any project directory and start Claude Code:

cd ~/projects/my-app
claude

Try these starter prompts to get a feel for the tool:

# Explore the codebase
"explain the architecture of this project"

# Make a real change
"add input validation to the signup form"

# Run tests
"write tests for the auth module, run them, and fix any failures"

# Git workflow
"commit my changes with a descriptive message"

Windows-Specific Tips

Native vs WSL

Claude Code now works natively on Windows — no WSL required. But if you prefer a Linux environment:

# Install WSL2
wsl --install -d Ubuntu

# Optimize memory usage
# Create %USERPROFILE%\.wslconfig:
[wsl2]
memory=8GB
processors=4
swap=2GB

Git for Windows

Install Git for Windows for the best experience — it provides Claude Code with the Bash tool. Without it, Claude Code falls back to PowerShell.

Windows Terminal provides the best experience for Claude Code on Windows — tabs, themes, GPU rendering, and full Unicode support.

What Claude Code Can Do

Now that you’re set up, here’s what you can accomplish:

  • Build features — describe what you want, Claude writes the code across multiple files
  • Fix bugs — paste an error message, Claude traces it through your codebase
  • Automate tedious work — write tests, fix lints, resolve merge conflicts, update deps
  • Git workflow — create branches, write commits, open PRs
  • Use MCP — connect to Jira, Slack, Google Drive, or any MCP-compatible tool
  • Run agent teams — spawn sub-agents for parallel work on different components
  • Schedule tasks — automate recurring work like nightly CI analysis or weekly dep audits

Troubleshooting

ProblemSolution
command not found: claudeRestart your terminal or re-run the installer
Authentication failsCheck your API key or re-run claude config
Slow performance on WindowsEnsure Git for Windows is installed
Node.js version errors (npm)Upgrade to Node.js 18+ or switch to native installer
WSL: can’t access Windows filesUse /mnt/c/ paths instead of C:\

Gotchas I Hit During Setup

I’ve installed Claude Code on three machines now, and each one had at least one surprise. The most common one — and I hit it every time — is command not found right after installation. The installer adds claude to your PATH, but the current terminal doesn’t pick it up. I wasted 15 minutes the first time convinced something was broken. Just close and reopen your terminal.

On my Windows machine running WSL2, npm install -g failed with EACCES permission errors. The fix was simple (npm config set prefix '~/.npm-global') but the real trap is that WSL can silently pick up your Windows Node.js instead of the Linux one. If which node returns something starting with /mnt/c/, that’s your problem — you need a Linux-native Node installation.

My Linux VPS was running Node 16 (Ubuntu 22.04 default), which is too old. I wish I’d skipped npm entirely and used the native installer (curl -fsSL https://claude.ai/install.sh | bash) from the start — it bundles its own runtime and avoids the version issue completely. If you’re setting up a fresh machine, go native. If anything feels off after install, claude doctor prints a diagnostic that catches most issues.

Next Steps

You’re now set up with Claude Code. Here are some resources to level up: