Claude Code CLI: The Definitive Technical Reference

TL;DR: Claude Code is an agentic CLI that reads your codebase, executes commands, and modifies files through a layered system of permissions, hooks, MCP integrations, and subagents. Master five core systems (configuration, permissions, hooks, MCP, and subagents) and you unlock force-multiplier productivity. Choose the model tier that fits each task — Opus for complex reasoning, Sonnet for general work, Haiku for fast exploration — or standardize on Opus if quality is your only variable. Use hooks (not prompts) for anything that must always execute.

Claude Code operates as an agentic system, not a chat interface with programming knowledge. The CLI reads your codebase, executes commands, modifies files, manages git workflows, connects to external services via MCP, and delegates complex tasks to specialized subagents. Everything flows through a command-line interface that integrates into how developers actually work.

The difference between casual and effective Claude Code usage comes down to five core systems. Master these and Claude Code becomes a force multiplier:

1. Configuration hierarchy: controls behavior
2. Permission system: gates operations
3. Hook system: enables deterministic automation
4. MCP protocol: extends capabilities
5. Subagent system: handles complex multi-step tasks

Key Takeaways

• Five systems determine your effectiveness: configuration hierarchy, permissions, hooks, MCP, and subagents control everything from behavior to automation.
• Push work to the Delegation Layer: subagents prevent context bloat by isolating exploration in clean context windows, returning only summaries.
• Hooks guarantee execution; prompts do not: use hooks for linting, formatting, and security checks that must run every time regardless of model behavior.
• Model tiering saves cost without sacrificing quality: route subagent exploration to cheaper models and reserve Opus for genuine architectural reasoning — or standardize on Opus if quality is your only variable.
• MCP connects Claude to your toolchain: databases, GitHub, Sentry, and 3,000+ integrations extend Claude beyond file reading and bash commands.

I spent months pushing Claude Code to its limits across production codebases, CI/CD pipelines, and enterprise deployments. This guide distills that experience into the complete reference I wish existed when I started. Every feature includes actual syntax, real configuration examples, and the edge cases that trip up experienced users.

How to Use This Guide

This is a 5,000+ line reference — you don’t need to read it cover to cover. Start where your experience level fits:

Use your browser’s Ctrl+F / Cmd+F to search for specific flags, commands, or configuration keys. The Quick Reference Card at the end provides a scannable summary of all major commands.

How Claude Code Works: The Mental Model

Before diving into features, understand how Claude Code’s architecture shapes everything you do with it. The system operates in three layers:

┌─────────────────────────────────────────────────────────┐
│                    CLAUDE CODE LAYERS                    │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  External tools, deterministic automation, domain       │
│  expertise, packaged extensions                          │
├─────────────────────────────────────────────────────────┤
│  DELEGATION LAYER                                        │
│  ┌─────────────────────────────────────────────────┐    │
│  │              Subagents (up to 10 parallel)       │    │
│  │   Explore | Plan | General-purpose | Custom      │    │
│  └─────────────────────────────────────────────────┘    │
│  Isolated contexts for focused work, returns summaries  │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         Main Conversation Context                │    │
│  │   Tools: Read, Edit, Bash, Glob, Grep, etc.     │    │
│  └─────────────────────────────────────────────────┘    │
│  Your primary interaction; limited context; costs money │
└─────────────────────────────────────────────────────────┘

Core Layer: Your main conversation. Every message, file read, and tool output consumes context from a shared window (200K tokens standard⁹⁸, 1M tokens with Opus 4.6 or extended context models). When context fills, Claude loses track of earlier decisions and quality degrades. This layer costs money per token.

Delegation Layer: Subagents spawn with clean contexts, do focused work, and return summaries. The exploration results don’t bloat your main conversation; only the conclusions return. Route subagents to cheaper model tiers for exploration, or use your primary model throughout if quality matters more than cost.

Extension Layer: MCP connects external services (databases, GitHub, Sentry). Hooks guarantee execution of shell commands regardless of model behavior. Skills encode domain expertise that Claude applies automatically. Plugins package all of these for distribution.

The key insight: Most users work entirely in the Core Layer, watching context bloat and costs climb. Power users push exploration and specialized work to the Delegation Layer, keep the Extension Layer configured for their workflow, and use the Core Layer only for orchestration and final decisions.

Table of Contents

1. How Do I Install Claude Code?
2. Quick Start: Your First Session
3. Core Interaction Modes
4. Configuration System Deep Dive
5. Which Model Should I Choose?
6. What Does Claude Code Cost?
7. Decision Frameworks
8. How Does the Permission System Work?
9. How Do Hooks Work?
10. What Is MCP (Model Context Protocol)?
11. What Are Subagents?
12. What Is Extended Thinking Mode?
13. Output Styles
14. Slash Commands
15. How Do Skills Work?
16. Plugin System
17. How Does Memory Work?
18. Image and Multimodal Input
19. How Does Git Integration Work?
20. How Do I Use Claude Code in My IDE?
21. Advanced Usage Patterns
22. Remote & Background Agents [RESEARCH PREVIEW]
23. Claude in Chrome
24. Claude Code in Slack [RESEARCH PREVIEW]
25. Performance Optimization
26. How Do I Debug Issues?
27. Enterprise Deployment
28. Keyboard Shortcuts Reference
29. Best Practices
30. Workflow Recipes
31. Migration Guide
32. Audience-Specific Guidance
33. Quick Reference Card
34. Changelog
35. References

How Do I Install Claude Code?

System Requirements

Claude Code runs on macOS 10.15+, Ubuntu 20.04+/Debian 10+, and Windows 10+ through WSL or Git Bash. The system requires 4 GB RAM minimum and an active internet connection.⁹⁹ Shell compatibility works best with Bash, Zsh, or Fish.

For Windows, both WSL 1 and WSL 2 work. Git Bash also works if you prefer native Windows. Alpine Linux and other musl-based systems require additional packages:

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

Installation Methods

Native installation (recommended)

The native binary provides the cleanest experience with no Node.js dependency:

# macOS and Linux
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew alternative
brew install --cask claude-code

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

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

For version-specific installation:

# Install specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

# Install latest explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Windows PowerShell - specific version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

NPM installation (deprecated)

Note: As of v2.1.15, npm installations show a deprecation notice. The native binary is now the recommended installation method. Migrate with claude install.

For legacy environments where npm is still needed:

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

Never use sudo with npm installation. It creates permission issues that complicate everything downstream.

Migration from existing installation

If you have an older npm-based installation, migrate to the native binary:

claude install

Authentication Options

Claude Code supports three authentication paths, each with different tradeoffs:

Claude Console (API billing)

Connect to Anthropic’s API directly through platform.claude.com (previously console.anthropic.com). Create an account, set up billing, and authenticate through the CLI. The Console provides usage-based billing with full API access. A dedicated “Claude Code” workspace is created automatically; you cannot create API keys for this workspace, but you can monitor usage.

Claude Pro or Max subscription

Use your claude.ai account credentials. The subscription covers both the web interface and CLI usage under a single monthly plan. The subscription simplifies billing for individual users who want predictable costs.

Enterprise platforms

AWS Bedrock, Google Vertex AI, and Microsoft Foundry each provide enterprise-grade access with existing cloud billing relationships:

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-profile

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project

# Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
# Optional: API key auth (otherwise uses Entra ID)
export ANTHROPIC_FOUNDRY_API_KEY=your-key

For enterprise deployments behind proxies or through LLM gateways:

# Corporate proxy
export HTTPS_PROXY='https://proxy.example.com:8080'

# LLM gateway (skip native auth)
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

Verification

claude doctor

The command reports installation type, version, system configuration, and any detected issues.

Authentication Management (v2.1.41+)

Manage authentication without entering the REPL:⁹⁷

claude auth login          # Log in or switch accounts
claude auth status         # Check current auth state (account, plan, expiry)
claude auth logout         # Clear stored credentials

Common workflow for switching between accounts or organizations:

claude auth logout && claude auth login

See also: How Do I Debug Issues? for troubleshooting authentication failures.

Updates

Claude Code auto-updates by default, checking at startup and periodically during sessions. Updates download in the background and apply on next launch.

Disable auto-updates:

export DISABLE_AUTOUPDATER=1

Or in settings.json:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

Manual update:

claude update

Uninstallation

Native installation (macOS/Linux/WSL):

rm -f ~/.local/bin/claude
rm -rf ~/.claude-code

Native installation (Windows PowerShell):

Remove-Item -Path "$env:LOCALAPPDATA\Programs\claude-code" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\Microsoft\WindowsApps\claude.exe" -Force

Clean configuration (removes all settings):

rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json

Quick Start: Your First Session

1. Install and launch:

claude                           # Launch in current directory

2. Navigate to a project:

cd ~/my-project && claude        # Or launch from any git repo

3. Ask Claude to do something:

> "Explain the architecture of this project"
> "Find all TODO comments and create a summary"
> "Add input validation to the signup form"

4. Use key shortcuts during your session:

/cost                            # Check token usage and cost
/compact                         # Free up context when it gets large
Alt+T                            # Toggle extended thinking for hard problems
Ctrl+C                           # Cancel current response

