Claude Code
Practitioner's Handbook

This edition replaces the v1 handbook (May 25, 2026). Claude Code shipped roughly 175 releases between then and now — the highlights below are the ones that change how you should actually use the tool day-to-day.

# Requires Node.js 18+
npm install -g @anthropic-ai/claude-code
claude --version

# Auth — browser OAuth (recommended) or API key
claude                              # opens browser auth on first run
export ANTHROPIC_API_KEY=sk-ant-...
claude --api-key $ANTHROPIC_API_KEY

# Update — Claude Code ships near-daily; update often
claude update                       # or: npm update -g @anthropic-ai/claude-code

# Run diagnostics
claude /doctor

# Fresh troubleshooting session — disables every customization
claude --safe-mode                  # or CLAUDE_CODE_SAFE_MODE=1

IDE Integrations

Switch at any time with /model. As of v2.1.197 (June 30, 2026), Sonnet 5 is the default model for new sessions on all surfaces, with native 1M-token context at standard pricing.

# Switch models interactively
/model

# Shorthand (recommended)
/model opus
/model sonnet
/model haiku
/model fable

# Full model IDs — CLI flags
claude --model claude-fable-5
claude --model claude-opus-4-8
claude --model claude-opus-4-7
claude --model claude-sonnet-5
claude --model claude-sonnet-4-6
claude --model claude-haiku-4-5-20251001

# Pin explicitly (aliases like `opus` can shift providers/versions over time)
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-8
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5

Sonnet 5, Opus 4.8, and Fable 5 use adaptive reasoning — the model decides how much to think per turn within a ceiling you set with /effort. This replaced the old fixed thinking-token-budget model from the Claude 4.5 generation.

# Set effort for the whole session
/effort high
/effort xhigh
/effort ultracode

# CLI flag / env var
claude --effort xhigh
export CLAUDE_CODE_EFFORT_LEVEL=high

# Turn thinking off entirely on think-by-default models
export MAX_THINKING_TOKENS=0
claude --thinking disabled

Ultracode — Automatic Multi-Agent Orchestration

Typing the word ultracode anywhere in a prompt triggers that single task to run as a Dynamic Workflow: a background orchestration script that a runtime executes, coordinating up to 16 concurrent subagents, with intermediate results kept in script variables rather than the main context window. Setting /effort ultracode makes this automatic for every substantive task in the session — Claude decides on its own when a request is big enough to fan out, verify with an independent subagent, and merge results.

# One-off: trigger a workflow for this task only
> "ultracode: migrate every route handler in src/api to the new validation middleware"

# Session-wide: every substantive task gets auto-orchestrated
/effort ultracode

# Disable the keyword trigger but keep manual /effort control
# /config → "Ultracode keyword trigger" → off

# Disable workflows entirely
export CLAUDE_CODE_DISABLE_WORKFLOWS=1
# or in settings.json: "disableWorkflows": true

Trigger phrases like think, think harder, and ultrathink still work as in-context instructions that ask the model to reason more before answering a specific turn. They're a lighter-weight nudge than /effort — useful when you want deeper reasoning on one message without changing the whole session's ceiling.

Claude Code ships five permission modes. Cycle between them with Shift+Tab, or set one explicitly with --permission-mode. Protected paths (like .env, credentials, CI secrets) stay protected in every mode except bypass.

# Cycle modes interactively
Shift+Tab

# Set explicitly via CLI flag
claude --permission-mode plan
claude --permission-mode acceptEdits
claude --permission-mode auto
claude --dangerously-skip-permissions    # bypass — use only in disposable containers

# Activate plan mode then share a spec
Shift+Tab
> "Read CLAUDE.md and plan how to add rate limiting to the ingest API"

# Or via command
/plan

# Combine with a higher effort level for architecture-grade plans
/effort xhigh
/plan

Auto mode is a permission mode where a background classifier makes approval decisions on your behalf, monitoring actions before they run. It sits between manual approval and bypass: far fewer interruptions than default, but real safety checks that bypass doesn't have.

# Enable auto mode for a session
claude --permission-mode auto

# Org admins can lock auto mode off entirely
# managed-settings.json:
{
  "permissions": { "disableAutoMode": "disable" }
}

CLAUDE.md is a markdown file Claude automatically loads into context at the start of every session. Think of it as onboarding notes for a new team member: coding standards, architecture context, build commands, and things to avoid.

Where CLAUDE.md Files Live — Resolution Order

Anatomy of a Good CLAUDE.md

# CLAUDE.md — project-name

