Claude Code Setup Guide — Install, Configure, and Ship Faster with the CLI

Claude Code is Anthropic's terminal-based AI coding agent. Unlike editor plugins, it runs directly in your terminal, reads your entire codebase, executes commands, and iterates on code autonomously.

Most developers have heard of it. Far fewer have actually set it up correctly — configured authentication, understood the CLI commands, and structured their project for maximum AI effectiveness.

This guide walks through the complete Claude Code setup from scratch: installation, authentication, first run, project configuration, and the CLI commands you will use every day.

🎯 Quick Answer (30-Second Read)

  • What it is: A CLI tool by Anthropic that runs an AI coding agent directly in your terminal
  • Requirements: Node.js 18+, an Anthropic API key or Claude.ai Pro/Max subscription
  • Install command: npm install -g @anthropic-ai/claude-code
  • Start command: claude in any project directory
  • Key advantage over editor plugins: Full terminal access, codebase-wide context, autonomous multi-step execution
  • First thing to do after install: Create a CLAUDE.md file in your project root

Prerequisites Before You Install

Before running the install command, make sure your environment is ready.

Node.js version 18 or higher is required. Claude Code will not run on older versions.

# Check your Node.js version
node --version

# If below 18, update via nvm
nvm install 18
nvm use 18

You need one of the following for authentication:

  • An Anthropic API key from console.anthropic.com
  • A Claude.ai Pro subscription (personal use)
  • A Claude.ai Max subscription (higher usage limits)
  • An Anthropic Console account with billing enabled (team / enterprise)

API key usage is billed per token. If you use Claude.ai Pro or Max, Claude Code usage is included within your plan limits. For heavy agentic workloads, Max is the practical choice.

Architecture: How Claude Code Works

flowchart TD A([👨‍💻 Developer]) -->|types prompt| B[Claude Code CLI] B --> C{Session Manager} C --> D[Context Builder] C --> E[Tool Executor] C --> F[API Client] D --> D1[Reads CLAUDE.md] D --> D2[Indexes project files] D --> D3[Loads conversation history] E --> E1[File read / write] E --> E2[Terminal commands] E --> E3[Web search] F -->|sends context + prompt| G[Anthropic API\nClaude Sonnet / Opus] G -->|returns plan + actions| F F --> H[Action Executor] H --> I{Review Mode?} I -->|Auto-accept| J[Apply changes directly] I -->|Manual| K[Show diff → await approval] J --> L([✅ Code Updated]) K --> L style A fill:#0f172a,color:#e2e8f0,stroke:#334155 style L fill:#166534,color:#dcfce7,stroke:#16a34a style G fill:#7c2d12,color:#fed7aa,stroke:#f97316 style I fill:#1e3a5f,color:#bfdbfe,stroke:#3b82f6 style B fill:#1e293b,color:#cbd5e1,stroke:#475569 style C fill:#1e293b,color:#cbd5e1,stroke:#475569 style D fill:#1e293b,color:#cbd5e1,stroke:#475569 style E fill:#1e293b,color:#cbd5e1,stroke:#475569 style F fill:#1e293b,color:#cbd5e1,stroke:#475569 style H fill:#1e293b,color:#cbd5e1,stroke:#475569 style D1 fill:#312e81,color:#e0e7ff,stroke:#6366f1 style D2 fill:#312e81,color:#e0e7ff,stroke:#6366f1 style D3 fill:#312e81,color:#e0e7ff,stroke:#6366f1 style E1 fill:#312e81,color:#e0e7ff,stroke:#6366f1 style E2 fill:#312e81,color:#e0e7ff,stroke:#6366f1 style E3 fill:#312e81,color:#e0e7ff,stroke:#6366f1 style J fill:#166534,color:#dcfce7,stroke:#16a34a style K fill:#78350f,color:#fef3c7,stroke:#f59e0b

Step-by-Step: Complete Claude Code Setup

Step 1 — Install Claude Code globally

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

This installs the claude binary globally. After install, verify it worked:

claude --version

You should see a version string like 1.x.x. If you get a command not found error, your npm global bin directory is not in your PATH. Fix it:

# Find your npm global bin path
npm config get prefix

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

