Claude Code: The Complete Guide to Anthropic's AI Coding CLI

You open the Claude website. You paste some code. You get an answer. You copy it back.

That is a chatbot. Claude Code is not that.

Claude Code runs inside your terminal. It reads your actual files. It writes code, runs your tests, fixes failures, commits to git, and opens pull requests — on its own. You describe what you want. It builds it.

This guide covers everything — from install to advanced automation — in one place.

What Makes Claude Code Different

Most AI tools have a wall between them and your work. You copy code in. You copy code out. You are always the bridge.

Claude Code removes that wall entirely.

Claude.ai (Web)

The Chatbot

You paste code in, copy answers out

File size limits block large codebases

Cannot run your tests or build tools

Cannot commit or open pull requests

You are always the bridge between AI and code

Claude Code (CLI)

The Coding Agent

Reads your entire codebase directly

No file size limits — works on 5GB+ repos

Runs tests, fixes failures, iterates

Commits, branches, opens PRs

You describe the goal. It handles execution.

Claude Code Is Everywhere Now

The terminal is just the beginning. In 2026, Claude Code runs across every surface where developers work.

Terminal CLI

Full power — this guide's focus

Runs anywhere, scriptable, hooks, MCP, full permission control. The complete feature set.

Desktop App

No terminal required

Visual diffs, multi-session management, scheduled tasks. Download from claude.ai/desktop.

VS Code / Cursor

Inline edits inside your editor

@-mentions, inline diffs, plan review without leaving the editor. Install the Claude Code extension.

JetBrains

IntelliJ / PyCharm / WebStorm

Official plugin with the same capabilities as the VS Code extension. Install from JetBrains Marketplace.

GitHub Actions / CI

Headless automation

Run claude -p in CI pipelines. Review PRs, run codemod scripts, automate repetitive checks on every push.

Web — claude.ai/code

No install needed

Browser-based access to remote repositories. No local setup required. Good for quick exploration on any machine.

The rest of this guide covers the terminal CLI — where the full power lives. But once you're comfortable here, the VS Code extension and Desktop App add a lot for day-to-day work.

Installing Claude Code

System Requirements

macOS 13+
Windows 10 1809+
Ubuntu 20.04+

Hardware

4GB+ RAM
Internet required

Shell

Bash, Zsh
PowerShell, CMD

Pick your platform and run one command:

macOS / Linux / WSL Recommended

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

🪟 Windows PowerShell

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

🍺 Homebrew (macOS — no auto-updates)

brew install --cask claude-code

Verify it worked:

claude --version

claude doctor   # full diagnostic check

Logging In

Four ways in. One is right for you.

⭐

Most people — just run claude Recommended

A browser tab opens, you sign in with your Anthropic account, and you're done. Works with Pro, Max, Teams, and Enterprise. No config required.

API Key

Best for: CI/CD · Scripts · Automation

Set one env variable. Claude Code picks it up automatically — no browser, no prompt.

export ANTHROPIC_API_KEY="sk-ant-..."

Cloud Providers

Best for: AWS · GCP · Azure deployments

Already running Claude through AWS Bedrock, Google Vertex AI, or Azure Foundry? Route Claude Code through your existing setup with one variable.

CLAUDE_CODE_USE_BEDROCK=true   # AWS
CLAUDE_CODE_USE_VERTEX=true    # GCP

Teams & Enterprise

Best for: Orgs · Centralized billing

Admin invites teammates through the Anthropic Console. Each member installs Claude Code and signs in with their own account. Usage and billing tracked centrally — no shared keys.

Your First 10 Minutes

Open your project folder in terminal, then run:

  $ cd your-project

  $ claude

You are now in an interactive session. Try these to get oriented:

Step 1

Understand your codebase

"Give me an overview of this project. What does it do and how is it structured?"

Step 2

Generate your CLAUDE.md

/init

Claude reads the codebase and writes a CLAUDE.md with your project's conventions.

Step 3

Give it a real task

"Find all TODO comments and fix the ones in the auth module. Run tests after."

The Four Modes

Claude Code has four distinct ways of working. Knowing when to use each one is the difference between a power user and a beginner.

💬

Interactive Mode

The Default

claude

Full REPL with streaming responses, keyboard shortcuts, permission prompts, and task tracking. Use this for everything that is not scripted.

