Beginner

Installing Claude Code

What this gives you: A fully working AI developer in your terminal. After this, you can ask Claude to build websites, write code, manage files, deploy projects, and automate tasks - all from one command line.

Claude Code is a command-line AI assistant that lives inside your terminal and operates directly on your codebase. This guide walks you through every step from a blank machine to your first productive session.

Prerequisites

Four things you need before installing:

Requirement	How to Check	How to Get It
Node.js 18+	`node --version`	`brew install node` (Mac) or nodejs.org (Windows)
npm	`npm --version`	Comes bundled with Node.js
Anthropic Account	-	console.anthropic.com (paid plan or API credits required)
Terminal	-	macOS Terminal, iTerm2, Windows Terminal, or any Unix shell

Installing Claude Code

Install globally with a single npm command:

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

The -g flag installs it globally, making the claude command available from any directory on your machine. This is the correct way to install it - you do not install it per-project.

To verify the installation succeeded:

claude --version

You should see output like 1.x.x. If you get "command not found", your npm global bin directory may not be in your PATH. Fix this by running:

# Find where npm puts global bins
npm config get prefix

# Add to your shell profile (~/.zshrc or ~/.bashrc)
export PATH="$(npm config get prefix)/bin:$PATH"

# Reload your shell
source ~/.zshrc

Authentication

The first time you run claude, it will open your browser to authenticate with your Anthropic account:

claude

Your browser opens to console.anthropic.com. Log in with your Anthropic account, approve the OAuth request, and your terminal will confirm authentication automatically. No API key copying required - it handles the token exchange for you.

If you prefer to use an API key directly (useful for servers or CI environments), set the environment variable:

# Add to ~/.zshrc or ~/.bashrc
export ANTHROPIC_API_KEY="your-api-key-here"

# Or prefix it inline for a single command
ANTHROPIC_API_KEY="sk-ant-..." claude -p "What files are in this directory?"

Warning: Never hardcode your API key in scripts you commit to git. Use environment variables or a .env file that is listed in .gitignore.

Your First Interactive Session

Navigate to any project directory and run claude:

# Navigate to your project
cd ~/my-project

# Start Claude Code
claude

Claude Code immediately reads your directory structure and any CLAUDE.md file present. You'll see a prompt like:

Claude Code (version 1.x.x)
Working directory: /Users/you/my-project
Model: claude-opus-4-5

> _

From here you can type natural language instructions. Try something like:

> Explain the structure of this codebase to me
> Find all TODO comments and list them
> Create a new component called UserCard in the components folder

Key Flags and Modes

The different ways to invoke Claude Code:

Command	What It Does	When to Use
`claude`	Opens a persistent interactive session	Extended development work, iterating on tasks
`claude -p "..."`	One-shot mode - runs a single prompt, outputs result	Quick tasks, scripting, piping output to files
`claude -c`	Continue your last session	Accidentally closed terminal, picking up where you left off
`claude --auto`	Executes all actions without asking for permission	Trusted tasks where you want speed (use with git)
`claude --plan`	Describes what it would do without doing it	Reviewing a plan before executing

Inside an interactive session, slash commands give you quick access:

Command	What It Does
`/help`	List all available commands
`/clear`	Clear conversation history (free up context)
`/compact`	Summarise history to save tokens
`/status`	Show model, context usage, costs
`/exit`	Exit the session

Tip: The most common pattern is claude -p for quick tasks and claude for anything that takes more than one step.

Permission Modes

Claude Code asks for permission before taking actions. You control how much autonomy it gets:

Mode	How It Works	Best For
Default	Claude proposes each action and waits for your `y/n/always` approval	Learning, sensitive projects
`--auto`	Claude executes everything automatically without asking	Trusted tasks where you want speed
`--plan`	Claude describes what it would do without actually doing it	Reviewing approach before committing

Warning: Auto mode gives Claude full write access to your filesystem and shell. Only use it in projects where you have git version control so you can roll back mistakes.

VS Code Extension

Claude Code also has a VS Code extension that embeds the same experience directly in your editor. Install it by searching for "Claude Code" in the VS Code extensions marketplace, or via the CLI:

code --install-extension anthropic.claude-code

The extension adds a Claude panel in the sidebar and lets you highlight code, right-click, and send it directly to Claude. It shares the same authentication as the CLI - no separate login needed.

Troubleshooting Common Install Issues

Permission Errors on macOS/Linux

If you get EACCES: permission denied when installing globally:

# Option 1: Use sudo (not recommended - can cause other issues)
sudo npm install -g @anthropic-ai/claude-code

# Option 2 (recommended): Fix npm permissions once
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code

Authentication Fails / Browser Doesn't Open

# Clear stored credentials and retry
claude auth logout
claude auth login

# If browser won't open, copy the URL manually from terminal output

Stuck on Old Version

# Update to latest
npm update -g @anthropic-ai/claude-code

# Or force reinstall
npm install -g @anthropic-ai/claude-code@latest

Node Version Too Old

# Install nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Restart terminal, then:
nvm install 20
nvm use 20
nvm alias default 20

# Now retry the install
npm install -g @anthropic-ai/claude-code

`claude` Command Not Found After Install

# Find the global bin path
npm root -g

# The bin folder is one level up from root
# e.g. if root is /usr/local/lib/node_modules, bin is /usr/local/bin
which node  # helps identify your node install location

# Add to PATH in ~/.zshrc
export PATH="/usr/local/bin:$PATH"

Tip: If you're using a package manager like Homebrew-installed Node or a version manager like nvm, the global bin path will differ from the system default. Always run npm config get prefix to find the correct path for your setup.

Verifying Everything Works

Run this quick smoke test to confirm installation, authentication, and basic functionality are all working:

# Check version
claude --version

# Run a simple one-shot to verify auth
claude -p "Say hello in exactly 5 words"

# Navigate to a real project and start a session
cd ~/your-project
claude

If all three commands work, you're fully set up and ready to go.

Next Guide

Understanding CLAUDE.md

Installing Claude Code

Prerequisites

Installing Claude Code

Authentication

Your First Interactive Session

Want a guided walkthrough?

Key Flags and Modes

Permission Modes

VS Code Extension

Troubleshooting Common Install Issues

Permission Errors on macOS/Linux

Authentication Fails / Browser Doesn't Open

Stuck on Old Version

Node Version Too Old

claude Command Not Found After Install

Verifying Everything Works

`claude` Command Not Found After Install