# Reload shell
source ~/.zshrc

Step 2 — Authenticate with your Anthropic account

Run this from any directory:

claude

On first launch, Claude Code opens a browser window for OAuth authentication. Log in with your Anthropic account or Claude.ai subscription.

If you prefer API key authentication:

export ANTHROPIC_API_KEY=sk-ant-your-key-here

Add this to your ~/.zshrc or ~/.bashrc to persist it across sessions:

echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.zshrc
source ~/.zshrc

Step 3 — Navigate to your project and start a session

cd ~/your-project
claude

Claude Code starts an interactive session in your terminal. It reads your current directory, looks for a CLAUDE.md file, and waits for your first prompt.

The first time you open a large project, it indexes the codebase in the background. This takes 30–60 seconds for medium projects.

Step 4 — Run your first task

Try a simple task to verify everything works:

> Explain the structure of this project and list the main entry points

Claude Code will read your files and return a structured summary. If it can navigate your codebase accurately, your setup is working correctly.

Step 5 — Create your CLAUDE.md configuration file

This is the most important post-install step. Create a CLAUDE.md at your project root:

touch CLAUDE.md

Then ask Claude Code to generate a starting point:

> Read my package.json, project structure, and key config files.
> Generate a CLAUDE.md file covering my stack, common commands, and conventions.

Review the output, adjust the rules, and save it. Every future session will start with this context loaded automatically.

For a full breakdown of what to put in CLAUDE.md, see the CLAUDE.md configuration guide.

Essential Claude Code CLI Commands

Interactive session commands

# Start a new session in current directory
claude

# Start with an initial prompt (non-interactive)
claude "explain this codebase"

# Start with a specific file in context
claude --file src/lib/auth.ts "how does authentication work here"

Session control during a conversation

Command What it does
Ctrl+C Cancel current operation
Ctrl+D or exit End the session
/clear Clear conversation history, keep project context
/help Show available slash commands
/status Show current model, token usage, session info

Running one-off tasks without an interactive session

# Run a single task and exit
claude -p "write unit tests for src/lib/utils.ts"

# Pipe file content to Claude Code
cat src/lib/auth.ts | claude -p "review this file for security issues"

# Run with output saved to a file
claude -p "generate API documentation for src/routes/" > docs/api.md

Controlling file permissions and safety

# Allow Claude to write files (prompted by default)
claude --allowedTools "read,write"

# Read-only mode — Claude can read but not modify files
claude --allowedTools "read"

# Allow terminal command execution
claude --allowedTools "read,write,bash"

Configuration: claude.json Settings

Claude Code stores global configuration in ~/.claude/claude.json. You can also create a project-level .claude/claude.json for per-project settings.

Key settings to know:

{
  "model": "claude-sonnet-4-5",
  "autoAcceptEdits": false,
  "theme": "dark",
  "verbose": false,
  "maxTokens": 8096
}

autoAcceptEdits — set to true to apply file changes without manual confirmation. Use this only on projects with good test coverage and version control. Default is false.

model — switch between Sonnet (faster, cheaper) and Opus (more powerful, slower) depending on task complexity.

verbose — set to true to see Claude Code's internal reasoning steps. Useful for debugging why it made a particular decision.

Daily Workflow: How to Use Claude Code Effectively

For feature development:

> Add rate limiting to the POST /api/auth/login route.
> Use the existing redis client in src/lib/redis.ts.
> Limit to 5 requests per minute per IP.
> Add a test in src/tests/auth.test.ts.

For debugging:

> Running `pnpm test` gives this error: [paste error]
> Find the root cause and fix it.

For refactoring:

> Refactor src/lib/db.ts to use connection pooling.
> Do not change the public API — only the internal implementation.
> Run the test suite after changes and fix any failures.

For code review:

> Review the last 3 files I modified for bugs, type safety issues,
> and anything that does not follow the conventions in CLAUDE.md.

Comparison: Claude Code vs Other AI Coding Tools