5. Continue later:

claude -c                        # Resume your most recent session
claude --resume                  # Pick from session list

Expert tip: Create a CLAUDE.md file in your project root with build commands, coding conventions, and architecture notes. Claude reads it every session — it’s the single highest-leverage thing you can do for quality.

Core Interaction Modes

Interactive REPL

Launch Claude Code without arguments to enter the interactive read-eval-print loop:

cd your-project
claude

The REPL maintains conversation context across turns. Type queries directly, receive responses, and continue until you exit with /exit or Ctrl+D.

Start with an initial prompt to focus the session:

claude "explain the authentication flow in this project"

Expert tip: The REPL persists state across compaction events. When context grows too large, Claude automatically summarizes older conversation while preserving key decisions and code snippets. You can trigger this manually with /compact or add custom instructions for what to preserve.

Non-Interactive Mode

Print mode (-p) executes a single query and exits:

# Direct query
claude -p "list all TODO comments in this project"

# Process piped input
cat error.log | claude -p "identify the root cause of these failures"

# Chain with other tools
claude -p "generate a README" > README.md

For structured output suitable for parsing in scripts:

claude -p "count lines by file type" --output-format json

The JSON output includes everything you need for automation:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.0034,
  "is_error": false,
  "duration_ms": 2847,
  "duration_api_ms": 1923,
  "num_turns": 4,
  "result": "Response text here...",
  "session_id": "abc-123-def"
}

For real-time processing of streaming output:

claude -p "build the application" --output-format stream-json | while read line; do
  echo "$line" | jq -r 'select(.result) | .result'
done

Output format options:

Exit codes:

Controlling agentic behavior in -p mode:

# Limit autonomous turns (prevents runaway loops)
claude -p "refactor the auth module" --max-turns 10

# Allow specific tools without prompting
claude -p "fix lint errors" --allowedTools "Edit,Bash(npm run lint)"

# Use with a specific model
claude -p "explain this code" --model claude-sonnet-4-5-20250929

CI/CD integration pattern:

# In a GitHub Action or CI pipeline
result=$(claude -p "review this diff for security issues" --output-format json 2>/dev/null)
is_error=$(echo "$result" | jq -r '.is_error')
if [ "$is_error" = "true" ]; then
  echo "Review failed"
  exit 1
fi
echo "$result" | jq -r '.result'

Session Management

Sessions persist conversation history for continuation. Session persistence is essential for complex multi-session work:

# Continue most recent session
claude -c

# Continue with additional prompt
claude -c -p "now add error handling"

# Resume specific session by ID
claude -r "abc123" "implement the remaining tests"

# Fork a session for parallel exploration
claude -r "base-session" --fork-session "try a different approach"

PR-linked sessions (v2.1.27+): Start a session linked to a specific pull request:⁸¹

claude --from-pr 123                                    # By PR number
claude --from-pr https://github.com/org/repo/pull/123   # By URL

Sessions also auto-link to PRs when you create them via gh pr create during a session. This makes it easy to resume work on a specific PR later.

Named sessions (Dec 2025): Name and manage sessions for easy recall:

# Name current session
> /rename auth-refactor

# Resume by name or number
> /resume 1                    # Resume first session
> /resume auth-refactor        # Resume by name
claude --resume auth-refactor  # Resume from terminal
claude -r 3                    # Resume by number from terminal

# Fork for parallel exploration
claude --resume auth-refactor --fork-session

Note: --session-id requires a valid UUID (e.g., 550e8400-e29b-41d4-a716-446655440000). For human-readable session naming, use /rename and --resume instead.

Claude Code stores sessions as JSONL transcripts. Agent execution assigns unique agentId values with transcripts stored as agent-{agentId}.jsonl. Resume preserves full context from previous conversations.

Plan Mode

Plan mode restricts Claude to read-only exploration—no file edits, no bash execution, no destructive actions. Claude designs an implementation approach, writes it to a plan file, and waits for your approval before executing anything.

Entering plan mode:

# Cycle through modes during a session
Shift+Tab           # Cycles: normal → plan → auto-accept

# Or ask Claude directly
"Plan how to refactor the auth module"   # Claude may enter plan mode automatically

How it works:

1. Claude enters plan mode (automatically for complex tasks, or via Shift+Tab)
2. Explores the codebase using read-only tools: Read, Glob, Grep, WebSearch, WebFetch
3. Writes a plan to .claude/plans/{session-slug}.md
4. Exits plan mode with ExitPlanMode, presenting the plan for your review
5. You approve, request changes, or reject

Available tools in plan mode: Read, Glob, Grep, LS, WebSearch, WebFetch, AskUserQuestion. Editing tools (Edit, Write, Bash, NotebookEdit) are blocked.

After plan approval (v2.1.32+): Claude offers three options: - “Yes, clear context and auto-accept edits” (Shift+Tab) — starts fresh with full context for the plan - “Yes, and manually approve edits” — preserves context, you approve each change - “Yes, auto-accept edits” — preserves context, Claude executes without per-edit approval

Auto-clearing context on approval is the recommended workflow. It gives the plan a fresh context window, which significantly improves plan adherence—Claude stays on track longer without old conversation interfering.

When to use plan mode: - New feature implementations with architectural decisions - Multi-file refactors where you want to review the approach first - Unfamiliar codebases where exploration should precede modification - Any task where multiple valid approaches exist and you want input

Expert tip: The more time you spend in plan mode, the more likely Claude will succeed at implementation. Plan mode is effectively free exploration—no risky tool calls, no wasted edits. Use it liberally.

Configuration System Deep Dive

Claude Code uses a layered configuration system. Understanding the hierarchy is essential because higher levels override lower ones, and enterprise settings cannot be bypassed at all.

Configuration Hierarchy

Expert tip: Use .claude/settings.local.json for personal preferences in shared projects (add it to .gitignore). Use .claude/settings.json for team-wide configuration that gets checked into version control.

Complete settings.json Reference

A full configuration demonstrating all major options:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-5-20250929",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)",
      "Bash(make:*)",
      "Edit(src/**)",
      "Write(src/**)",
      "mcp__github"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(package-lock.json)",
      "Edit(.git/**)"
    ],
    "ask": [
      "WebFetch",
      "Bash(curl:*)",
      "Bash(docker:*)"
    ],
    "additionalDirectories": [
      "../shared-lib",
      "../docs"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory",
  "language": "en",
  "respectGitignore": true,
  "showTurnDuration": true,
  "plansDirectory": ".claude/plans",
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"],
  "spinnerTipsOverride": {
    "tips": ["Custom tip 1", "Custom tip 2"],
    "excludeDefault": true
  }
}

Environment Variables Reference

Authentication and API:

ANTHROPIC_API_KEY=sk-ant-...                    # Direct API authentication
ANTHROPIC_AUTH_TOKEN=token                      # Custom authorization header
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Additional request headers

Model configuration:

ANTHROPIC_MODEL=claude-opus-4-6                 # Override default model
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6    # Opus 4.6 (Feb 2026)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5-20250929
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Model for subagents
MAX_THINKING_TOKENS=10000                       # Enable extended thinking
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # Limit output length
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1          # Enable agent teams (v2.1.32+)

Cloud provider configuration:

CLAUDE_CODE_USE_BEDROCK=1                       # Use AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1                        # Use Google Vertex AI
CLAUDE_CODE_USE_FOUNDRY=1                       # Use Microsoft Foundry
ANTHROPIC_BEDROCK_BASE_URL=https://...          # Custom Bedrock endpoint
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # Skip Bedrock auth (for gateways)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # Skip Vertex auth
AWS_BEARER_TOKEN_BEDROCK=token                  # Bedrock bearer token
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # Override Vertex region

Behavior control:

DISABLE_AUTOUPDATER=1                           # Prevent automatic updates
DISABLE_TELEMETRY=1                             # Opt out of usage telemetry
DISABLE_ERROR_REPORTING=1                       # Disable Sentry
DISABLE_BUG_COMMAND=1                           # Disable /bug command
DISABLE_COST_WARNINGS=1                         # Hide cost warnings
DISABLE_PROMPT_CACHING=1                        # Disable prompt caching globally
DISABLE_PROMPT_CACHING_SONNET=1                 # Disable for Sonnet only
DISABLE_PROMPT_CACHING_OPUS=1                   # Disable for Opus only
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # Skip non-critical API calls

Tool configuration:

BASH_DEFAULT_TIMEOUT_MS=30000                   # Bash command timeout (30s)
BASH_MAX_TIMEOUT_MS=600000                      # Maximum bash timeout (10min)
BASH_MAX_OUTPUT_LENGTH=50000                    # Bash output limit
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # Reset CWD after each bash
MCP_TIMEOUT=5000                                # MCP server startup timeout
MCP_TOOL_TIMEOUT=30000                          # MCP tool execution timeout
MAX_MCP_OUTPUT_TOKENS=25000                     # MCP output limit
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Slash command context limit

Network and proxy:

HTTP_PROXY=http://proxy:8080                    # HTTP proxy
HTTPS_PROXY=https://proxy:8080                  # HTTPS proxy
NO_PROXY=localhost,example.com                  # Bypass proxy for domains
CLAUDE_CODE_CLIENT_CERT=/path/to/cert           # mTLS certificate
CLAUDE_CODE_CLIENT_KEY=/path/to/key             # mTLS private key
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE=pass          # mTLS passphrase

UI and terminal:

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Don't update terminal title
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Skip IDE extension install
CLAUDE_CODE_SHELL=/bin/zsh                      # Override shell detection
USE_BUILTIN_RIPGREP=1                           # Use included ripgrep (default)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Custom config directory
IS_DEMO=1                                       # Hide sensitive UI elements[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Disable background tasks and Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # Override temp directory[^50]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Disable 1M context window (use standard 200K)[^103]
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000       # Plugin marketplace git timeout (default 120s, was 30s)[^105]

SDK caller identity (v2.1.51+):

CLAUDE_CODE_ACCOUNT_UUID=uuid                  # Provide account UUID synchronously for SDK callers
CLAUDE_CODE_USER_EMAIL=[email protected]        # Provide user email for SDK callers
CLAUDE_CODE_ORGANIZATION_UUID=uuid             # Provide organization UUID for SDK callers

Debugging:

ANTHROPIC_LOG=debug                             # Enable API request logging

Which Model Should I Choose?

Choosing the right model for each task significantly impacts both cost and quality. Claude Code provides flexible model switching at multiple levels.

Available Models

Opus 4.6 (February 5, 2026): The latest flagship model with 1M token context window (beta), 128K max output, adaptive thinking, and agent teams.⁸⁶ Same pricing as Opus 4.5 ($5/$25 per MTok). Long context (>200K input) costs $10/$37.50 per MTok. Model ID: claude-opus-4-6.¹

Sonnet 4.6 (February 17, 2026): The new balanced model replacing Sonnet 4.5 as the default across claude.ai and Claude Cowork.¹⁰⁰ Same pricing as Sonnet 4.5 ($3/$15 per MTok). Improved agentic search performance while consuming fewer tokens. Supports extended thinking, adaptive thinking, and a 1M token context window (beta). 64K max output. Knowledge cutoff: August 2025 (reliable), January 2026 (training data). Model ID: claude-sonnet-4-6. Sonnet 4.5 is now a legacy model.¹⁰⁰

Why these price differences matter: A typical coding session consumes 50K-200K input tokens and 10K-50K output tokens. With Haiku, that’s $0.10-$0.45 per session. With Opus, the same session costs $0.50-$2.25, 5x more. Reserve Opus for genuinely hard problems.¹

When to Use Each Model

Haiku: Use for subagents doing exploration, simple file searches, quick questions. It’s ~5x cheaper than Opus and responds faster. Perfect for background tasks where you don’t need deep reasoning.

Sonnet: The workhorse for daily development. Handles most coding tasks well: implementing features, fixing bugs, writing tests, code review. Use this as your default. Sonnet 4.6 (February 2026) delivers improved agentic search and better token efficiency compared to Sonnet 4.5, with adaptive thinking support and the 1M context window beta.¹⁰⁰

Opus: Reserve for genuinely complex reasoning: architectural decisions, tricky debugging, understanding complex systems, security analysis. Opus 4.6 (February 2026) is a significant step up: it plans more carefully, sustains agentic tasks longer, operates more reliably in large codebases, and catches its own mistakes better during code review.⁸⁶ It features a 1M token context window in beta and introduces adaptive thinking that automatically determines reasoning depth. According to Anthropic, on Terminal-Bench 2.0, Opus 4.6 achieves the highest industry agentic coding score. On GDPval-AA (economically valuable knowledge work), Anthropic reports it outperforms GPT-5.2 by ~144 Elo points.⁸⁶ Note: Pro subscription users have access to Opus as part of their subscription.²⁰

Opusplan: A hybrid mode that uses Opus for planning (where reasoning quality matters most) and Sonnet for execution (where speed matters). Excellent for complex refactoring where you want the best plan but don’t need Opus-level reasoning for each individual edit.

Switching Models

During session:

> /model opus
> /model sonnet
> /model haiku

At startup:

claude --model opus

Via environment:

export ANTHROPIC_MODEL=opus

In settings.json:

{
  "model": "claude-sonnet-4-5-20250929"
}

For subagents specifically:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

Extended Context

For large codebases or long sessions, enable 1M token context:

claude --model sonnet[1m]
claude --model opus[1m]           # Opus 4.6 with 1M context (beta)

Or within a session:

> /model sonnet[1m]
> /model opus[1m]

Opus 4.6 is the first Opus-class model with native 1M context support. It achieves 76% accuracy on the 8-needle 1M variant of MRCR v2 (competitors score ~18.5%), making it the strongest model for long-context retrieval.⁸⁶

Extended context costs more per token (2x input, 1.5x output when >200K input tokens). Use it when you actually need it, not as a default.

Checking Current Model

> /status

The command shows current model, account info, applied settings, and other session state.

Model picker labels (v2.1.51+): The /model picker now shows human-readable labels (e.g., “Sonnet 4.6”) instead of raw model IDs for pinned versions, with upgrade hints when newer versions are available.¹⁰⁵

Fast Mode (v2.1.36+)

Fast mode provides significantly faster output from the same model; it does not switch to a cheaper model. Toggle it during a session with /fast.⁹³

> /fast            # Toggle fast mode on/off

Pricing (Opus 4.6 fast mode):

Fast mode pricing applies across the full context window, including requests over 200K input tokens — there is no additional long context surcharge in fast mode.¹ Fast mode pricing stacks with prompt caching and data residency multipliers, but NOT with long context pricing. Fast mode is not available with the Batch API.

When to use fast mode: - Iterating rapidly on small changes where latency is the bottleneck - Generating tests, boilerplate, or repetitive code where speed matters more than cost - Working through a list of similar tasks sequentially

When NOT to use fast mode: - Long-running agentic tasks (cost adds up fast at 6x rates) - Background subagent work (nobody’s waiting for the output) - Budget-conscious sessions

Opus 4.6 fast mode now includes the full 1M context window (v2.1.50+). Previously, fast mode was limited to standard context; now you get the same 1M token capacity at fast mode speeds.¹⁰³

Expert tip: Fast mode pairs well with the opusplan hybrid: use fast mode during the Sonnet execution phase for rapid iteration while keeping standard rates for Opus planning. Note that /fast requires /extra-usage to be enabled first (v2.1.37 fix).⁹³

What Does Claude Code Cost?

Understanding and controlling costs is essential for sustainable Claude Code usage. See also Model Selection for model capabilities and Decision Frameworks for choosing the right model per task.

Viewing Costs

> /cost

Output:

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    247 lines added, 89 lines removed

Subscription Plans

Rate limits (August 2025): Anthropic introduced weekly rate limits for paid subscribers. Max subscribers can purchase additional usage beyond the rate limit at standard API rates.²¹

API Token Pricing (February 2026)¹⁸⁶

For API-billed users, per-million-token pricing:

Long context pricing (>200K input tokens):

The 200K threshold is based on total input tokens (including cache reads/writes). When exceeded, Anthropic bills all tokens at the long context rate.¹

Data residency pricing: Specifying US-only inference via inference_geo adds a 1.1× multiplier on all token pricing (Opus 4.6+ models only).¹

Prompt caching significantly reduces repeated input costs: cache writes cost 1.25× base (5-min cache) or 2× (1-hr cache), but cache reads cost only 0.1×, a 90% savings. For RAG systems and code assistants with repeated context, caching can reduce costs 88-95%.

Batch API offers 50% discounts with 24-hour turnaround for non-urgent tasks like overnight test suites.

Multiple Accounts Policy⁵⁹

Can you have multiple Claude accounts? Yes, for legitimate use cases. Anthropic explicitly permits multiple accounts when they serve distinct purposes.

What’s allowed:

Technical limits: - Up to 3 accounts can be verified with the same phone number - Multiple paid subscriptions from the same IP/network are explicitly supported - Accounts are completely separate; no chat or project transfer between them

What’s prohibited (per the Usage Policy): - Creating accounts to evade bans after being banned - Coordinating malicious activity across accounts to avoid detection - Using multiple accounts to circumvent rate limits or free tier credits

Real-world note: In January 2026, power user Jeffrey Emanuel (@doodlestein) had 22 Max accounts auto-flagged and temporarily banned. Anthropic employee Thariq (@trq212) resolved it within 4 hours after confirming legitimate use. If you’re using Claude Code extensively for both work and personal projects across multiple accounts, that’s exactly what the service is designed for, but don’t try to game the system.

When in doubt: Contact Anthropic Support to confirm your specific setup in writing.

Cost Factors

Real-World Cost Examples

Cost-saving insight: Using Haiku for exploration subagents and Sonnet for implementation typically reduces costs 40-50% compared to using Sonnet for everything.

Team Cost Management

Recommended TPM/RPM by team size:

Hidden Tool Fees

Beyond per-token pricing, some tools incur separate charges:¹⁶

These add up in agent loops. A 100-iteration debug cycle with Bash costs ~24,500 extra input tokens in overhead alone.