### Project overview
Brief description of what this repo does and its core architecture.

### Coding standards
- TypeScript strict mode; no `any` without a comment justifying it
- Config-driven: no magic numbers in code, use config files
- All async operations require explicit error handling
- Tests: vitest, colocated as `*.test.ts`
- Never hardcode secrets; use `.env` + a typed config loader

### Build & test commands
!`cat package.json | grep -A 10 '"scripts"'`   # live-injects your npm scripts

### Recent activity (dynamic context)
!`git log --oneline -5`
!`git status`

### Do NOT
- Modify files under /infra/prod/
- Push directly to main; always use feature branches
- Run database migrations without human confirmation

### Reference docs
@./docs/architecture.md
@./configs/base_config.yaml

# Auto-generate CLAUDE.md by scanning the current codebase
/init

# Progressive-disclosure tuning — trims a bloated CLAUDE.md
# while preserving critical rules (community skill pattern, see §14)
/claude-md-progressive-disclosurer

Settings resolve hierarchically: Enterprise/managed policy → CLI flags → .claude/settings.local.json (personal, gitignored) → .claude/settings.json (project, shared) → ~/.claude/settings.json (user). More specific scopes override less specific ones; managed policy always wins.

# .claude/settings.json — project-level, shared via git
{
  "model": "claude-sonnet-5",
  "permissions": {
    "allow": [
      "Bash(git add:*)",
      "Bash(git commit:*)",
      "Bash(npm run:*)",
      "Write(src/**)",
      "Edit(*.ts)",
      "Edit(*.yaml)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(curl * | bash:*)",
      "Write(.env)",
      "Write(infra/prod/**)"
    ]
  },
  "disableBundledSkills": false,
  "disableWorkflows": false,
  "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5-20251001"]
}

# Interactive permission management
/permissions

# Useful CLI flags
claude --allowedTools "Read,Grep,Glob"      # restrict tools
claude --disallowedTools "Bash,Write"       # deny specific tools
claude --permission-mode acceptEdits        # auto-accept all edits, still gate Bash

Commands are markdown files in .claude/commands/ (project) or ~/.claude/commands/ (global). They surface as /command-name with tab-completion. For anything that needs supporting files, templates, or subagent delegation, prefer a Skill (§13) instead.

# Create a command
mkdir -p .claude/commands
nano .claude/commands/review-pr.md

# Use it
/review-pr
/fix-issue 123          # $ARGUMENTS passes "123"
/deploy-staging main    # $ARGUMENTS passes "main"

Command Anatomy

--- file: .claude/commands/commit.md ---
---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
description: Create a semantic git commit from staged changes
---

## Context
- Current status: !`git status`
- Current diff: !`git diff HEAD`
- Branch: !`git branch --show-current`
- Recent commits: !`git log --oneline -5`

Create a conventional commit message (type(scope): description) for these changes.
Stage all relevant files and commit.

Built-in Commands Reference

Skills are the evolution of custom commands: directories under .claude/skills/ (project) or ~/.claude/skills/ (personal, applies to every project) with a SKILL.md entrypoint, plus optional supporting files, templates, scripts, and reference docs. Unlike commands, skills are not code that runs — they're structured instructions Claude reads and follows, optionally delegating to a subagent.

# Directory structure
.claude/skills/
  code-review/
    SKILL.md          # entrypoint, metadata
    checklist.md       # supporting doc
    templates/
      review.md
  train-eval/
    SKILL.md
    scripts/
      evaluate.py

--- .claude/skills/train-eval/SKILL.md ---
---
name: train-eval
description: Run a training evaluation loop and compare checkpoints. Use when asked to evaluate, benchmark, or compare model checkpoints.
allowed-tools: [Bash, Read, Write, Grep]
agent: general-purpose
context: fork
---

# Training Evaluation Skill

## Steps
1. Read the active config from configs/active.yaml
2. Run: python scripts/evaluate.py --checkpoint $ARGUMENTS
3. Parse the run URL from stdout
4. Summarize eval metrics in a markdown table
5. Compare against baseline in configs/baselines.yaml

Include ultrathink to deeply analyze any regression.

Skills vs. MCP Connections

They're complementary: a code-review skill tells Claude how to review code; a GitHub MCP connector gives it PRs to review. Together, Claude pulls the PR via MCP and reviews it using the skill's standards.

# Hide Claude's built-in bundled skills/commands (v2.1.169+)
# .claude/settings.json
{ "disableBundledSkills": true }