⚡

Print Mode

For Scripts & CI/CD

claude -p "your prompt"

Non-interactive, returns immediately. Use in shell scripts, CI pipelines, and automation loops. Supports --output-format json for machine-readable output.

📥

Pipe Mode

Pipe Data Directly

cat error.log | claude -p "summarize"
git diff | claude -p "review"

Feed any data via stdin. Works with logs, diffs, file output, API responses. Claude receives and processes it inline.

🛡️

Plan Mode

Read-only & Safe

claude --permission-mode plan
# or press Shift+Tab in session

Claude can read files and explore — but cannot write or execute anything. Perfect for exploring unfamiliar code or planning a large refactor safely.

The Commands That Matter Most

Command	What It Does	When to Use It
`/init`	Generate CLAUDE.md from your codebase	First session in any project
`/clear`	Start a fresh conversation	Between unrelated tasks
`/compact`	Summarize conversation to free context	Long sessions getting slow
`/memory`	View and edit Claude's learned notes	See what Claude has remembered
`/permissions`	Configure what Claude is allowed to do	Pre-approve safe commands
`/model`	Switch AI model mid-session	Switch between Sonnet/Opus
`/cost`	Show token usage and estimated cost	Track spending per session
`/doctor`	Diagnose auth, connectivity, and config	Something not working right
`/mcp`	Manage MCP server connections	Connect external tools
`/status`	Show current model, auth, and account	Verify your setup
`claude -c`	Continue your most recent session	Pick up where you left off
`claude -r <name>`	Resume a named session	Long-running or named work
`claude commit`	Dedicated git commit helper with staged diff context	Better commit messages automatically
`claude auth status`	Check current login state	Debug auth issues
`claude update`	Update to the latest version	Keep current (auto-updates on curl install)

Essential keyboard shortcuts:

Ctrl+C Cancel current generation

Shift+Tab Toggle permission mode

Esc + Esc Rewind last action

Ctrl+V Paste image from clipboard

Ctrl+B Background the running task

Ctrl+D Exit Claude Code

CLAUDE.md — Teach It Your Project Once

CLAUDE.md is a markdown file that Claude reads at the start of every session. It is how you encode your project's conventions, commands, and rules — permanently.

You write it once. Claude follows it forever.

📁 Where to Put It

./CLAUDE.md — project-wide, check into git
./.claude/CLAUDE.md — project, alternate location
~/.claude/CLAUDE.md — your personal rules, all projects
/Library/Application Support/ClaudeCode/CLAUDE.md — org-managed (macOS), cannot be excluded by users

⚠️ Keep it Short

Target under 200 lines. Claude reads the entire file on every session start. Longer files get less attention — ruthlessly prune what Claude does not need.

Example CLAUDE.md

    # Code Style

    - TypeScript everywhere, 2-space indent

    - Use const; avoid var and let

    - React: functional components only

    # Commands

    - Run tests: npm test

    - Build: npm run build

    - Lint: npm run lint

    # Git

    - Branch from main

    - Commit: imperative mood ("add feature", not "added")

    - Run tests before every commit

    # Architecture

    - API handlers: src/api/handlers/

    - Models: src/models/

    - Tests co-located with source

    # IMPORTANT: Never commit .env files

The quality rule: Be specific or do not write it.

✅ Good

Run `npm test` before committing
API handlers live in `src/api/`
Use 2-space indentation

❌ Ignored

Test your changes
Keep files organized
Format code properly

Two advanced features worth knowing

Import other files — Use @path/to/file syntax inside CLAUDE.md to pull in other markdown files. Keeps the main file clean by splitting long rules into topic files.

Rules directory — Put individual rule files in .claude/rules/. Each file can use YAML frontmatter to scope rules to specific file paths — so frontend rules only load when Claude is working in src/ui/, backend rules only for src/api/.

Custom Commands — Reusable Workflows

Any .md file you put in .claude/commands/ becomes a slash command available in every session. It's the fastest way to turn a multi-step workflow into a one-liner.

How Custom Commands Work