Feature Claude Code CLI Cursor GitHub Copilot Devin
Interface Terminal IDE (VS Code fork) IDE plugin Web + IDE
Codebase context ✅ Full ✅ Full ⚠️ Partial ✅ Full
Agent / multi-step ✅ Yes ✅ Yes ❌ No ✅ Yes
Terminal execution ✅ Native ✅ Yes ❌ No ✅ Yes
Headless / CI use ✅ Yes ❌ No ❌ No ❌ No
Custom model choice ❌ Claude only ✅ Multiple ❌ No ❌ No
Cost Usage-based $20/mo $10/mo $500/mo
Best for Terminal-first devs IDE-first devs Autocomplete Full autonomy

Troubleshooting Common Setup Issues

claude: command not found after install
Your npm global bin is not in PATH. Run npm config get prefix, add /bin to your PATH in .zshrc or .bashrc, and reload your shell.

Authentication fails or browser does not open
Try claude --login to force a fresh OAuth flow. If behind a proxy, set HTTPS_PROXY environment variable before running.

Claude Code modifies files I did not want changed
Add a hard rule to your CLAUDE.md: NEVER modify [filename]. For session-level protection, use --allowedTools "read" to run in read-only mode.

Slow responses on large codebases
Claude Code indexes files on first run. For very large repos, add a .claudeignore file (same syntax as .gitignore) to exclude node_modules, build artifacts, and generated files.

# .claudeignore
node_modules/
.next/
dist/
build/
*.lock
coverage/

Token usage is too high
Use /clear periodically during long sessions to reset conversation history while keeping project context. Switch to claude-sonnet in settings for routine tasks, reserving Opus for complex reasoning tasks.

Real Developer Use Case

A backend developer at a startup used Claude Code to migrate a legacy Express API with 60 route files to a new Hono-based architecture. The task was too large and too mechanical for manual work but too complex for a simple find-and-replace script.

They wrote a detailed prompt specifying the migration rules, pointed Claude Code at the routes directory, and let it run with autoAcceptEdits disabled so they could review each file before accepting.

Claude Code migrated each route file, updated the middleware imports, ran pnpm typecheck after each file, caught four type mismatches autonomously, and flagged two files where business logic was ambiguous enough to require human review.

The full migration took three hours. The same task estimated manually was two to three days.

Frequently Asked Questions

Is Claude Code free to use?
Claude Code requires either a paid Claude.ai subscription (Pro or Max) or an Anthropic API key with billing enabled. There is no permanent free tier for Claude Code. Claude.ai Pro includes Claude Code access within plan limits. Max provides significantly higher usage caps suited for daily agentic workflows.

Can I use Claude Code in CI/CD pipelines?
Yes — and this is one of Claude Code's strongest use cases. Use the -p flag for non-interactive single-task execution: claude -p "run tests and report any failures". Set ANTHROPIC_API_KEY as a CI secret and invoke Claude Code as a build step.

Does Claude Code work on Windows?
Claude Code works on Windows via WSL2 (Windows Subsystem for Linux). Native Windows support through PowerShell or CMD is limited. WSL2 with Ubuntu is the recommended Windows setup and behaves identically to macOS or Linux.

How is Claude Code different from using Claude.ai in the browser?
The browser interface has no access to your local files, terminal, or codebase. Claude Code runs as a local agent with full read/write access to your project, the ability to execute shell commands, and persistent context through CLAUDE.md. It is purpose-built for software development tasks, not general conversation.

What model does Claude Code use?
By default, Claude Code uses Claude Sonnet for most tasks. You can switch to Claude Opus in settings for more complex reasoning tasks. Sonnet is faster and cheaper for routine coding work. Opus handles ambiguous, multi-constraint problems more reliably.

Conclusion

Claude Code is the most capable terminal-based AI coding agent available in 2025. Setting it up correctly — proper authentication, a solid CLAUDE.md, a .claudeignore for large repos, and an understanding of the key CLI flags — takes under 30 minutes and changes how you work every day after that.

Install it if you are a developer who lives in the terminal, works on multi-file features, or wants an AI agent that can run, test, and debug code without leaving the command line.

The setup investment is small. The productivity return is large.

Related reads: How to Create a CLAUDE.md Configuration File · How AI Agents Write Code Automatically · Cursor vs VS Code: Which Is Better for AI Coding · How Developers Use AI to Build Apps Faster