A plugin bundles one or more skills, along with optional hooks and MCP server configs, into a single installable package. Plugins are the distribution format; skills are the content. Anthropic ships an official marketplace (claude-plugins-official) alongside dozens of community marketplaces.

# Browse the built-in Discover tab
/plugin

# Add a marketplace, then install from it
/plugin marketplace add anthropics/claude-plugins-official
/plugin install code-simplifier@claude-plugins-official
/plugin install security-guidance@claude-plugins-official

# Add a community marketplace by GitHub repo
/plugin marketplace add owner/repo
/plugin install some-skill@repo-marketplace

# Install by domain bundle (community pattern)
claude /plugin install engineering-skills
claude /plugin install devops-skills

Hooks intercept Claude Code's lifecycle and run your code — shell scripts, HTTP endpoints, LLM prompts, or agents — at specific events. Unlike CLAUDE.md's probabilistic "should do" guidance, hooks are deterministic: they run every time, and they still fire even in bypass permission mode.

# .claude/settings.json — hooks section
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "python hooks/block_dangerous.py"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "prettier --write $CLAUDE_TOOL_INPUT_FILE_PATH"
        }]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [{
          "type": "command",
          "command": "notify-send 'Claude Code' 'Session complete'"
        }]
      }
    ]
  }
}

Hook Events

Hook Handler Types

--- hooks/block_dangerous.py ---
import json, sys, re

data = json.load(sys.stdin)
cmd = data.get("tool_input", {}).get("command", "")

BLOCKED = [r"rm\s+-rf", r"curl.*\|\s*bash", r":(){:|:&};:"]
for pattern in BLOCKED:
    if re.search(pattern, cmd):
        print(json.dumps({"decision": "block", "reason": f"Blocked: {pattern}"}))
        sys.exit(0)

sys.exit(0)  # allow

Claude Code's main session can delegate work to subagents through the Task tool. Each subagent runs in its own isolated context window, with its own model, tool access, and cache — results return to the caller as a distilled summary, keeping the main thread's context clean.

# Open Agent View — research-preview operations dashboard
claude agents

# Scope to one directory
claude agents --cwd ./services/api

# Dispatch flags for background sessions (v2.1.142+)
claude agents --add-dir ./libs --model claude-sonnet-5 --effort high --permission-mode acceptEdits

Custom subagents live in .claude/agents/ (project) or ~/.claude/agents/ (personal) as markdown files with YAML frontmatter. Claude Code can run up to 10 subagents in parallel, and subagents can themselves spawn nested subagents (since v2.1.172).

--- .claude/agents/reviewer.md ---
---
name: reviewer
description: Reviews code changes for correctness, security, and test coverage. Use proactively after any implementation is complete, or when asked to review, compare, or audit changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are an expert code reviewer.

When reviewing a change:
1. Run the test suite and linter
2. Check for injection risks, unhandled errors, and missing edge cases
3. Flag any diff that touches auth, payments, or data-deletion paths for extra scrutiny
4. Output a structured markdown report: status, key findings, recommendations

Return only the report — no preamble.

# Invoke a custom agent directly
@reviewer check the changes from the last commit

# Or let Claude auto-delegate by description match
> "Review the auth module changes"  # Claude delegates if a subagent's description matches

Meta-Agent (Agent That Builds Agents)

--- .claude/agents/meta-agent.md ---
---
name: meta-agent
description: Generates new subagent definitions from natural language descriptions. Use when asked to "build a new agent" or "create a subagent for..."
---