Cost-Saving Strategies

1. Use Haiku for subagents: Most exploration doesn’t need Sonnet
2. Enable prompt caching: Default, but verify it’s not disabled
3. Set max turns: claude --max-turns 5 prevents runaway conversations
4. Use plan mode for exploration: No execution = no accidental expensive operations
5. Compact proactively: Smaller context = fewer tokens
6. Limit output: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
7. Batch API for non-urgent work: 50% off both input and output tokens

Monitoring Usage

• Claude Console: platform.claude.com (requires Admin or Billing role)
• Workspace limits: Set spending limits per workspace
• Bedrock/Vertex: Use native cloud cost monitoring
• LiteLLM: For detailed per-user tracking with third-party providers

Background Token Usage

Some operations consume tokens in the background: - Conversation summarization for /resume - /cost and /status commands - Auto-compaction

Typically under $0.04 per session.

Claude Code Analytics API (Team/Enterprise)⁵³

Programmatically access your organization’s Claude Code usage analytics and productivity metrics via the Admin API.

Endpoint: GET /v1/organizations/usage_report/claude_code

Requirements: - Admin API key (sk-ant-admin...) - Team or Enterprise plan - Admin, Billing, or Developer role

Available Metrics:

Example Request:

curl "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2026-01-15" \
  -H "x-api-key: sk-ant-admin..." \
  -H "anthropic-version: 2023-06-01"

Use Cases: - Developer productivity analysis (sessions, commits, PRs) - Tool usage metrics (acceptance/rejection rates for Edit, Write, etc.) - Cost tracking and allocation across teams - ROI justification for AI coding tools

Note: Data appears within 1 hour of activity completion. Only data older than 1 hour is included in responses for consistency.

Decision Frameworks

Knowing features exists isn’t enough. You need to know when to use each. These decision trees transform knowledge into action.

Which Model Should I Use?

START → Is the task simple? (file search, quick question, formatting)
         │
         ├── YES → Use Haiku
         │         Cost: ~$0.03/task
         │         Speed: Fastest
         │
         └── NO → Does it require deep reasoning?
                  (architecture, complex debugging, security analysis)
                  │
                  ├── YES → Use Opus 4.6
                  │         Cost: ~$2.00/task
                  │         Quality: Highest (1M context, adaptive thinking)
                  │
                  └── NO → Use Sonnet (default)
                           Cost: ~$0.75/task
                           Balance: Best overall

Rule of thumb: Start with Sonnet. Drop to Haiku for subagents. Escalate to Opus 4.6 only when Sonnet’s answer feels shallow. With agent teams (v2.1.32+), Opus can coordinate multiple agents working in parallel on different subtasks.⁸⁶

Command vs Skill vs Subagent vs Agent Team?

Do you want explicit control over when it runs?
│
├── YES → Use Slash Command
│         Example: /deploy, /test, /security-review
│         You invoke it. You control timing.
│
└── NO → Should the expertise apply automatically based on context?
         │
         ├── YES → Use Skill
         │         Example: Security patterns, domain rules, code standards
         │         Claude recognizes context and applies expertise.
         │
         └── NO → Does the work need isolated context?
                  │
                  ├── YES → Is there one subtask or many parallel subtasks?
                  │         │
                  │         ├── ONE → Use Subagent (Task tool)
                  │         │         Example: Deep exploration, parallel analysis
                  │         │         Prevents context bloat in main conversation.
                  │         │
                  │         └── MANY → Use Agent Team (v2.1.32+)
                  │                   Example: 5 agents reviewing different modules simultaneously
                  │                   Opus coordinates; each agent works independently.
                  │
                  └── NO → Just prompt directly
                           Not everything needs abstraction.

Hook vs Prompt?

Must the action ALWAYS happen, regardless of Claude's judgment?
│
├── YES → Use Hook (deterministic)
│         Examples:
│         - Format code after every edit
│         - Log all bash commands
│         - Block access to .env files
│         Claude cannot skip, forget, or decide otherwise.
│
└── NO → Use Prompt (probabilistic)
         Examples:
         - "Consider adding tests"
         - "Think about edge cases"
         - "Review for security if relevant"
         Claude decides based on context.

When to Use Extended Thinking?

Is this a genuinely hard problem?
│
├── Architectural decision with many tradeoffs → YES, use thinking
├── Complex debugging with unclear root cause → YES, use thinking
├── Security analysis requiring careful reasoning → YES, use thinking
├── Understanding unfamiliar codebase → YES, use thinking
│
├── Routine bug fix → NO, skip thinking
├── Simple refactoring → NO, skip thinking
├── Code formatting → NO, skip thinking
└── Quick questions → NO, skip thinking

Toggle with Alt+T during session. Higher thinking budgets cost more; start with minimum and increase only if responses feel rushed.

Opus 4.6 adaptive thinking: Opus 4.6 automatically adjusts thinking depth based on problem complexity. For most tasks, explicit thinking budget control isn’t necessary — Opus scales up for hard problems and stays fast for simple ones. Manual thinking toggling is most useful with Sonnet when you want to force deeper analysis.

Which Execution Surface?

Where should this work happen?
│
├── Requires YOUR local files and tools
│   │
│   ├── Interactive, iterative work → Main REPL session
│   ├── One-shot scripted task → claude -p "prompt" (print mode)
│   ├── CI/CD automation → claude -p --json (non-interactive + structured output)
│   └── Parallel isolated tasks → Subagents via Task tool
│
├── Requires SOMEONE ELSE'S environment
│   │
│   └── Remote codebase or server → Background agent (cloud)
│
└── Doesn't require any environment
    │
    ├── Research or analysis → Subagent with Explore type
    └── Web content extraction → WebFetch / WebSearch tools

Agent Teams vs Subagents vs Parallel Sessions

Do you need multiple agents working on related subtasks?
│
├── YES → Are the subtasks independent (no shared state)?
│         │
│         ├── YES → Can they share the same codebase?
│         │         │
│         │         ├── YES → Use Agent Team (v2.1.32+)
│         │         │         Opus coordinates. Agents share repo access.
│         │         │         Example: "Review auth, API, and DB modules in parallel"
│         │         │
│         │         └── NO → Use Parallel Sessions (separate terminals)
│         │                  Each has its own working directory.
│         │                  Example: "Fix repo-A and repo-B simultaneously"
│         │
│         └── NO → Use Sequential Subagents
│                  Results from one feed into the next.
│                  Example: "Explore → Plan → Implement"
│
└── NO → Use Single Subagent or Main REPL

Which Hook Type?

What kind of automation do you need?
│
├── Run a shell command at a specific event?
│   │
│   └── Use Command Hook
│       Trigger: PreToolUse, PostToolUse, Notification, Stop, SubagentStop
│       Example: "Run prettier after every file edit"
│       Config: hooks.PostToolUse[].command = "prettier --write $FILE"
│
├── Modify Claude's system prompt based on context?
│   │
│   └── Use Prompt Hook (v2.1.35+)
│       Trigger: Same events
│       Example: "Inject project rules when working in /src/auth/"
│       Config: hooks.PreToolUse[].prompt = "When editing auth files..."
│
└── Have Claude make a judgment call before proceeding?
    │
    └── Use Agent Hook (v2.1.35+)
        Trigger: Same events
        Example: "Evaluate if this bash command is safe before running"
        Config: hooks.PreToolUse[].agent = { prompt: "Is this safe?" }

When to Use /fast?

Is response speed more important than depth right now?
│
├── YES → Use /fast
│         Same Opus 4.6 model, faster output
│         Good for: quick questions, simple edits, code explanations,
│                   file searches, formatting tasks
│
└── NO → Stay in normal mode
         Good for: architecture decisions, complex debugging,
                   security reviews, multi-file refactors,
                   anything requiring deep reasoning

/fast toggles fast mode for the current session. It uses the same model (Opus 4.6) with optimized output speed — it does NOT switch to a cheaper model.

How Does the Permission System Work?

Claude Code’s permission system provides fine-grained control over what operations can execute. Understanding it is essential for both security and workflow efficiency. See also Enterprise Deployment for managed settings that enforce permissions organization-wide.

Permission Tiers

Read-only tools (auto-approved): - Read - Read file contents - Glob - Find files by pattern - Grep - Search file contents - WebSearch - Search the web - LSP - Code intelligence (go-to-definition, find references, hover docs)²⁵

LSP Tool capabilities (v2.0.74+): The LSP tool provides IDE-like code intelligence: - Go-to-definition: Jump to where a symbol is defined - Find references: List all usages of a symbol across the codebase - Hover docs: Get type information and documentation for any symbol - Works with TypeScript, Python, Go, Rust, and other languages with LSP support - Requires language server to be available (typically installed with your toolchain)

Modification tools (require approval): - Edit - Modify existing files - Write - Create new files - Bash - Execute shell commands - WebFetch - Fetch URL contents - NotebookEdit - Modify Jupyter notebooks

The first time a modification tool runs, Claude Code prompts for approval. Approvals persist for the session unless explicitly configured otherwise.

Permission Modes

