Claude Code is Anthropic's CLI agent. Setup takes 5 minutes if you know the order. Skip one step and you waste an hour.

The most common mistakes: running the wrong install command for your shell, missing PATH setup after install, and having an ANTHROPIC_API_KEY environment variable left over from a previous project that quietly overrides your subscription. This guide covers all three — plus the first things to do after it's running.

For background on what Claude Code actually is, read What is Claude Code first. If you want a hands-on beginner project walkthrough, see the Claude Code tutorial for beginners. This guide focuses specifically on getting the install right.

Prerequisites

Before running any install command, check these three things:

1. Claude subscription Claude Code requires a Claude Pro, Max, Team, Enterprise, or Console account. The free Claude.ai plan does not include access. If you're unsure, open claude.ai/settings and verify your subscription tier.

2. A supported operating system

• macOS 13.0 or later
• Windows 10 (build 1809) or later, 64-bit only
• Ubuntu 20.04+, Debian 10+, or Alpine Linux 3.19+

3. Shell awareness Windows has multiple shells (PowerShell, CMD, Git Bash). The install command is different for each. Running the wrong one wastes time. This guide shows which command to use where.

Node.js is NOT required if you use the native installer (recommended). It's only needed for the npm fallback path.

Install by Platform

macOS

The fastest path on macOS is the native installer:

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

This downloads and installs the Claude Code binary to ~/.local/bin/claude. Native installs update automatically in the background.

If your team manages tools via Homebrew:

brew install --cask claude-code

Use claude-code for the stable channel. Use claude-code@latest only if you want new releases as soon as they ship. Homebrew does NOT auto-update — run brew upgrade claude-code manually to stay current.

Verify it worked:

claude --version

If you get zsh: command not found: claude, your PATH needs the install directory. See the Common Errors section below.

Windows

Windows has two routes: native Windows and WSL2. The right choice depends on where your project lives.

Native Windows — from PowerShell (recommended):

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

Native Windows — from CMD:

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

WinGet (for managed Windows environments):

winget install Anthropic.ClaudeCode

WSL2 setup — run this inside your WSL terminal, not PowerShell:

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

The most common Windows mistake: pasting the PowerShell command into CMD, or the CMD command into PowerShell. They're different shells. irm works in PowerShell. curl -fsSL ... works in CMD. If you see 'irm' is not recognized, you're in CMD. If you see The token '&&' is not valid, you're in PowerShell.

Install Git for Windows after setting up Claude Code. Without it, Claude Code falls back to PowerShell for shell operations, which breaks many common workflows.

Linux

Native installer (fastest):

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

Debian/Ubuntu via apt:

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
 -o /etc/apt/keyrings/claude-code.asc
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
 | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update && sudo apt install claude-code

Alpine Linux — install dependencies first:

apk add libgcc libstdc++ ripgrep
curl -fsSL https://claude.ai/install.sh | bash

Low-memory VPS (under 4 GB RAM): the installer gets killed by the Linux OOM manager. Add swap space first:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
curl -fsSL https://claude.ai/install.sh | bash

The 3 Commands That Prove It's Working

Run these after any install. They confirm the binary is reachable, authenticated, and ready:

claude --version # shows version number — confirms PATH is set
claude doctor # runs diagnostics — catches common config issues
claude # starts interactive mode — confirms login works

If claude --version works but claude hangs on startup, run claude doctor first — it identifies the exact cause.

On first run, Claude Code opens a browser window for OAuth login. Complete authentication there. Your credentials are stored and you won't need to log in again.

Setting Up CLAUDE.md

Once Claude Code is installed, create a CLAUDE.md file in your project root. This file tells Claude Code things it should always know about your project — without you re-explaining them every session.

A minimal CLAUDE.md:

# Project Context

This is a Next.js 14 app with TypeScript and Prisma.

## Commands
- `npm run dev` — starts the development server
- `npm run test` — runs Jest tests
- `npm run lint` — runs ESLint

## Conventions
- Use named exports, never default exports
- All API routes must validate auth before processing
- Error messages go in /src/constants/errors.ts

## Do Not
- Modify prisma/schema.prisma without adding a migration
- Add dependencies without checking package.json for conflicts

Claude Code reads CLAUDE.md at the start of every session. Good entries: coding conventions, commands the agent should know, things it should never do, and the project's current state. Bad entries: lengthy context that belongs in comments, things that change per-task, or generic best practices the model already knows.

You can also place CLAUDE.md files in subdirectories — Claude Code reads the one closest to the file it's working in.

Common Errors and Exact Fixes

Error: command not found: claude after install

The binary installed but your shell can't find it. The native installer places claude at ~/.local/bin/claude on macOS/Linux. Add this directory to your PATH:

# For zsh (default on macOS):
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

# For bash (default on Linux):
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

Then verify: claude --version

Error: OAuth error: Invalid code

The login code expired before you pasted it. Press Enter to retry, then complete authentication quickly. If the browser doesn't open automatically (common in WSL or SSH sessions), type c at the login prompt to copy the OAuth URL and paste it into your local browser.

Error: Unexpected API charges / wrong account billed

If you have ANTHROPIC_API_KEY set as an environment variable, Claude Code uses that API key instead of your subscription. This is the most common source of surprise charges.

Check it:

echo $ANTHROPIC_API_KEY

If it prints a key you didn't intend to use, unset it:

unset ANTHROPIC_API_KEY

Remove it permanently by deleting the export ANTHROPIC_API_KEY=... line from ~/.zshrc or ~/.bashrc. Then restart your terminal and log in with /login inside Claude Code.

Error: Killed during install on Linux VPS

Your server has less than 4 GB available RAM. The Linux OOM killer terminated the installer. Add swap space (see the Linux section above), then retry.

Error: dyld: cannot load on macOS

You're running macOS 12 or earlier. Claude Code requires macOS 13.0+. Update macOS from System Settings → Software Update.

Plan Mode vs Agentic Mode

Claude Code runs in two primary modes. Knowing when to use each saves significant time.

Agentic mode (default) — Claude acts immediately. It reads files, edits code, runs commands, and iterates until the task is complete. Use this for:

• Clear, well-scoped tasks ("add input validation to the signup form")
• Bug fixes where the cause is known
• Routine changes you've made before

Plan mode — Claude thinks before acting. It produces a plan, waits for your approval, then executes. Activate it by starting your prompt with /plan or pressing Shift+Tab to cycle modes. Use this for:

• Large refactors touching many files
• Tasks where wrong assumptions are expensive to undo
• Anything involving database schema changes
• Features you haven't built in this codebase before

The default for new users is often too much agentic mode on tasks that warrant planning. When Claude starts making changes you didn't expect, stop the session, switch to plan mode, and get the plan confirmed before proceeding.

Build This Into Your App With Claude Code or Cursor

If you're building an app and want Claude Code or Cursor to handle deployment, auth, and databases — not just local code — add the Blink plugin:

npx skills add https://github.com/blink-new/blink-plugin

blink login

Then give your agent a prompt like this:

Build a user authentication system with email/password sign-in,
protected routes, and a user profile page. Deploy it to Blink Cloud
with a Postgres database. Use the Blink plugin for hosting and auth.

Blink Cloud handles database provisioning, auth infrastructure, and hosting — you ship a running app instead of configuring services. See blink.new/cloud for the full platform.

Frequently Asked Questions

Related articles