Given a description, produce a properly formatted .claude/agents/*.md file
following the project's agent standards. Ask clarifying questions if needed.

> "Build a new subagent that monitors bundle size after every build"
# meta-agent creates .claude/agents/bundle-size-monitor.md automatically

Builder + Validator

--- .claude/agents/validator.md ---
---
name: validator
description: Validates code changes for correctness, security, and test coverage. Use after implementation is complete.
tools: Read, Bash, Grep
model: sonnet
---
Run: the test suite, linter, type-checker, and a security scanner.
Return: PASS or FAIL with specific findings.

# In a session
> "Implement the rate limiter, then validate it"
# Claude builds → spawns validator → reports consolidated result
# The agent that wrote the code never grades its own work.

Parallel Worktree Agents

# Run 3 agents on different features simultaneously
claude -w feature-auth &
claude -w feature-billing &
claude -w feature-notifications &
wait
# Each works in an isolated git worktree — no conflicts
git merge feature-auth feature-billing feature-notifications

Dynamic Workflows — Automatic Orchestration

Introduced with Opus 4.8 (v2.1.154, May 28, 2026): when triggered by the ultracode keyword or /effort ultracode, Claude writes a small orchestration script that a background runtime executes, coordinating up to 16 concurrent subagents per task (tens to hundreds across a full session). Intermediate results live in script variables, not the main context window — this is what lets it scale past what a single conversation can coordinate.

/goal sets a verifiable end condition. Claude works toward it continuously — spawning subagents, running tests, iterating — until a separate evaluator confirms the condition is met, or a budget is exhausted. No more typing "keep going" every few files; the loop self-terminates when the goal is actually verified, not when Claude feels done.

# A useful /goal prompt carries the full control contract.
# The goal line itself is the least important part.

/goal "Fix all failing tests in packages/api"

Context:
  - Failing tests: [paste output of `npm test 2>&1`]
  - Codebase: TypeScript, Express, Prisma ORM
  - Do NOT modify test files — fix the implementation only

Verifier:         run `npm test` after each change batch
                  pass condition: exit code 0, 0 failed tests

Evidence:         paste final test output as proof of completion

Budget:
  max_turns:      25
  max_duration:   45 minutes
  max_cost:       $2.00

Stop conditions:
  ✓ All tests pass (exit 0)
  ✗ Budget hit → summarize work done, open issues list, stop
  ✗ Same test fails 3 times in a row → stop, explain blocker

Do NOT:
  - Skip or disable failing tests
  - Modify test expectations
  - Leave TODO comments as fixes

# Headless / scripted usage — run against a prompt file until
# the goal is marked complete or the iteration limit is reached

# prompt.md
Task: Bring test coverage on src/billing/ above 85%.
Done when: coverage report shows >=85%, all new tests pass, PR is open.
Limit: 20 iterations.

claude --headless -p "$(cat prompt.md)"

Model Context Protocol gives Claude Code access to databases, APIs, and services through a standardized interface. Hundreds of servers are available, official and community-maintained.

# .claude/mcp.json — project MCP config
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" },
      "request_timeout_ms": 120000
    },
    "postgres": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
    }
  }
}

# Manage MCP servers interactively
/mcp                         # list connected servers + tool counts, flags zero-tool connections
claude --mcp-server github   # enable specific server

# Use in prompts naturally
> "Open a GitHub issue for the rate-limiter bug and assign it to me"
> "Query the last 5 failed CI runs and summarize what broke"

The Agent SDK lets you build custom agent orchestrators in TypeScript or Python — with full control over tool access, hooks, subagents, and permissions. Use it when Claude Code's interactive mode isn't enough and you need to embed agentic behavior into your own service.

TypeScript SDK

import { query, type ClaudeCodeOptions } from "@anthropic-ai/claude-code";

const options: ClaudeCodeOptions = {
  maxTurns: 10,
  model: "claude-sonnet-5",
  allowedTools: ["Read", "Write", "Bash", "Grep"],
  systemPrompt: "You are a specialist reviewer for this codebase...",
  hooks: {
    PreToolUse: async (input) => {
      if (input.tool_name === "Bash" && input.tool_input.command.includes("rm -rf")) {
        return { decision: "block", reason: "Destructive command blocked" };
      }
    },
    Stop: async (input) => {
      console.log(`Session ended: ${input.session_id}`);
    }
  }
};

for await (const message of query({
  prompt: "Audit the auth module for injection risks",
  options
})) {
  console.log(message);
}

.github/workflows/claude-review.yml
name: Claude Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropic/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Review this PR diff for bugs, security issues, and test coverage gaps"
          permission-mode: plan

Claude Code speaks the Anthropic Messages API natively, but it can be pointed at any Anthropic-compatible or OpenAI-compatible endpoint — including local inference via Ollama and open-weight models from Zhipu (GLM), Moonshot (Kimi), MiniMax, Alibaba (Qwen), and DeepSeek.

Native Ollama Routing (Simplest Path)

Ollama ships native Anthropic API compatibility, so no proxy is required for basic use — just point the two environment variables at your local Ollama instance.

# ~/.claude/settings.json — environment overrides
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:11434",
    "ANTHROPIC_AUTH_TOKEN": "ollama",
    "ANTHROPIC_API_KEY": ""
  }
}

# Pull and run a local model
ollama pull qwen3.6:27b
claude --model qwen3.6:27b

# Guided setup
ollama launch claude --config

Ollama Cloud — Frontier Open-Weight Models, No GPU Required

Models tagged :cloud (e.g. glm-5.1:cloud, kimi-k2.6:cloud, deepseek-v4-pro:cloud) run on Ollama's infrastructure rather than your hardware — same environment variables, but your prompts leave the machine. Useful when local hardware can't fit a frontier-class open model.

ollama pull glm-5.1:cloud
claude --model glm-5.1:cloud
# Ollama Cloud plans: Free / Pro (~$20/mo) / Max (~$100/mo)

Recommended Open-Weight Models (mid-2026)

Claude Code Router — Per-Request-Type Routing

For finer control than a single global backend, @musistudio/claude-code-router is an open-source proxy that intercepts Claude Code's requests and routes each request type to a different provider — useful because a coding session isn't one workload: summarizing a diff is a throwaway task, planning a refactor is a reasoning task, and applying an edit is where quality matters most.

# Launch with the router instead of `claude`
npm install -g @musistudio/claude-code-router
ccr code

# config.json — route each request type to a different provider/model
{
  "Providers": [
    { "name": "ollama", "api_base_url": "http://localhost:11434/v1/chat/completions", "models": ["qwen3.6:27b"] },
    { "name": "deepseek", "api_base_url": "https://api.deepseek.com/v1", "api_key": "${DEEPSEEK_API_KEY}", "models": ["deepseek-v4-pro-max"] }
  ],
  "Router": {
    "default":     "ollama,qwen3.6:27b",
    "background":  "ollama,qwen3.6:27b",
    "think":       "deepseek,deepseek-v4-pro-max",
    "longContext": "deepseek,deepseek-v4-pro-max"
  }
}

# Override any route mid-session
/model provider,model-name

• /context — view token usage as a colored grid before you hit a wall
• /compact — summarize and compress when context gets heavy mid-task
• /clear — hard reset between unrelated tasks; don't carry stale context forward
• /fork — branch into a background session to explore a risky change without polluting the main thread
• Push verbose, read-heavy operations (large file scans, log parsing) into subagents — their context doesn't count against your main window
• Keep CLAUDE.md lean (§10) and move deep reference material into Skills, loaded only when relevant

Curriculum-Aware Slash Command

--- .claude/commands/run-suite.md ---
---
allowed-tools: Bash(npm:*), Read, Write
description: Run a named test suite and summarize failures
---

Run test suite $ARGUMENTS:
1. Validate config: !`cat configs/$ARGUMENTS.yaml`
2. Run: npm test -- --suite=$ARGUMENTS
3. If failures, invoke @reviewer on the failing files
4. Log a one-line summary to CHANGELOG-tests.md

Post-Deploy Verification Hook

--- hooks/post-deploy-check.sh ---
#!/bin/bash
# PostToolUse hook on Bash — triggers after any deploy script
INPUT=$(cat)
CMD=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_input',{}).get('command',''))")

if echo "$CMD" | grep -q "deploy.sh"; then
  echo '{"systemMessage": "Deploy finished. Run @reviewer against the release diff."}'
fi

# Useful debug commands
/doctor          # full diagnostics
/context         # token grid
claude --version # verify version
claude update    # update to latest

# Read raw session transcripts
ls ~/.claude/projects/
cat ~/.claude/projects/<project-hash>/<session-id>.jsonl | jq .

Official Docs

• Overview code.claude.com/docs/en/overview
• Changelog code.claude.com/docs/en/changelog
• CLI ref docs.claude.com — CLI Reference
• Model config code.claude.com/docs/en/model-config
• Permission modes code.claude.com — Permission modes
• Auto mode claude.com/blog/auto-mode
• Auto mode engineering anthropic.com/engineering — How we built auto mode
• Hooks code.claude.com/docs/en/hooks
• Skills code.claude.com/docs/en/skills
• Plugins code.claude.com/docs/en/plugins
• Subagents SDK platform.claude.com — Subagents
• MCP docs.claude.com — MCP
• GHA docs.claude.com — GitHub Actions
• CLAUDE.md docs.claude.com — Memory & CLAUDE.md
• Models overview platform.claude.com — Models overview
• Fable / Mythos anthropic.com/news — Fable & Mythos access notice

Community Resources

• Awesome CC github.com/hesreallyhim/awesome-claude-code
• Hooks mastery github.com/disler/claude-code-hooks-mastery
• Router github.com/musistudio/claude-code-router
• Compatible models github.com/Alorse/cc-compatible-models
• Skills marketplace claudemarketplaces.com

Prompt Engineering for Claude Code

• Prompting docs.claude.com — Prompt engineering overview
• Extended thinking docs.claude.com — Extended thinking