<div style="background: #0d1117; border: 1px solid rgba(255,255,255,0.07); border-radius: 10px; padding: 16px 20px;">
  <div style="color: #22d3ee; font-size: 0.78rem; font-weight: 700; margin-bottom: 8px; text-transform: uppercase; letter-spacing: 0.08em;">Project commands (shared with team)</div>
  <div style="color: #64748b; font-size: 0.8rem; margin-bottom: 10px;">Save to <code style="color: #22d3ee; background: rgba(6,182,212,0.1); padding: 1px 5px; border-radius: 3px;">.claude/commands/</code> and commit to git. Available to everyone on the team.</div>
  <div style="background: #020810; border-radius: 6px; padding: 10px 14px; font-family: monospace; font-size: 0.8rem; color: #67e8f9; overflow-x: auto;">.claude/commands/review-pr.md<br/>.claude/commands/deploy-staging.md<br/>.claude/commands/run-migrations.md</div>
</div>

<div style="background: #0d1117; border: 1px solid rgba(255,255,255,0.07); border-radius: 10px; padding: 16px 20px;">
  <div style="color: #22d3ee; font-size: 0.78rem; font-weight: 700; margin-bottom: 8px; text-transform: uppercase; letter-spacing: 0.08em;">Personal commands (all projects)</div>
  <div style="color: #64748b; font-size: 0.8rem; margin-bottom: 10px;">Save to <code style="color: #22d3ee; background: rgba(6,182,212,0.1); padding: 1px 5px; border-radius: 3px;">~/.claude/commands/</code>. Only for you, works in every project.</div>
  <div style="background: #020810; border-radius: 6px; padding: 10px 14px; font-family: monospace; font-size: 0.8rem; color: #67e8f9; overflow-x: auto;">~/.claude/commands/explain-error.md<br/>~/.claude/commands/write-tests.md</div>
</div>

<div style="background: #0d1117; border: 1px solid rgba(255,255,255,0.07); border-radius: 10px; padding: 16px 20px;">
  <div style="color: #22d3ee; font-size: 0.78rem; font-weight: 700; margin-bottom: 8px; text-transform: uppercase; letter-spacing: 0.08em;">Example: review-pr.md</div>
  <div style="background: #020810; border-radius: 6px; padding: 10px 14px; font-family: monospace; font-size: 0.8rem; color: #67e8f9; line-height: 1.8; overflow-x: auto;"><span style="color: #64748b;"># Review PR</span><br/>Review the changes in the current branch against main.<br/>Check for: bugs, security issues, missing tests, unclear names.<br/>Use $ARGUMENTS for the PR number if provided.<br/>Output a structured list: Critical / Warnings / Suggestions.</div>
  <div style="color: #64748b; font-size: 0.78rem; margin-top: 10px;">Invoke with: <code style="color: #22d3ee; background: rgba(6,182,212,0.1); padding: 1px 5px; border-radius: 3px;">/review-pr 142</code></div>
</div>

Use $ARGUMENTS anywhere in the file to pass parameters when invoking. Commands can be as simple as one sentence or as detailed as a full multi-step workflow.

How Claude Remembers Things

Claude Code has two memory systems working in parallel.

📝

CLAUDE.md

You write it

✓ Persistent instructions you control

✓ Check into git — shared with team

✓ Loaded at the start of every session

✓ Full control over what Claude knows

🧠

Auto Memory

Claude writes it

✓ Build commands and patterns it learns

✓ Stored in ~/.claude/projects/.../memory/

✓ Local only — not shared with team

✓ View and edit any time with /memory

Auto Memory tip: Claude saves things like "npm run dev starts the server on port 3001" and "the tests require a running Postgres instance." It stops asking you the same setup questions twice. View and delete entries any time from /memory.

The Permission System

Claude Code asks before taking actions that change your system. You control exactly what it can and cannot do.

👁️

Always Allowed

Never prompts

Read files
Search code
Web search

⚠️

Ask First

Default behavior

Write files
Edit files
Run commands

🚫

Blocked

Explicitly denied

Git push
rm -rf
sudo commands

Pre-approve common safe commands in .claude/settings.json:

// .claude/settings.json

{

  "permissions": {

    "allow": [

      "Bash(npm run *)",

      "Bash(npm test)",

      "Bash(git commit *)",

      "Bash(git status)",

      "Read",

      "Edit"

    ],

    "deny": [

      "Bash(git push)",

      "Bash(rm -rf *)",

      "Bash(sudo *)"

    ]

  }

}