YOLO Mode (v2.0.68+): For fully autonomous operation, use the --dangerously-skip-permissions flag. The flag says yes to everything: file edits, bash commands, all tool calls. The word “dangerous” is intentional. Use in sandboxed environments or when you fully trust the codebase.⁶¹

claude --dangerously-skip-permissions

Set mode via CLI:

claude --permission-mode acceptEdits

Toggle during session:

Shift+Tab  # Cycles through modes

In settings.json:

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Permission Rules Syntax

Fine-grained rules control specific operations. Rules are evaluated in order: first match wins.

Bash command patterns:

{
  "allow": [
    "Bash(npm run build)",
    "Bash(npm run test:*)",
    "Bash(git commit:*)",
    "Bash(make:*)"
  ],
  "deny": [
    "Bash(rm -rf:*)",
    "Bash(sudo:*)",
    "Bash(curl|wget:*)"
  ]
}

The asterisk provides prefix matching: Bash(npm run test:*) allows npm run test, npm run test:unit, and npm run test:integration.

Important limitation: Bash patterns match prefixes only, not regex. A pattern like Bash(curl http:*) won’t match curl -X GET http://... because the options come before the URL. For reliable blocking, deny the command entirely: Bash(curl:*).

File operation patterns:

{
  "allow": [
    "Edit(src/**)",
    "Write(src/**)",
    "Read(docs/**)"
  ],
  "deny": [
    "Read(.env*)",
    "Read(secrets/**)",
    "Edit(.git/**)",
    "Edit(node_modules/**)"
  ]
}