Choosing the Right Model

Claude Code supports multiple models. The right choice depends on what you are building.

Alias	Model	Cost	Best For
`sonnet`	claude-sonnet-4-6	$3 / $15 per 1M tokens	Daily coding, bug fixes, features — the everyday workhorse
`opus`	claude-opus-4-6	$15 / $75 per 1M tokens	Complex architecture, multi-step planning, hard debugging
`haiku`	claude-haiku-4-5	$0.80 / $4 per 1M tokens	Quick lookups, subagents, repetitive tasks
`sonnet[1m]`	Sonnet + 1M context	Subscription	Massive codebases, very long sessions

Switch mid-session anytime: /model opus or /model sonnet

MCP: Connect Claude to Everything

MCP (Model Context Protocol) lets Claude Code talk to external systems — GitHub, Sentry, Notion, databases, Slack, and hundreds more — directly from your session.

Adding MCP Servers

<div style="background: #0d1117; border: 1px solid rgba(255,255,255,0.07); border-radius: 10px; padding: 16px 20px;">
  <div style="color: #c084fc; font-size: 0.78rem; font-weight: 700; margin-bottom: 8px; text-transform: uppercase; letter-spacing: 0.08em;">HTTP Server (most common)</div>
  <div style="background: #08020f; border-radius: 6px; padding: 10px 14px; font-family: monospace; font-size: 0.8rem; color: #c4b5fd; overflow-x: auto;">claude mcp add --transport http github https://api.githubcopilot.com/mcp/<br/>claude mcp add --transport http sentry https://mcp.sentry.dev/mcp</div>
</div>

<div style="background: #0d1117; border: 1px solid rgba(255,255,255,0.07); border-radius: 10px; padding: 16px 20px;">
  <div style="color: #c084fc; font-size: 0.78rem; font-weight: 700; margin-bottom: 8px; text-transform: uppercase; letter-spacing: 0.08em;">Local Tool (npm package)</div>
  <div style="background: #08020f; border-radius: 6px; padding: 10px 14px; font-family: monospace; font-size: 0.8rem; color: #c4b5fd; overflow-x: auto;">claude mcp add --transport stdio my-tool \<br/>&nbsp;&nbsp;--env API_KEY=your-key \<br/>&nbsp;&nbsp;-- npx -y my-mcp-package</div>
</div>

<div style="background: #0d1117; border: 1px solid rgba(255,255,255,0.07); border-radius: 10px; padding: 16px 20px;">
  <div style="color: #c084fc; font-size: 0.78rem; font-weight: 700; margin-bottom: 8px; text-transform: uppercase; letter-spacing: 0.08em;">Project-wide (shared with team)</div>
  <div style="background: #08020f; border-radius: 6px; padding: 10px 14px; font-family: monospace; font-size: 0.8rem; color: #c4b5fd; overflow-x: auto;">claude mcp add --scope project --transport http github https://api.githubcopilot.com/mcp/<br/><span style="color: #64748b;"># Saves to .mcp.json — check this into git</span></div>
</div>

Popular integrations:

🐙

GitHub

PRs, Issues, Reviews

🔴

Sentry

Errors, Issues

💬

Slack

Channels, Messages

🗃️

PostgreSQL

Direct DB queries

Hooks: Automation That Always Runs

Hooks are shell commands that fire automatically at specific moments in every Claude Code session. Unlike CLAUDE.md instructions (advisory), hooks are guaranteed to run.

When Hooks Fire

PreToolUse

Before any tool executes. Block dangerous commands, log for audit.

PostToolUse

After a tool succeeds. Auto-format code, run linters, update logs.

Stop

After Claude finishes. Verify the work, run tests, notify you.

SessionStart

When a session begins. Inject environment, set context.

Real example — auto-format files after every edit:

// .claude/settings.json

{

  "hooks": {

    "PostToolUse": [{

      "matcher": "Edit|Write",

      "hooks": [{

        "type": "command",

        "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"

      }]

    }]

  }

}

Hook exit codes:

exit 0 → allow the action, add context via stdout
exit 2 → block the action, stderr becomes Claude's feedback

Five Workflows That Show What It Can Really Do

🐛

Workflow 1 — Fix a Bug With Full Context