Path syntax: - Relative paths: Edit(src/**) - relative to working directory - Absolute from settings file: Edit(/build/**) - relative to settings file location - True absolute: Edit(//tmp/**) - starts with // - Home directory: Read(~/.zshrc)

MCP tool patterns:

{
  "allow": [
    "mcp__github",
    "mcp__database__query",
    "mcp__myserver__*"
  ],
  "deny": [
    "mcp__dangerous_server",
    "mcp__untrusted__*"
  ]
}

Use wildcard syntax mcp__server__* to allow or deny all tools from a specific MCP server.³⁹ Wildcard syntax is useful for quickly enabling all tools from trusted servers or blocking entire servers from untrusted sources.

WebFetch patterns:

{
  "allow": [
    "WebFetch(domain:github.com)",
    "WebFetch(domain:api.example.com)"
  ]
}

Additional Directories

Extend Claude’s access beyond the current project:

{
  "permissions": {
    "additionalDirectories": [
      "../shared-lib",
      "../docs",
      "~/reference-projects/design-system"
    ]
  }
}

Additional directories are essential for monorepos or when Claude needs to reference code in sibling directories.

Sandbox Mode

Enable filesystem and network isolation:

> /sandbox

Or configure in settings:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true
    }
  }
}

When sandboxed: - Filesystem access restricted to project directory - Network access controlled - Certain commands excluded from sandbox restrictions - Bash commands auto-allowed if autoAllowBashIfSandboxed is true

Expert tip: Sandbox mode is excellent for running Claude on untrusted codebases. Enable it when exploring unfamiliar projects or when you want an extra layer of protection. Internal Anthropic testing found sandboxing reduces permission prompts by 84%.⁴⁵ The sandbox uses OS-level primitives (macOS seatbelt, Linux bubblewrap) for filesystem and network isolation, so even a successful prompt injection is fully contained. Anthropic has open-sourced the sandbox runtime for teams building their own agents.⁸⁹

Security notes (v2.1.34+): Commands excluded from sandboxing via sandbox.excludedCommands or dangerouslyDisableSandbox could previously bypass the Bash ask permission rule when autoAllowBashIfSandboxed was enabled; this was fixed in v2.1.34.⁹⁴ As of v2.1.38, writes to .claude/skills are blocked in sandbox mode, preventing prompt injection from modifying skill definitions.⁹⁵

How Do Hooks Work?

Hooks execute deterministic shell commands at specific points in Claude Code’s workflow. Unlike prompting Claude to perform actions, hooks guarantee execution regardless of model behavior. They’re essential for enforcing team standards and automating repetitive tasks. See Decision Frameworks for the “Which Hook Type?” decision tree covering command, prompt, and agent hooks.

Why hooks instead of prompts: Telling Claude “always run Prettier after editing files” works sometimes. But Claude might forget, prioritize speed, or decide the change is “too small.” Hooks guarantee execution: every Edit or Write triggers your formatter, every time, no exceptions. For compliance, security, and team standards, deterministic beats probabilistic.⁷

Available Events

Hook Configuration

Define hooks in settings.json or a dedicated hooks.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/inject-context.sh"
          }
        ]
      }
    ]
  }
}

Matchers

The matcher field determines which tools trigger a hook:

{"matcher": "*"}              // Match all tools
{"matcher": "Bash"}           // Match Bash only
{"matcher": "Edit|Write"}     // Match Edit or Write
{"matcher": "mcp__github"}    // Match MCP server tools
{"matcher": ""}               // Match for events without tools (like UserPromptSubmit)

Hook Input/Output Protocol

Hooks receive JSON on stdin:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123"
}

Stop/SubagentStop hooks (v2.1.47+) receive an additional last_assistant_message field containing Claude’s final response text, so hooks can inspect the output without parsing transcript files:

{
  "session_id": "abc-123",
  "last_assistant_message": "I've completed the refactoring. Here's what changed..."
}

Exit codes control behavior: - 0: Success: operation proceeds. Stdout shown in verbose mode (Ctrl+O). For UserPromptSubmit and SessionStart, stdout is added to context. - 2: Blocking error: operation stops. Stderr becomes the error message fed back to Claude. - 1, 3, etc.: Non-blocking error: operation continues. Stderr shown as warning in verbose mode.

For advanced control, hooks can output JSON:

{
  "decision": "allow",
  "message": "Command validated and modified",
  "modifications": {
    "tool_input": {
      "command": "npm test -- --coverage"
    }
  }
}

PreToolUse decision control (preferred format): PreToolUse hooks use hookSpecificOutput for richer control: three outcomes (allow/deny/ask) plus the ability to modify tool input and inject context:⁹⁶

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

Note: Top-level decision and reason fields are deprecated for PreToolUse. Use hookSpecificOutput.permissionDecision and hookSpecificOutput.permissionDecisionReason instead. Other events (PostToolUse, Stop, etc.) still use top-level decision.⁹⁶

Async Hooks (January 2026)

Hooks can now run in the background without blocking Claude Code’s execution. Add async: true to your hook configuration:⁸⁸

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/notify-slack.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

When to use async hooks: - Notifications (Slack, email, Pushover) that shouldn’t slow down the session - Logging and telemetry that can run in the background - Non-critical post-processing (analytics, backups)

When NOT to use async hooks: - Formatting (must complete before next edit) - Validation (must block on failure) - Any hook that needs to modify tool input/output

Prompt-Based and Agent-Based Hooks (v2.1.32+)

Beyond shell command hooks (type: "command"), Claude Code supports two LLM-powered hook types that evaluate conditions using AI reasoning rather than scripts.⁹⁶

Prompt hooks (type: "prompt") send a single-turn prompt to a fast Claude model. The model returns { "ok": true } to allow or { "ok": false, "reason": "..." } to block:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all requested tasks are complete and tests pass.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Agent hooks (type: "agent") spawn a subagent with tool access (Read, Grep, Glob) for multi-turn verification. Use these when checking requires inspecting actual files or test output:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Use $ARGUMENTS as a placeholder for the hook’s JSON input. Both types support model (defaults to fast model) and timeout fields. Supported events: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Stop, SubagentStop, TaskCompleted. TeammateIdle does not support prompt/agent hooks.

Hook Environment Variables

Hooks have access to environment variables for resolving paths:⁹⁶

Persist environment variables from SessionStart:

#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
fi
exit 0

HTTP hook security (v2.1.51+): HTTP hooks that interpolate environment variables into headers now require an explicit allowedEnvVars list. This prevents arbitrary environment variable exfiltration through header values. HTTP hooks are also routed through the sandbox network proxy when sandboxing is enabled, enforcing the domain allowlist. HTTP hooks are not supported for SessionStart/Setup events.¹⁰⁵

{
  "hooks": {
    "PostToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "curl -H 'Authorization: Bearer $MY_TOKEN' https://api.example.com/notify",
        "allowedEnvVars": ["MY_TOKEN"]
      }]
    }]
  }
}

Hook workspace trust (v2.1.51+): statusLine and fileSuggestion hook commands now require workspace trust acceptance before executing in interactive mode, closing a potential security vector.¹⁰⁵

Practical Hook Examples

Auto-format TypeScript files after editing:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.ts ]] && npx prettier --write \"$FILE_PATH\" || true'"
          }
        ]
      }
    ]
  }
}

Log all bash commands:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-history.log"
          }
        ]
      }
    ]
  }
}

Block access to sensitive files:

#!/bin/bash
# .claude/hooks/protect-files.sh
data=$(cat)
path=$(echo "$data" | jq -r '.tool_input.file_path // empty')

if [[ "$path" == *".env"* ]] || [[ "$path" == *"secrets/"* ]] || [[ "$path" == *".pem"* ]]; then
  echo "Blocked: Cannot access sensitive file $path" >&2
  exit 2  # Exit 2 = block the tool call. Exit 1 = non-blocking error (hook failure only).
fi
exit 0

Run tests after code changes:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.test.ts ]] || npm run test:affected'"
          }
        ]
      }
    ]
  }
}

Custom notification system:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Waiting for your input'"
          }
        ]
      }
    ]
  }
}

Inject dynamic context into prompts:

#!/bin/bash
# .claude/hooks/inject-context.sh
# Add current git branch and recent commits to every prompt

branch=$(git branch --show-current 2>/dev/null)
commits=$(git log --oneline -3 2>/dev/null | tr '\n' ' ')

if [ -n "$branch" ]; then
  echo "[Context: Branch '$branch', Recent: $commits]"
fi
exit 0

Hook Debugging

Enable debug mode to troubleshoot hooks:

claude --debug

Debug mode logs: - Hook execution times - Input/output data - Error messages and stack traces - Decision results (allow/reject/ask)

Component-Scoped Hooks (v2.1.0+)

Hooks can be defined directly in Skills, subagents, and slash commands using frontmatter. These hooks are scoped to the component’s lifecycle and only run when that component is active.⁴¹

Skill with embedded hooks:

---
name: secure-deployment
description: Deployment skill with security validation
hooks:
  PreToolUse:
    - matcher: Bash
      command: ".claude/hooks/validate-deploy.sh"
  PostToolUse:
    - matcher: Bash
      command: ".claude/hooks/log-deploy.sh"
  Stop:
    - command: ".claude/hooks/cleanup.sh"
      once: true  # Run only once per session
---

Supported events: PreToolUse, PostToolUse, Stop

The once option (skills and slash commands only) ensures the hook runs only once per session, which is useful for cleanup or finalization tasks.

Long-Running Sessions Strategy

For overnight or unattended Claude Code sessions, configure hooks to keep Claude on track without manual intervention. The key insight: use linting and testing hooks as guardrails that force Claude to fix issues before continuing.⁶⁴

The “Don’t Stop Until Tests Pass” Pattern:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint && npm run typecheck",
            "timeout": 60000
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm test || echo 'Tests failing - Claude should fix before stopping'"
          }
        ]
      }
    ]
  }
}

Strategy for overnight sessions:

1. Pre-flight check: Use a Setup hook to verify environment is ready
2. Continuous validation: PostToolUse hooks run tests after each change
3. Gate completion: Stop hooks verify all acceptance criteria before Claude declares “done”
4. Notification: Stop hooks can notify you via Slack/Pushover when Claude finishes or gets stuck

Combine with --dangerously-skip-permissions in a sandboxed container for fully autonomous overnight runs. Claude will keep iterating until tests pass or it exhausts its options.

Deep Dive: Why each of 95 production hooks exists, the failures that created them, and the four-layer lifecycle architecture

What Is MCP (Model Context Protocol)?

MCP extends Claude Code with access to external tools, databases, APIs, and services through a standardized protocol. The ecosystem has exploded: MCP now has 100 million monthly downloads and 3,000+ servers indexed on MCP.so (January 2026), cementing its position as the industry standard for connecting AI to tools and data.³⁵⁴ Understanding MCP is essential for integrating Claude into your existing toolchain.

Why MCP matters for developers: Without MCP, Claude Code can only read files and run bash commands. With MCP, Claude can query your production database, create Jira tickets, review GitHub PRs, check Sentry errors, and interact with any API your team uses, all from natural language requests. The protocol standardizes how AI tools connect to external services, preventing vendor lock-in. See Decision Frameworks for guidance on when to use MCP vs other extension mechanisms.

Remote MCP Support (June 2025)

Claude Code now supports remote MCP servers with native OAuth authentication.²⁸ Connect to tools and data sources without managing local servers. Just authenticate once and Claude Code handles token refresh automatically.

# Connect to remote MCP server with OAuth
claude mcp add --transport http linear https://mcp.linear.app/sse
# Browser opens for OAuth flow, tokens stored securely

claude.ai MCP Connectors (v2.1.46+)

Claude Code can now use MCP connectors configured in your claude.ai account. This bridges the gap between web and CLI: MCP servers you’ve set up through the claude.ai interface are automatically available in Claude Code without re-configuring them locally.¹⁰²

MCP Tool Search (v2.1.7+)

As MCP servers grew in capability (some exposing 50+ tools), tool descriptions began consuming excessive context. MCP Tool Search solves this by dynamically loading tool descriptions only when needed, a form of lazy loading for AI tools.⁵⁴

Performance impact: Internal benchmarks show dramatic accuracy improvements: - Opus 4: 49% → 74% on MCP evaluations - Opus 4.5: 79.5% → 88.1% on MCP evaluations - Token overhead reduction: 85%

How it works: When MCP tool descriptions exceed 10% of context window (default threshold), Claude Code defers loading full descriptions until they’re actually needed. Claude sees tool names but fetches descriptions on-demand.

Configuration:

{
  "mcpToolSearchAutoEnable": "auto:15"  // Enable when tools exceed 15% of context
}

Values: - true - Always enable tool search - false - Always disable (load all tool descriptions upfront) - auto:N - Enable when tools exceed N% of context (0-100)

Expert tip: With Tool Search enabled, you can connect to many more MCP servers without worrying about context limits. The 95% context reduction means servers that previously competed for context now coexist peacefully.

Interactive MCP Setup Wizard

Run claude mcp add without arguments to launch a step-by-step interface for adding MCP servers. The wizard walks through transport type selection, authentication, and configuration.¹⁵

Transport Types

HTTP (recommended for remote servers):

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# With authentication
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer $API_TOKEN"

SSE (deprecated but functional):

claude mcp add --transport sse asana https://mcp.asana.com/sse \
  --header "X-API-Key: your-key"

Stdio (local servers):

# PostgreSQL
claude mcp add --transport stdio postgres \
  --env "DATABASE_URL=postgresql://user:pass@localhost/db" \
  -- npx -y @anthropic-ai/mcp-server-postgres

# Custom server
claude mcp add --transport stdio custom -- python /path/to/server.py --port 8000

Windows requires a cmd wrapper for stdio:

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Scope Management

MCP servers exist at three scopes with clear precedence (local overrides project overrides user):

Specify scope during installation:

claude mcp add --scope project --transport http github https://...
claude mcp add --scope user --transport stdio personal-tool -- ./my-tool

Configuration File Format

The .mcp.json file defines project-level servers:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SENTRY_API_KEY}"
      }
    },
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "X-API-Key": "${INTERNAL_API_KEY}"
      }
    }
  }
}

Environment variables expand using ${VAR} syntax with optional defaults: ${VAR:-default}.

MCP Management Commands

claude mcp list                      # View all configured servers
claude mcp get github                # Get specific server details
claude mcp remove github             # Remove a server
claude mcp reset-project-choices     # Reset project-scoped approvals
claude mcp add-from-claude-desktop   # Import from Claude Desktop
claude mcp add-json weather '{"type":"http","url":"..."}'  # Add from JSON

# Within Claude Code REPL
> /mcp                               # Interactive MCP management

OAuth Authentication

For servers requiring OAuth:

> /mcp
# Follow browser-based OAuth flow
# Tokens stored securely and auto-refreshed
# Use "Clear authentication" to revoke access

Using MCP Resources and Prompts

Reference resources:

@github:issue://123
@postgres:schema://users
@docs:file://api/authentication

MCP prompts as slash commands:

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug title" high

Output Limits

Claude Code limits MCP output to prevent context overflow: - Warning threshold: 10,000 tokens - Default maximum: 25,000 tokens

Increase if needed:

export MAX_MCP_OUTPUT_TOKENS=50000

Popular MCP Servers

Practical MCP Patterns

GitHub workflow:

> Review PR #456
> List all open issues assigned to me
> Create a bug issue for the authentication failure we found

Database queries:

> What's our total revenue this quarter?
> Show the schema for the users table
> Find customers with no purchases in 90 days

Error monitoring:

> What errors occurred in production today?
> Show the stack trace for error ABC123
> Which deployment introduced these errors?

Enterprise MCP Configuration

System administrators can enforce MCP policies via managed-mcp.json:

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "sentry" },
    { "serverCommand": ["npx", "-y", "@approved/server"] }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" }
  ]
}

Location: - macOS: /Library/Application Support/ClaudeCode/managed-mcp.json - Linux: /etc/claude-code/managed-mcp.json - Windows: C:\ProgramData\ClaudeCode\managed-mcp.json

Denylist takes absolute precedence. Commands must match exactly including argument order.

MCP Apps (January 2026)

Anthropic launched MCP Apps, an extension to the Model Context Protocol that enables interactive tool UIs directly inside the Claude interface.⁷⁸ MCP Apps let users view, edit, and interact with content from external services without leaving Claude, including Asana, Box, Canva, Figma, Hex, monday.com, and Slack. Any MCP server can supply an interactive UI that renders inside Claude. While MCP Apps currently appear in the claude.ai web interface, the underlying MCP protocol extensions are relevant to Claude Code’s MCP ecosystem as servers adopt the new interactive capabilities.

API Platform: Code Execution Tool v2 (January 2026)

Anthropic launched v2 of the Code Execution Tool in public beta, replacing the original Python-only sandbox with Bash command execution and direct file manipulation.⁷⁹ Key changes: - Execute Bash commands (not just Python) in sandboxed containers - Write and run code in any language - Programmatic tool calling (also public beta): Claude can call tools from within code execution, reducing latency and token usage in multi-tool workflows

The v2 tool primarily affects API users but signals the direction for Claude Code’s cloud execution capabilities.

What Are Subagents?

Subagents are specialized Claude instances that handle complex tasks independently. They’re one of the most powerful features in Claude Code and one of the least understood. Mastering subagents dramatically expands what you can accomplish. See Decision Frameworks for guidance on Agent Teams vs Subagents vs Parallel Sessions.

Why subagents exist: Claude Code’s main conversation has a single context window. Everything you discuss, every file Claude reads, every tool output: all of it consumes that context. In long sessions, context fills up, Claude loses track of earlier decisions, and performance degrades. Subagents solve this by isolating work: exploration results don’t bloat your main conversation, only the summary returns. Claude can also run up to 10 subagents in parallel, enabling concurrent work that would be impossible sequentially.²

How Subagents Work

When Claude encounters a task that benefits from focused attention (deep exploration, multi-step analysis, specialized work), it can spawn a subagent. The subagent:

1. Starts with a clean context (no pollution from main conversation)
2. Has access to specified tools
3. Operates with a specific model (often cheaper/faster)
4. Returns results to the main conversation

The architecture prevents context overflow while enabling complex workflows.

Built-In Subagent Types

Explore (fast, read-only): - Model: Haiku (ultra-fast) - Mode: Strictly read-only - Tools: Glob, Grep, Read, and safe bash commands (ls, git status, git log, git diff, find, cat, head, tail) - Thoroughness levels: Quick, Medium, Very thorough - Use for: Codebase exploration, finding files, understanding structure

General-purpose: - Model: Sonnet - Mode: Full read/write - Tools: All available tools - Use for: Complex research + modification tasks

Plan: - Model: Sonnet (or Opus with opusplan) - Mode: Read-only - Tools: Read, Glob, Grep, Bash - Use for: Planning complex implementations before execution

Triggering Subagents

Claude automatically delegates to subagents based on task type. You can also explicitly request them:

> Use the explore agent to find all authentication-related files

> Have a subagent analyze the database schema thoroughly

> Spawn an agent to research how error handling works in this codebase

Expert tip: For complex tasks, explicitly request subagent delegation. “Use an explore agent to find…” prevents context bloat in your main conversation.

Creating Custom Subagents

Define subagents in .claude/agents/ (project) or ~/.claude/agents/ (personal):

---
name: security-reviewer
description: Expert security code reviewer. Use PROACTIVELY after any code changes to authentication, authorization, or data handling.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

You are a senior security engineer reviewing code for vulnerabilities.

When invoked:
1. Identify the files that were recently changed
2. Analyze for OWASP Top 10 vulnerabilities
3. Check for secrets, hardcoded credentials, SQL injection
4. Report findings with severity levels and remediation steps

Focus on actionable security findings, not style issues.

Configuration fields:

Restricting spawnable subagents (v2.1.33+): The tools field supports Task(agent_type) syntax to limit which subagent types an agent can spawn. For example, tools: Read, Grep, Task(Explore) allows the agent to use Read and Grep directly but only delegate to Explore-type subagents. The restriction prevents over-delegation in constrained agents.

CLI-Defined Subagents (v2.1.32+)

Define subagents as JSON at launch for quick testing or automation. These exist only for the session and aren’t saved to disk:⁹⁶

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality and security.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

The --agents flag accepts JSON with the same frontmatter fields as file-based subagents: description, prompt, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, and memory.

Managing Subagents

> /agents                    # Interactive management
> /agents create             # Create new subagent
> /agents edit               # Modify existing
> /agents delete             # Remove subagent
> /agents list               # View all

CLI listing (v2.1.50+): List all configured agents from the command line without starting an interactive session:

claude agents                # Shows agents grouped by source (built-in, user, project, plugin)

Remote control (v2.1.51+): The claude remote-control subcommand serves your local environment for external builds, enabling all users to access local-environment capabilities remotely:¹⁰⁵

claude remote-control        # Start serving local environment for external builds

Running Agents in Background

For long-running tasks:

> Run a thorough security review in the background

> /agents  # Check status of running agents

Retrieve results later with the agent ID.

Advanced Patterns

Chained subagents:

> First use the code-analyzer subagent to find performance issues, then use the optimizer subagent to fix them

Parallel exploration:

> Have three explore agents search in parallel:
> 1. Authentication code
> 2. Database models
> 3. API routes

Resumable agents: Agents can be resumed with their ID to continue previous work:

> Resume agent abc123 and continue the analysis

Async Subagents (December 2025)

Asynchronous subagents enable multitasking and parallel execution for large-scale projects:

> Run security review in the background while I continue frontend work
> /tasks                    # Check status of running agents

Async agents return results via the unified TaskOutputTool, enabling efficient pipeline-style workflows.

Permission Denial Resilience (v2.1.0+)

Starting in v2.1.0, subagents continue working after permission denials instead of stopping entirely. When a subagent hits a permissions wall, it tries alternative approaches automatically. The change makes autonomous workflows more resilient and reduces the need for human intervention.⁴⁷

Agent Teams (February 2026, Research Preview)

Agent Teams coordinate multiple Claude Code instances working together. One session acts as the team lead, spawning teammates that work independently in their own context windows, communicating directly with each other via a shared mailbox and task list.⁸⁶⁹¹

Unlike subagents (which run within a single session and only report back to the caller), teammates are full independent sessions that can message each other, challenge each other’s findings, and self-coordinate.

Enable:

// settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Or via environment: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Architecture:

Display modes:

Configure in settings: "teammateMode": "in-process" or "tmux". Or per-session: claude --teammate-mode in-process.

Key controls: - Shift+Down: Cycle through teammates (in-process mode; wraps back to lead after last teammate) - Shift+Tab: Enable delegate mode (restricts lead to coordination only, no code changes) - Ctrl+T: Toggle shared task list - Enter on teammate: View their session; Escape to interrupt their turn

When to use agent teams vs subagents:

Best use cases: - Research and review (multiple perspectives simultaneously) - New modules/features (teammates each own separate pieces) - Debugging with competing hypotheses (test different theories in parallel) - Cross-layer coordination (frontend, backend, tests each owned by different teammate)

Plan approval for teammates: For complex or risky tasks, require teammates to plan before implementing. The teammate works in read-only plan mode until the lead reviews and approves their approach:

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

The lead makes approval decisions autonomously. Influence its judgment with criteria: “only approve plans that include test coverage” or “reject plans that modify the database schema.”

Example prompts:

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage

Spawn a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

Storage: Team configs live at ~/.claude/teams/{team-name}/config.json (members array with name, agent ID, agent type). Task lists at ~/.claude/tasks/{team-name}/. Tasks support dependencies: blocked tasks unblock automatically when their dependencies complete.⁹¹

Hook integration: Use TeammateIdle (exit code 2 to send feedback and keep teammate working) and TaskCompleted (exit code 2 to prevent completion) hooks to enforce quality gates on teammates.

Limitations (experimental): - No session resumption for in-process teammates (/resume won’t restore them) - One team per session; no nested teams - Teammates can’t spawn their own teams - Split panes require tmux or iTerm2 (not supported in VS Code terminal, Windows Terminal, or Ghostty) - All teammates start with the lead’s permission mode - Token-intensive: each teammate is a separate Claude instance

Agent Skills (December 2025)

Agent Skills are organized folders of instructions, scripts, and resources that agents discover and load dynamically.³¹ They provide composable, portable domain expertise:

.claude/skills/
├── security-review/
│   ├── skill.md           # Instructions and prompts
│   ├── checklist.md       # Security checklist
│   └── common-vulns.sh    # Detection scripts
└── performance-audit/
    ├── skill.md
    └── profiling-guide.md

Skills differ from commands: commands are explicitly invoked, while skills auto-activate based on task context. The Claude Agent SDK (renamed from Claude Code SDK) provides the framework for building custom agents with skill support.³²

What Is Extended Thinking Mode?

Extended thinking gives Claude more time to reason through complex problems before responding. It’s particularly valuable for architectural decisions, debugging tricky issues, and tasks requiring careful analysis.

Current State (January 2026)

Extended thinking is now enabled by default with a budget of 31,999 tokens, the maximum budget that was previously triggered by “ultrathink.”⁷⁰ Anthropic made this change because extended thinking significantly improves performance on complex planning and reasoning tasks.

Important: Natural language triggers like “think”, “think hard”, “think harder”, and “ultrathink” no longer work. Claude now interprets these keywords as regular prompt instructions and does not allocate thinking tokens. The thinking budget is controlled exclusively by the MAX_THINKING_TOKENS environment variable or via /config.⁷⁰

Supported Models

• Claude Opus 4.6 (also supports adaptive thinking, which automatically determines reasoning depth)
• Claude Sonnet 4.6 (also supports adaptive thinking)
• Claude Opus 4.5
• Claude Sonnet 4.5
• Claude Haiku 4.5

Controlling Extended Thinking

Quick toggle during session:

Press Alt+T to toggle thinking on/off

Note: Anthropic changed the thinking toggle from Tab to Alt+T to avoid accidental triggers.³⁹

Via /config: Navigate to /config → Extended Thinking to enable/disable or adjust budget.

Environment variable (permanent):

# Set custom budget (default is 31,999)
export MAX_THINKING_TOKENS=8000
claude

# Double the default for complex tasks
export MAX_THINKING_TOKENS=63999
claude

Disable for cost savings: For simpler tasks where deep reasoning isn’t needed, you can reduce costs by disabling thinking in /config or lowering the budget:

export MAX_THINKING_TOKENS=8000  # Reduce from default 31,999

Thinking Token Budgets

Cost consideration: Anthropic bills thinking tokens as output tokens. The default 31,999 budget works well for most tasks, but for simple operations you can save costs by reducing the budget or disabling thinking entirely.

How It Works

When thinking is enabled, Claude performs internal reasoning that influences the answer but does not appear in the output. Claude Code encrypts the thinking and returns it in a signature field for verification.

In multi-turn conversations with tool use, thinking blocks must be passed back to the API to preserve reasoning continuity. Claude Code handles this automatically.

When to Consider Disabling/Reducing

Extended thinking is now the default, but consider reducing the budget or disabling for: - Simple file edits - Routine refactoring - Quick questions - Code formatting - High-volume operations where costs add up

Cache Behavior

Claude Code preserves system prompt caching when thinking parameters change. Changing the thinking budget or enabled status between turns invalidates message caching.

Output Styles

Output styles customize how Claude presents information, which is useful for learning, documentation, or specific team preferences.¹⁹

Built-In Styles

Setting Output Style

> /output-style Explanatory
> /output-style Learning

Or via settings:

{
  "outputStyle": "Explanatory"
}

Custom Output Styles

Create in .claude/styles/:

# my-style

## Instructions
- Always explain the WHY behind each decision
- Include relevant documentation links
- Format code examples with comments
- End with a "What to do next" section

## Format
Use markdown headers for organization.
Keep explanations under 200 words per section.

Invoke with /output-style my-style.

Slash Commands

Slash commands provide quick access to Claude Code features and enable custom workflows. They’re faster than typing out full prompts for common operations.

Built-In Command Reference

Custom Command Creation

Create reusable commands in .claude/commands/ (project) or ~/.claude/commands/ (personal):

---
description: Security-focused code review
allowed-tools: Read, Grep, Glob
model: claude-sonnet-4-5
---

Review this code for security vulnerabilities:

1. Injection attacks (SQL, command, XSS)
2. Authentication and authorization flaws
3. Sensitive data exposure
4. Insecure dependencies

Focus on actionable findings with specific line references.

Save as .claude/commands/security-review.md, invoke with /security-review.

Command Frontmatter Options

---
description: Brief description for /help
allowed-tools: Read, Edit, Bash(npm:*)
model: opus
argument-hint: [arg1] [arg2]
disable-model-invocation: false
---

Argument Interpolation

All arguments as single string:

---
description: Fix GitHub issue
argument-hint: [issue-number]
---

Fix GitHub issue #$ARGUMENTS following our coding standards.

Usage: /fix-issue 123

Numbered arguments:

---
description: Create component
argument-hint: [name] [type]
---

Create a new $2 component named $1 in src/components/.

Usage: /create-component Button functional

Inline Bash Execution

Execute bash commands within command prompts:

---
description: Git status summary
allowed-tools: Bash(git:*)
---

Current branch: !`git branch --show-current`
Recent commits: !`git log --oneline -5`
Changed files: !`git status --short`

Summarize the current state of this repository.

File References

Include file contents in commands:

---
description: Compare implementations
---

Compare these files:
@src/v1/handler.ts
@src/v2/handler.ts

Which implementation is more maintainable?

Command Namespacing

Organize commands in subdirectories:

.claude/commands/
├── backend/
│   ├── test.md
│   └── deploy.md
├── frontend/
│   ├── test.md
│   └── build.md
└── review.md

Commands with the same name show their namespace in help: /test (project:backend) vs /test (project:frontend).

How Do Skills Work?

Skills represent a fundamentally different approach to extending Claude Code. Unlike slash commands that you invoke explicitly, skills are model-invoked—Claude automatically discovers and uses them based on context. You embed domain expertise into a skill, and Claude draws on that expertise whenever the situation calls for it, without you needing to remember to ask.

Why skills change everything: Consider domain expertise: the payment processing rules, the compliance requirements, the architectural patterns your team has refined over years. Without skills, you either re-explain this context every session or hope Claude infers it from code comments. With skills, you encode it once. Claude reads the skill definition and applies that expertise automatically whenever relevant. Your junior developers get senior-level guidance without asking. Your security patterns get enforced without remembering to invoke them.

The distinction matters. A slash command is a shortcut you remember to use. A skill is knowledge Claude always has available. When you create a security review skill with your team’s specific vulnerability patterns and compliance requirements, Claude applies that expertise whenever it encounters relevant code, whether during PR reviews, refactoring, or any task where security matters. You don’t invoke /security-review; Claude recognizes the context and applies the skill automatically.

Skills vs Commands vs Subagents

Understanding when to use each extension mechanism prevents duplication and maximizes effectiveness:

Use slash commands when you want explicit control: /deploy, /test, /review PR 456. You decide when to run them.

Use skills when expertise activates automatically: security patterns, code style enforcement, domain-specific knowledge. Claude decides when to apply them.

Use subagents when tasks need isolation: background exploration, parallel analysis, specialized reasoning that shouldn’t pollute your main conversation.

Skill Structure and Location

Skills live in dedicated directories containing a required SKILL.md file plus optional supporting resources:

Personal skills (available across all your projects):

~/.claude/skills/
├── code-reviewer/
│   ├── SKILL.md
│   ├── SECURITY_PATTERNS.md
│   └── PERFORMANCE_CHECKLIST.md
├── sql-analyst/
│   ├── SKILL.md
│   └── QUERY_PATTERNS.md
└── api-designer/
    └── SKILL.md

Project skills (shared with team via git):

.claude/skills/
├── domain-expert/
│   ├── SKILL.md
│   ├── BUSINESS_RULES.md
│   └── DATA_MODELS.md
└── deployment/
    ├── SKILL.md
    └── RUNBOOKS.md

Project skills commit to version control. When teammates pull, they get your skills automatically, with no installation, no configuration. Automatic distribution standardizes expertise across a team.

SKILL.md Format

Every skill requires a SKILL.md file with YAML frontmatter:

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues, and best practice violations. Use when examining code changes, reviewing PRs, analyzing code quality, or when asked to review or audit code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Analysis

When reviewing code, check for:

### Input Validation
- All user input sanitized before use
- Parameterized queries for database operations
- Output encoding for rendered content

### Authentication & Authorization
- Session tokens properly validated
- Permission checks before sensitive operations
- No hardcoded credentials or API keys

### Data Exposure
- Sensitive data not logged
- PII properly masked in error messages
- API responses don't leak internal details

## Performance Patterns

### Database
- N+1 query detection
- Missing indexes on filtered columns
- Unbounded result sets

### Memory
- Large object lifecycle management
- Stream processing for big files
- Connection pool exhaustion risks

## Review Output Format

For each finding:
- **File**: path/to/file.ts:123
- **Severity**: Critical | High | Medium | Low
- **Category**: Security | Performance | Maintainability
- **Issue**: Clear description of the problem
- **Recommendation**: Specific fix with code example
- **Rationale**: Why this matters

See [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md) for detailed vulnerability patterns.
See [PERFORMANCE_CHECKLIST.md](PERFORMANCE_CHECKLIST.md) for optimization guidelines.

Frontmatter Reference

String Substitutions (v2.1.9+): Skills can access session context using ${CLAUDE_SESSION_ID} substitution. Useful for logging, tracking, or generating session-specific outputs.⁵¹

The description field is critical. Claude discovers skills by matching your requests against skill descriptions. A vague description means Claude won’t recognize when to use the skill. A specific description with clear trigger conditions means reliable activation.

Poor description:

description: Helps with code

Effective description:

description: Review code for security vulnerabilities, performance issues, and best practice violations. Use when examining code changes, reviewing PRs, analyzing code quality, or when asked to review, audit, or check code.

The effective description includes: - What the skill does (review code for specific issues) - When to use it (examining changes, PRs, quality analysis) - Trigger phrases (review, audit, check)

Tool Restrictions

The allowed-tools field limits what Claude can do when a skill is active. Tool restrictions are essential for read-only or scope-limited skills:

---
name: security-auditor
description: Audit code for security vulnerabilities without making changes
allowed-tools: Read, Grep, Glob
---