"I'm seeing this error when running tests:
[paste full stack trace]
Investigate the root cause, implement a fix, run tests to verify."

Claude reads the affected files, traces the error, writes the fix, runs npm test, and iterates until tests pass — without you touching a file.

🚀

Workflow 2 — Build a Full Feature End-to-End

"Add Google OAuth login. Explore the auth system, create a detailed plan,
implement it, write tests, and open a PR when done."

Claude explores the codebase, writes an implementation plan, builds the feature, writes tests, commits cleanly, and opens the PR — all from one prompt.

🗂️

Workflow 3 — Understand a New Codebase

"Give me an overview of this codebase. How does auth work?
What are the key data models? Where is the main business logic?"

Start in Plan Mode (Shift+Tab). Claude reads the full repo and produces a map — no changes made, no risk. Perfect for onboarding to unfamiliar projects.

🔄

Workflow 4 — Bulk Scripted Operations

for file in $(cat js-files.txt); do
  claude -p "Migrate $file to TypeScript" \
    --allowedTools "Edit,Bash(git commit *)"
done

Use print mode in loops for batch operations. Migrate files, generate tests, apply consistent refactors across your entire codebase automatically.

🧪

Workflow 5 — Write Tests for Uncovered Code

"Find functions in NotificationsService that have no test coverage.
Write comprehensive tests covering all edge cases. Run them and fix failures."

Claude maps the module, identifies untested paths, writes tests, runs them, and fixes any that fail. You get coverage without writing a single test by hand.

The 8 Best Practices That Actually Matter

Give Claude a way to verify its own work

Always include a testable success condition. "Write a validateEmail function. Test: [email protected] → true, invalid → false. Run tests and fix failures." Claude loops until it passes rather than guessing.

Plan before you build, especially for complex changes

Switch to Plan Mode (Shift+Tab or --permission-mode plan), ask Claude to explore and write a detailed plan, then review it and execute. Prevents costly wrong-direction work.

Use /clear between unrelated tasks

Stale context is wasted tokens and confused responses. Start fresh between distinct tasks. Reuse context only when it is genuinely relevant to what you are asking next.

Pre-approve safe commands so Claude stops asking

After 10+ permission prompts, you stop reviewing them carefully. Add npm run *, git commit *, and Read to your allow list. Reserve manual approval for genuinely risky commands.

Use Sonnet for 90% of work, Opus for hard problems only

Sonnet handles most coding tasks at a fraction of the cost. Switch to Opus for complex architecture decisions, deep debugging, or multi-step planning. Use /model opus when you need the upgrade.

Use subagents for investigation tasks

Subagents work in separate contexts. Ask Claude to "use a subagent to investigate how auth is implemented" — the investigation stays isolated, keeping your main session focused and clean.

CLAUDE.md is for what you cannot change every session

If you find yourself repeating the same instruction across sessions ("always run npm test after changes", "use the api/handlers directory"), that belongs in CLAUDE.md — not typed every time.

Hooks for enforcement. CLAUDE.md for guidance.

CLAUDE.md is advisory — Claude reads it and tries to follow it. Hooks are deterministic — they always fire. Use hooks for things that must happen: auto-format, block protected files, audit logging.

Pricing — What It Actually Costs

Plan	Monthly	Best For
Pro	$20	Individual developers, lighter usage
Max	$200	Heavy daily use, large codebases, 8M tokens/month
Teams Standard	$30/user	Teams with shared billing and admin controls
API / Pay-as-you-go	Per token	Automation, CI/CD pipelines, scripting at scale

Average real-world cost: Most individual developers spend $6–12/day on heavy Claude Code use. Track your session spend with /cost. Use /clear between tasks to avoid paying for irrelevant context.

The Bottom Line

Claude Code is not a smarter autocomplete.

It is a collaborator that reads your codebase, understands your conventions, runs your tools, and ships working code — while you focus on what actually requires your judgment. The bottleneck is no longer writing code. It is knowing what to build.

Install it. Run /init. Give it a real task.
Then watch what happens.

Sources: Anthropic Claude Code official documentation (code.claude.com/docs) · Claude Code CLI reference · Anthropic model pricing page · Stack Overflow Developer Survey 2025 · GitHub "The Impact of AI on Developer Productivity" (2022)