The Complete Claude Code CLI Guide

Quick Links: Get Started · Commands · MCP Setup · Settings · SDK · Changelog

🔄 Live Guide: Auto-updated every 2 days from official docs, GitHub releases, and Anthropic changelog. See update-log.md.

🤖 For AI Agents: Optimized for both humans and AI. [OFFICIAL] = from code.claude.com. [COMMUNITY] = observed patterns. [EXPERIMENTAL] = unverified.

What is Claude Code?

Claude Code is an agentic AI coding assistant that lives in your terminal. It understands your codebase, edits files directly, runs commands, and helps you code faster through natural language conversation.

Key Capabilities:

• 💬 Natural language interface in your terminal
• 📝 Direct file editing and command execution
• 🔍 Full project context awareness
• 🔗 External integrations via MCP (Model Context Protocol)
• 🤖 Extensible via Skills, Hooks, and Plugins
• 🛡️ Sandboxed execution for security

Installation:

# Quick Install (macOS, Linux, WSL)
curl -fsSL https://claude.ai/install.sh | bash

# 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

# Alternative: Homebrew (macOS/Linux)
brew install --cask claude-code

# Alternative: WinGet (Windows)
winget install Anthropic.ClaudeCode

# Alternative: NPM (⚠️ Deprecated - use native install instead)
npm install -g @anthropic-ai/claude-code

claude --version  # Verify installation

Official Documentation: https://code.claude.com/docs/en/overview

Contents

Quick Reference

Essential Commands [OFFICIAL]

# Starting Claude Code
claude                    # Start interactive session
claude -p "task"          # Print mode (non-interactive)
claude --continue         # Continue last session
claude --resume       # Resume specific session

# Session Management
/help                     # Show available commands
/exit                     # End session
/compact                  # Reduce context size
/compact [instructions]  # Compact conversation with optional focus instructions

# Background Tasks
/bashes                   # List background processes
/kill                # Stop background process

# Discovery
/commands                 # List skills and commands
/hooks                   # Show configured hooks
/skills                  # List available Skills (NEW)
/plugin                  # Manage plugins

Source: CLI Reference

CLI Flags Reference [OFFICIAL]

# Output Control
claude -p, --print "task"          # Print mode: non-interactive, prints result and exits
claude --output-format json         # Output format: text, json, or stream-json
claude --input-format text          # Input format: text or stream-json
claude --verbose                    # Enable verbose logging (full turn-by-turn output)

# Session Management
claude --continue                   # Continue from last session
claude --resume         # Resume specific session by ID or name
claude --from-pr                # Resume session linked to GitHub PR number or URL [NEW]
claude --fork-session               # Create new session ID instead of reusing original
claude --session-id           # Use specific session ID (must be valid UUID)

# Remote Sessions (claude.ai subscribers)
claude --remote "task"              # Create web session on claude.ai
claude --teleport                   # Resume web session in local terminal
claude --remote-control             # Bridge this session to claude.ai/code (mobile/web)
claude --channels                   # Allow MCP servers to push messages in (research preview) [NEW]

# Background Sessions & Agent View [NEW]
claude agents                       # Open the agent view: every session, running/blocked/done
claude agents --json                # List live sessions as JSON (add --all for completed)
claude agents --cwd           # Scope the session list to a directory
claude --bg "task"                  # Start the session in the background
claude --bg --exec ''      # Run a shell command as an attachable background session
claude --bg --name           # Name the background session
claude attach                   # Attach to a background session
claude logs                     # Show a background session's output
claude stop  / claude rm    # Stop or remove a background session
claude respawn                  # Restart a stopped background session
claude daemon status                # Inspect the background-session daemon

# Debugging & Logging
claude --debug                      # Enable debug mode (with optional category filtering)
claude --debug "api,mcp"            # Debug specific categories
claude --debug "!statsig,!file"     # Exclude categories with !

# Model & Agent Configuration
claude --model                # Specify model (sonnet, opus, haiku, or full name)
claude --fallback-model       # Fallback model when overloaded (interactive too, v2.1.166)
claude --effort high                # Set reasoning effort (low/medium/high/xhigh/max/ultracode) [NEW]
claude --agent                # Specify custom agent (overrides settings)
claude --agents ''            # Define custom subagents dynamically via JSON
claude --forward-subagent-text      # Include subagent text/thinking in stream-json output [NEW]

# System Prompt Customization
claude --system-prompt "prompt"     # Replace entire default system prompt
claude --system-prompt-file   # Replace with file contents (print mode only)
claude --append-system-prompt "..."  # Append to default system prompt
claude --append-system-prompt-file   # Append file contents (print mode only)

# Tool & Permission Management
claude --tools "Bash,Read,Edit"     # Restrict built-in tools (use "" to disable all)
claude --allowedTools "Bash(git:*)" # Tools that execute without prompting
claude --disallowedTools "Edit"     # Tools removed from context
claude --permission-mode plan       # Begin in specified permission mode
claude --permission-mode manual     # "default" mode renamed to "manual" in v2.1.200 [NEW]
claude --dangerously-skip-permissions  # Skip all permission prompts ⚠️
claude --allow-dangerously-skip-permissions  # Enable bypass option without activating [NEW]
claude --permission-prompt-tool   # MCP tool for permission prompts (non-interactive) [NEW]

# Budget & Execution Limits (print mode)
claude --max-budget-usd 5.00        # Maximum dollar amount for API calls
claude --max-turns 3                # Limit number of agentic turns
claude --json-schema ''     # Get validated JSON output matching schema (print mode) [NEW]

# Directory & Configuration
claude --add-dir ../apps ../lib     # Add additional working directories
claude --plugin-dir ./my-plugins    # Load plugins from a directory or .zip (repeat for more)
claude --plugin-url            # Fetch a plugin .zip archive from a URL for this session [NEW]
claude --worktree, -w         # Run the session in an isolated git worktree
claude --settings ./settings.json   # Path to settings JSON file
claude --setting-sources user,project  # Comma-separated list of setting sources [NEW]
claude --mcp-config ./mcp.json      # Load MCP servers from JSON file
claude --strict-mcp-config          # Only use MCP servers from --mcp-config

# IDE & Browser Integration
claude --ide                        # Auto-connect to IDE on startup
claude --chrome                     # Enable Chrome browser integration
claude --no-chrome                  # Disable Chrome browser integration

# Agent Teams [NEW]
claude --teammate-mode in-process   # Teammates display in main terminal
claude --teammate-mode tmux         # Each teammate in own pane (requires tmux/iTerm2)
claude --teammate-mode auto         # Auto-detect (default)

# Setup & Maintenance
claude --init                       # Run Setup hooks and start interactive mode
claude --init-only                  # Run Setup hooks and exit (no interactive session)
claude --maintenance                # Run Setup hooks with maintenance trigger and exit

# Troubleshooting & Accessibility [NEW]
claude --safe-mode                  # Start with CLAUDE.md, plugins, skills, hooks, MCP disabled
claude --bare                       # Minimal scripted -p runs (no hooks/LSP/plugin sync)
claude --ax-screen-reader           # Opt-in plain-text rendering for screen readers
claude doctor                       # Full setup checkup that can diagnose and fix issues

# Other Options
claude -n, --name             # Set a display name for the session at startup [NEW]
claude --disable-slash-commands     # Disable all skills and slash commands
claude --no-session-persistence     # Disable session persistence (print mode)
claude --betas interleaved-thinking # Beta headers for API requests
claude --include-partial-messages   # Include partial streaming events (with stream-json) [NEW]
claude --exclude-dynamic-system-prompt-sections  # Better cross-user prompt caching (print) [NEW]

# Subcommands
claude auth login|status|logout     # Manage authentication (--console for API billing)
claude mcp login|logout       # Authenticate an MCP server without opening /mcp
claude plugin init|list|details|prune|tag   # Plugin authoring and maintenance
claude project purge [path]         # Delete all Claude Code state for a project [NEW]
claude auto-mode reset              # Restore the default auto-mode configuration [NEW]

Common Flag Combinations:

# One-off task with JSON output
claude --print "analyze this code" --output-format json

# Debug MCP and API issues
claude --debug "api,mcp"

# Resume session with specific model
claude --resume auth-refactor --model opus

# Non-interactive with budget limit (CI/CD)
claude -p --max-budget-usd 5.00 --output-format json "run tests"

# Custom subagents for specialized work
claude --agents '{"reviewer":{"description":"Code reviewer","prompt":"Review for bugs"}}'

# Remote session for claude.ai subscribers
claude --remote "fix the login bug"

Source: CLI Reference

Core Tools [OFFICIAL]

Source: Settings Reference

Core Concepts

1. How Claude Code Works [OFFICIAL]

Claude Code operates through a conversational interface in your terminal:

# You describe what you want
$ claude
> "Add user authentication to the API"

# Claude Code:
1. Analyzes your codebase structure
2. Plans the implementation
3. Requests permission for file edits (first time)
4. Writes code directly to your files
5. Can run tests and verify changes
6. Creates git commits if requested

Key Principles:

• Natural Language: Just describe what you need - no special syntax
• Direct Action: Edits files and runs commands with your permission
• Context Aware: Understands your entire project structure
• Incremental Trust: Asks permission as needed for new operations
• Scriptable: Can be automated via SDK

Source: Overview

2. Permission Model [OFFICIAL]

Claude Code uses an incremental permission system for safety:

# Permission Rules — three buckets, each an ARRAY of "Tool(specifier)" strings
"allow"  # Permit without asking
"ask"    # Prompt before each use
"deny"   # Block completely

# Permission Modes — the starting behavior, set with permissions.defaultMode
"default"            # Prompt on first use of each tool (alias: "manual")
"acceptEdits"        # Auto-accept file edits and common filesystem commands
"plan"               # Explore read-only; no source edits
"auto"               # Auto-approve with background safety checks
"dontAsk"            # Auto-deny anything not pre-approved
"bypassPermissions"  # Skip prompts entirely (isolated environments only)

# NOTE: rule buckets and modes are different things. There is no "ask" MODE.
# To prompt before acting, stay in "default" mode and add ask RULES:
#   { "defaultMode": "default", "ask": ["Bash", "Edit"] }

# Permission Priority [NEW v2.1.27]
# Content-level rules override tool-level rules
# Example: allow: ["Bash"], ask: ["Bash(rm *)"]
#   -> Bash is generally allowed, but "rm *" commands require confirmation

# Tools Requiring Permission
- Bash (command execution)
- Write/Edit/NotebookEdit (file modifications)
- WebFetch/WebSearch (network access)
- Skill (skills and custom commands)

# Tools Not Requiring Permission (Safe Operations)
- Read/NotebookRead (reading files)
- Grep/Glob (searching)
- TodoWrite (task tracking)
- Task (sub-agents)

Configuring Permissions:

Create .claude/settings.json in your project or ~/.claude/settings.json globally:

{
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(git status)",
      "Bash(git diff)",
      "Bash(git log *)",
      "Bash(npm test)",
      "Bash(npm run *)",
      "Read",
      "Edit"
    ],
    "deny": [
      "Read(*.env)",
      "Read(.env.*)",
      "Edit(*.env)",
      "Edit(.env.*)",
      "Edit(.git/**)"
    ],
    "additionalDirectories": [
      "/path/to/other/project"
    ]
  }
}

Rule syntax gotchas:

• allow / ask / deny are arrays of "Tool(specifier)" strings, never objects keyed by tool name. An object such as "deny": { "Write": ["*.env"] } is silently ignored.
• A bare tool name matches every use of that tool: "Read" allows all reads.
• Use Edit(path), not Write(path). File permission checks match only Edit(path) and Read(path) rules; Write(path), NotebookEdit(path), and Glob(path) rules are accepted but never matched, and warn at startup (v2.1.210+). Edit rules cover all file-editing tools.
• The space before * matters: Bash(npm run *) matches npm run build but not npm runfoo, while Bash(npm run*) matches both.
• Read and Edit specifiers use gitignore syntax; a bare filename matches at any depth, so Read(.env) and Read(**/.env) are equivalent.
• To block a secret, deny both Read(...) and Edit(...) — denying edits alone still lets Claude read the file.

Source: Permissions, Settings

3. Project Context - CLAUDE.md [COMMUNITY]

A CLAUDE.md file in your project root provides persistent context across sessions:

Example CLAUDE.md file (click to expand)

# Project: My Application

## Critical Context (Read First)
- Language: TypeScript + Node.js
- Framework: Express + React
- Database: PostgreSQL with Prisma ORM
- Testing: Jest + React Testing Library

## Commands That Work
npm run dev          # Start dev server (port 3000)
npm test             # Run all tests
npm run lint         # ESLint check
npm run typecheck    # TypeScript validation
npm run db:migrate   # Run Prisma migrations

## Important Patterns
- All API routes in /src/routes - RESTful structure
- Database queries use Prisma Client
- Auth uses JWT tokens (implementation in /src/auth)
- Frontend components in /src/components
- API responses: {success: boolean, data: any, error?: string}

## Gotchas & What NOT to Do
- DON'T modify /generated folder (auto-generated by Prisma)
- DON'T commit .env files (use .env.example instead)
- ALWAYS run npm run db:migrate after pulling schema changes
- DON'T use `any` type in TypeScript - use proper typing

## File Structure
/src
  /routes       # Express API routes
  /services     # Business logic
  /models       # Type definitions
  /middleware   # Express middleware
  /utils        # Shared utilities
  /auth         # Authentication logic

## Recent Learnings
- [2026-01-15] Payment webhook needs raw body parser for Stripe
- [2026-01-10] Redis pool: {maxRetriesPerRequest: 3}

Why CLAUDE.md Helps:

• ✅ Provides context immediately at session start
• ✅ Reduces need to re-explain project structure
• ✅ Stores project-specific patterns and conventions
• ✅ Documents what works (and what doesn't)
• ✅ Shared with team via git
• ✅ AI-optimized format for Claude to understand quickly

Note: While CLAUDE.md is not an official feature, it's a widely-adopted community pattern. Claude Code will automatically read it if present at project root.

4. Tools Reference [OFFICIAL]

Read Tool

Purpose: Read and analyze files

# Examples
Read file_path="/src/app.ts"
Read file_path="/docs/screenshot.png"  # Can read images!
Read file_path="/docs/guide.pdf"       # Can read PDFs!
Read file_path="/docs/guide.pdf" pages="1-5"  # Read specific PDF pages [NEW v2.1.30]

Capabilities:

• Reads any text file (code, configs, logs, etc.)
• Handles images (screenshots, diagrams, charts)
• Processes PDFs - extracts text and visual content
• Parses Jupyter notebooks (.ipynb files)
• Returns content with line numbers (cat -n format)
• Can read large files with offset/limit parameters

PDF Parameters [NEW v2.1.30]:

• pages: Optional page range (e.g., "1-5", "1,3,5") to read specific pages
• Large PDFs (>10 pages) return a lightweight reference when @mentioned
• PDF limits: Maximum 100 pages, 20MB file size

Special Features:

• Images: Claude can read screenshots of errors, UI designs, architecture diagrams
• PDFs: Extract and analyze PDF content, useful for documentation and requirements
• Notebooks: Full access to code cells, markdown, and outputs

Write Tool

Purpose: Create new files

Write file_path="/src/newFile.ts"
      content="export const config = {...}"

Behavior:

• Creates new file with specified content
• Will OVERWRITE if file already exists (use Edit for existing files)
• Requires permission on first use per session
• Creates parent directories if needed

Best Practice: Use Edit tool for modifying existing files, Write tool only for new files.

Edit Tool

Purpose: Modify existing files with precise string replacement

Edit file_path="/src/app.ts"
     old_string="const port = 3000"
     new_string="const port = process.env.PORT || 3000"

Important:

• Requires exact string match including whitespace and indentation
• Fails if old_string is not unique in file (use larger context or replace_all)
• Use replace_all=true to replace all occurrences (useful for renaming)
• Must read file first before editing

Common Pattern:

# 1. Read file to see exact content
Read file_path="/src/app.ts"

# 2. Edit with exact string match
Edit file_path="/src/app.ts"
     old_string="function login() {
  return 'TODO';
}"
     new_string="function login() {
  return authenticateUser();
}"

Bash Tool

Purpose: Execute shell commands

Bash command="npm test"
Bash command="git status"
Bash command="find . -name '*.test.ts'"

Features:

• Can run any shell command
• Supports background execution (run_in_background=true)
• Configurable timeout (default 2 minutes, max 10 minutes)
• Git operations are common (status, diff, log, commit, push)

Security:

• Requires permission
• Can be restricted by pattern in settings
• Sandboxing available on macOS/Linux

Common Git Patterns:

# Check status
Bash command="git status"

# View changes
Bash command="git diff"

# Create commit
Bash command='git add . && git commit -m "feat: add authentication"'

# View history
Bash command="git log --oneline -10"

Grep Tool

Purpose: Search file contents with regex patterns

# Find functions
Grep pattern="function.*auth" path="src/" output_mode="content"

# Find TODOs with context
Grep pattern="TODO" output_mode="content" -C=3

# Count occurrences
Grep pattern="import.*from" output_mode="count"

# Case insensitive
Grep pattern="error" -i=true output_mode="files_with_matches"

Parameters:

• pattern: Regex pattern (ripgrep syntax)
• path: Directory or file to search (default: current directory)
• output_mode:
  • "files_with_matches" (default) - Just file paths
  • "content" - Show matching lines
  • "count" - Show match counts per file
• -A, -B, -C: Context lines (after, before, both)
• -i: Case insensitive
• -n: Show line numbers
• type: Filter by file type (e.g., "js", "py", "rust")
• glob: Filter by glob pattern (e.g., "*.test.ts")

Fast and Powerful: Uses ripgrep under the hood, much faster than bash grep on large codebases.

Glob Tool

Purpose: Find files by pattern

# Find test files
Glob pattern="**/*.test.ts"

# Find specific extensions
Glob pattern="src/**/*.{ts,tsx}"

# Find config files
Glob pattern="**/config.{json,yaml,yml}"

Features:

• Fast pattern matching (works with any codebase size)
• Returns files sorted by modification time (recent first)
• Supports complex glob patterns (** for recursive, {} for alternatives)

TodoWrite Tool

Purpose: Manage task lists during work

TodoWrite todos=[
  {
    "content": "Add authentication endpoint",
    "status": "in_progress",
    "activeForm": "Adding authentication endpoint"
  },
  {
    "content": "Write integration tests",
    "status": "pending",
    "activeForm": "Writing integration tests"
  },
  {
    "content": "Update API documentation",
    "status": "pending",
    "activeForm": "Updating API documentation"
  }
]

Task States:

• "pending" - Not started yet
• "in_progress" - Currently working on (should be only ONE at a time)
• "completed" - Finished successfully

Dependency Tracking [NEW]: v2.1.16 introduced task dependency tracking, allowing tasks to define prerequisites that must complete before they start. This enables complex multi-step workflows with proper sequencing.

Best Practices:

• Use for multi-step tasks (3+ steps)
• Keep ONE task in_progress at a time
• Mark completed IMMEDIATELY after finishing
• Use descriptive content (what to do) and activeForm (what you're doing)

When to Use:

• ✅ Complex multi-step features
• ✅ User provides multiple tasks
• ✅ Non-trivial work requiring planning
• ❌ Single straightforward tasks
• ❌ Trivial operations

Task Tool (Sub-Agents)

Purpose: Launch specialized AI agents for specific tasks

# Explore codebase
Task subagent_type="Explore"
     prompt="Find all API endpoints and their authentication requirements"

# General purpose agent for complex tasks
Task subagent_type="general-purpose"
     prompt="Research best practices for rate limiting APIs and implement a solution"

Available Sub-Agent Types:

• "general-purpose" - Complex multi-step tasks, research, implementation
• "Explore" - Fast codebase exploration (Glob, Grep, Read, Bash)

When to Use:

• Research tasks requiring web search + analysis
• Codebase exploration (finding patterns, understanding architecture)
• Complex multi-step operations that can run independently
• Background work while you continue other tasks

WebFetch Tool

Purpose: Fetch and analyze web page content

WebFetch url="https://docs.example.com/api"
         prompt="Extract all endpoint documentation"

Features:

• Converts HTML to markdown for analysis
• Can extract specific information with prompt
• Useful for researching docs, articles, references

WebSearch Tool

Purpose: Search the web for current information

WebSearch query="React 19 new features 2024"

Use Cases:

• Research current best practices
• Find up-to-date library documentation
• Check for known issues or solutions
• Verify latest framework features

Source: CLI Reference, Settings

LSP Tool (Language Server Protocol) [OFFICIAL]

Purpose: Get code intelligence features like go-to-definition, find references, and hover documentation.

LSP operation="goToDefinition"
    filePath="src/utils/auth.ts"
    line=42
    character=15

Available Operations:

Parameters:

• operation (required): The LSP operation to perform
• filePath (required): Absolute or relative path to the file
• line (required): Line number (1-based, as shown in editors)
• character (required): Character offset (1-based, as shown in editors)

Use Cases:

# Find where a function is defined
> "Go to the definition of getUserById"

# Find all usages of a function
> "Find all references to the authenticate function"

# Get documentation for a symbol
> "What does the validateToken function do?"

# Explore code structure
> "List all symbols in the auth.ts file"

Note: LSP servers must be configured for the file type. If no server is available for a language, an error will be returned.

Source: CLI Reference

5. Context Management [OFFICIAL]

Claude Code maintains conversation context with smart management:

Context Commands

/compact                   # Reduce context by removing old information
/compact "keep auth work"  # Compact with focus instructions (keeps specified context)

When to Use

Use /compact when:

• Long sessions with many file reads
• "Context too large" errors
• You've completed a major task and want to start fresh

Use /compact with instructions when:

• Context is getting large but you want to preserve recent work
• Switching between related tasks
• You want intelligent cleanup without losing important context
• Example: /compact "keep the authentication implementation context"

What Gets Preserved vs Cleared

Preserved:

• CLAUDE.md content (your project context)
• Recent interactions and decisions
• Current task information and todos
• Recent file reads still relevant

Cleared:

• Old file reads no longer needed
• Completed operations
• Stale search results
• Old context no longer relevant

Automatic Context Management

Claude Code may automatically compact when:

• Token limit is approaching
• Many old file reads are present
• Session has been very long

Source: Settings

6. Workspace Management [OFFICIAL]

Adding Directories with /add-dir

Claude Code can work with multiple directories simultaneously:

# Add another directory to current session
/add-dir /path/to/other/project

# Work across multiple projects
> "Update the User type in backend and propagate to frontend"
# Claude can now access both directories

Use Cases:

• Monorepo development (frontend + backend + shared libs)
• Cross-project refactoring
• Dependency updates across multiple projects
• Coordinating changes between related repositories

Configuration:

You can also pre-configure additional directories in .claude/settings.json:

{
  "permissions": {
    "additionalDirectories": [
      "/path/to/frontend",
      "/path/to/backend",
      "/path/to/shared-libs"
    ]
  }
}

Status Line Configuration with /statusline

Customize what information appears in your status line:

# Configure status line
/statusline

# Options typically include:
# - Current model
# - Token usage
# - Session duration
# - Active tools
# - Background processes

Benefits:

• Monitor token usage in real-time
• Track session duration
• See active background processes
• Understand which tools are being used

Source: CLI Reference

Quick Start Guide

Your First Session

# 1. Navigate to your project
cd /path/to/your/project

# 2. Start Claude Code
claude

# 3. Ask Claude to understand your project
> "Read the codebase and explain the project structure"

# Claude will:
- Look for README, package.json, or similar entry points
- Read relevant files (asks permission first time)
- Analyze the code structure
- Provide a summary

# 4. Request an analysis
> "Review the authentication system for security issues"

# Claude will:
- Find authentication-related files
- Analyze the implementation
- Identify potential vulnerabilities
- Suggest improvements

# 5. Make changes
> "Add rate limiting to the login endpoint"

# Claude will:
- Plan the implementation
- Show you what changes will be made
- Request permission to edit files
- Implement the changes
- Can run tests to verify

# 6. Create a commit
> "Create a git commit for these changes"

# Claude will:
- Run git status to see changes
- Review git diff
- Create a descriptive commit message
- Commit the changes

Setting Up Your Project for Claude Code

1. Create CLAUDE.md [COMMUNITY]

This provides context that persists across all sessions:

# Ask Claude to help create it
> "Create a CLAUDE.md file documenting this project's structure, commands, and conventions"

# Or create manually with:
- Languages and frameworks used
- Important commands (dev, test, build, lint)
- Project structure overview
- Coding conventions
- Known gotchas or issues

2. Configure Permissions (Optional) [OFFICIAL]

Create .claude/settings.json in your project:

{
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(npm test)",
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff)",
      "Bash(git log *)",
      "Read",
      "Grep",
      "Glob"
    ],
    "deny": [
      "Read(*.env)",
      "Read(.env.*)",
      "Edit(*.env)",
      "Edit(.env.*)",
      "Edit(.git/**)"
    ]
  }
}

This configuration:

• Allows common safe commands without asking
• Blocks both reading and editing sensitive files
• Still asks permission for other file modifications

3. Test the Setup

> "Run the tests"
# Should execute without permission prompt (if configured)

> "What commands are available?"
# Claude will read package.json and list scripts

> "What's in CLAUDE.md?"
# Claude will read and summarize your project context

Source: Quickstart, Settings

Advanced Features

Thinking Mode [OFFICIAL]

Claude Code supports extended thinking for complex reasoning tasks. Opus 4.5 has thinking mode enabled by default.

Activation Methods:

# Toggle with keyboard shortcut
Alt+T (or Option+T on macOS)  # Toggle thinking on/off

# Or use natural language
> "think about this problem"
> "think harder about the architecture"
> "ultrathink about this security issue"

# Tab key (sticky toggle)
Press Tab to toggle thinking mode on/off for subsequent prompts

Thinking Levels:

Best Practices:

• Use think harder for debugging complex issues
• Use ultrathink for architectural decisions or security reviews
• Thinking content is visible in Ctrl+O transcript mode
• Thinking mode is sticky - stays on until toggled off

Source: Thinking Mode

Model Lineup [NEW] [OFFICIAL]

Models added to Claude Code since v2.1.39, newest first. Switch with /model or --model.

Removed / migrated:

• Opus 4 and 4.1 were removed from Claude Code on the first-party API in v2.1.68; pinned users moved to Opus 4.6.
• Sonnet 4.5 with 1M context was removed from the Max plan in v2.1.49 in favor of Sonnet 4.6.
• Sonnet 4.5 users on Pro/Max/Team Premium were auto-migrated to Sonnet 4.6 (v2.1.69).

Effort levels: /effort (added v2.1.76) accepts low, medium, high, xhigh, max, and ultracode, plus auto to reset to the model default. xhigh arrived in v2.1.111 and ultracode in v2.1.160; ultracode is a Claude Code setting rather than a model level — it sends xhigh and additionally orchestrates dynamic workflows, and it is session-only. max is also session-only unless set through CLAUDE_CODE_EFFORT_LEVEL, and the persisted effortLevel setting accepts only low, medium, high, and xhigh. Defaults have shifted several times — high for API-key/Bedrock/Vertex/Foundry/Team/Enterprise since v2.1.94, high for Pro/Max on Opus 4.6 and Sonnet 4.6 since v2.1.117, and high by default on Opus 4.8. Skills, slash commands, and agents can set effort: in frontmatter, and hooks receive effort.level / $CLAUDE_EFFORT.

Organization controls: admins can set an org default model (shown as "Org default" in /model, v2.1.196), restrict models with availableModels, and harden it with the enforceAvailableModels managed setting (v2.1.175).

Fast Mode [OFFICIAL]

Fast mode is a high-speed configuration that makes responses 2.5x faster at a higher cost per token. Available since v2.1.36.

Model support has moved. Fast mode launched on Opus 4.6, switched to Opus 4.7 by default in v2.1.142, added Opus 4.8 at a much lower premium in v2.1.154 (2x the standard rate for 2.5x the speed), and as of v2.1.219 /fast applies to Opus 5 and Opus 4.8 — Opus 4.7 was removed from fast mode. Opus 5 fast mode is $10/$50 per MTok. CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE was deprecated in v2.1.154 and removed in v2.1.160. The pricing table below is the original Opus 4.6 launch pricing and is kept for historical reference.

Toggle Fast Mode:

# Toggle with built-in command
/fast          # Toggle on/off

# Or set in settings
"fastMode": true   # In user settings file

Visual Indicators:

• ↯ icon appears next to prompt when fast mode is active
• Icon turns gray during rate limit cooldown

Pricing (per MTok) — original Opus 4.6 launch pricing:

Note: the Opus 4.6 fast-mode discount ran until February 16, 2026. Fast mode on Opus 4.8 is 2x the standard rate (v2.1.154), and Opus 5 fast mode is $10/$50 per MTok (v2.1.219).

Requirements:

• Claude subscription plan (Pro/Max/Team/Enterprise) or Claude Console API
• Usage credits enabled (/usage-credits, formerly /extra-usage)
• Not available on third-party providers (Bedrock, Vertex, Azure Foundry)
• For Teams/Enterprise: Admin must enable in organization settings

When to Use:

• ✅ Rapid iteration on code changes
• ✅ Live debugging sessions
• ✅ Time-sensitive work
• ❌ Long autonomous tasks (cost matters more)
• ❌ Batch processing or CI/CD pipelines

Fast Mode vs Effort Level:

You can combine both for maximum speed on straightforward tasks.

Rate Limits:

• Separate rate limits from standard Opus 4.6
• Automatically falls back to standard mode during cooldown
• Re-enables when cooldown expires

Source: Fast Mode

Plan Mode [OFFICIAL]

Plan Mode provides structured planning with model selection for complex tasks.

# Enter plan mode
/plan

# Or Claude may suggest plan mode for complex tasks
> "Implement a complete authentication system"
# Claude: "This is a complex task. Would you like me to create a plan first?"

Plan Mode Features:

• Opus planning, Sonnet execution - Uses stronger model for planning, faster model for implementation
• SonnetPlan Mode - Sonnet planning, Haiku execution (cost-effective)
• Shift+Tab - Auto-accept edits in plan mode
• Plan persistence - Plans persist across /clear

Plan Mode Workflow:

1. Claude analyzes the task and creates a structured plan
2. You review and approve or modify the plan
3. Claude executes the plan step by step
4. Progress is tracked with TodoWrite

Source: Plan Mode

Background Tasks & Agents [OFFICIAL]

Run commands and agents in the background while continuing to work.

Keyboard Shortcut:

Ctrl+B  # Background current command or agent (unified shortcut)

Background Commands:

# Start command in background
> "Run the dev server in background"
> "Start tests in watch mode in background"

# Or prefix with &
> "& npm run dev"

# View background tasks
/tasks
/bashes

# Kill a background task
/kill 

Background Agents:

# Launch agent in background
> "Have an Explore agent analyze the codebase architecture in background"

# Agents run asynchronously and notify you when complete
# You receive wake-up messages when background agents finish

Features:

• Real-time output streaming to status line
• Wake-up notifications when tasks complete
• Multiple concurrent background processes
• Output persisted to files for large outputs

Source: Background Tasks

Auto-Memory [NEW]

Claude Code now automatically records and recalls memories as it works (v2.1.32+).

How It Works:

• Claude automatically remembers important context, decisions, and patterns
• Memories persist across sessions and inform future work
• No manual intervention required

Memory Scopes for Agents:

---
name: my-agent
memory: project  # Options: user, project, local
---

Disable Auto-Memory:

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

Keyboard Shortcuts [OFFICIAL]

Navigation & Editing:

Model & Mode Switching:

Input & Submission:

Image & File Handling:

Vim Bindings (if enabled):

Login & Authentication:

Bash Mode Autocomplete [NEW v2.1.14]:

Prompt Suggestions [OFFICIAL]

Claude Code suggests prompts based on context (enabled by default).

# Claude suggests contextual prompts
> _  # Cursor blinking
# Suggestion appears: "Review the changes we made"

# Tab to edit the suggestion
Tab → Edit the suggestion text

# Enter to submit immediately
Enter → Submit the suggestion as-is

Configuration:

# Toggle in /config
/config
# Search for "prompt suggestions"
# Toggle enable/disable

Environment Variables [OFFICIAL]

Core Configuration:

Display & UI:

Bash & Commands:

Model Configuration:

MCP Configuration:

File & Context:

Network & Proxy:

Auto-Update & Plugins:

Monitoring & Telemetry:

Advanced:

Subagents & Background Sessions: [NEW]

Retries, Caching & Timeouts: [NEW]

Security & Enterprise: [NEW]

Windows & Shell: [NEW]

Telemetry (additions): [NEW]

New Settings [OFFICIAL]

Recent settings additions (configure in /config or settings.json):

{
  // Response language
  "language": "en",  // Claude's response language

  // Git integration
  "attribution": true,  // Add model name to commit bylines
  "respectGitignore": true,  // Respect .gitignore in searches

  // UI preferences
  "showTurnDuration": true,  // Show turn duration messages
  "fileSuggestion": "custom-cmd",  // Custom @ file search command
  "spinnerVerbs": ["analyzing", "thinking", "processing"],  // Custom spinner verbs
  "prefersReducedMotion": false,  // Reduce UI animations for accessibility [NEW v2.1.30]

  // Session behavior
  "companyAnnouncements": true,  // Show startup announcements

  // Plan mode
  "plansDirectory": ".claude/plans"  // Custom directory for plan files
}

Settings Added Since v2.1.39 [NEW] [OFFICIAL]

Managed (admin) settings added since v2.1.39: enforceAvailableModels, requiredMinimumVersion / requiredMaximumVersion, forceRemoteSettingsRefresh, parentSettingsBehavior, pluginSuggestionMarketplaces, allowedChannelPlugins, allowAllClaudeAiMcps, pluginTrustMessage, wslInheritsWindowsSettings, plus the managed-settings.d/ drop-in directory.

Skills Variable Substitution: [NEW]

# In skill files, use ${CLAUDE_SESSION_ID} for session-specific operations
Session ID: ${CLAUDE_SESSION_ID}

Project Rules:

# New: .claude/rules/ directory for project-specific rules
.claude/rules/
├── coding-style.md      # Coding conventions
├── testing.md           # Testing requirements
└── security.md          # Security guidelines

Wildcard Permissions:

{
  "permissions": {
    "allow": [
      "Bash(npm *)",
      "Bash(git *)",
      "mcp__myserver__*"
    ]
  }
}

Bash(npm *) and Bash(git *) are wildcard command patterns; mcp__myserver__* allows every tool from the myserver MCP server.

Skills System

Skills are unified capabilities that extend Claude Code — both auto-activated by Claude and manually invoked via /skill-name.

Note: Custom slash commands (.claude/commands/ files) have been merged into skills as of v2.1.3. Your existing command files keep working unchanged. Skills are recommended for new work because they support additional features like supporting files, invocation control, and subagent execution. See Migration: Commands to Skills.

Claude Code skills follow the Agent Skills open standard, which works across multiple AI tools. Claude Code extends the standard with additional features like invocation control, subagent execution, and dynamic context injection.

What Are Skills? [OFFICIAL]

Skills are instructions packaged as SKILL.md files that extend what Claude Code can do. Claude loads them when relevant to your request, or you invoke them directly:

# Claude auto-activates a skill based on your request
You: "Review this code for security issues"
Claude: [Loads security-reviewer skill automatically]

# Or you invoke a skill directly
You: /security-reviewer src/auth.ts
Claude: [Loads and executes the security-reviewer skill]

Two types of skill content:

• Reference content — Knowledge Claude applies to your current work (conventions, patterns, style guides). Runs inline alongside your conversation context.
• Task content — Step-by-step instructions for a specific action (deploy, commit, code generation). Often invoked manually with /skill-name.

Where Skills Live [OFFICIAL]

Where you store a skill determines who can use it:

When skills share the same name, higher-priority locations win: Enterprise > Personal > Project. Plugin skills use a plugin-name:skill-name namespace, so they cannot conflict.

Legacy compatibility: Files in .claude/commands/ still work and support the same frontmatter. If a skill and a command share the same name, the skill takes precedence.

Automatic nested directory discovery: When you work with files in subdirectories, Claude Code discovers skills from nested .claude/skills/ directories. For example, editing a file in packages/frontend/ also loads skills from packages/frontend/.claude/skills/. This supports monorepo setups where packages have their own skills.

Live change detection: Skills from directories added via --add-dir are loaded automatically and picked up by live change detection — edit them during a session without restarting.

Skill Directory Structure [OFFICIAL]

Each skill is a directory with SKILL.md as the entrypoint:

my-skill/
├── SKILL.md           # Main instructions (required)
├── template.md        # Template for Claude to fill in (optional)
├── examples/
│   └── sample.md      # Example output (optional)
└── scripts/
    └── validate.sh    # Script Claude can execute (optional)

Reference supporting files from your SKILL.md so Claude knows what each file contains:

## Additional resources
- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

Tip: Keep SKILL.md under 500 lines. Move detailed reference material to separate files.

Creating a Skill [OFFICIAL]

Step 1: Create the skill directory:

# Personal skill (available in all projects)
mkdir -p ~/.claude/skills/explain-code

# Project skill (shared with team via git)
mkdir -p .claude/skills/explain-code

Step 2: Write SKILL.md with frontmatter and instructions:

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

Keep explanations conversational. For complex concepts, use multiple analogies.

Step 3: Test the skill:

# Let Claude invoke it automatically
> "How does this code work?"

# Or invoke it directly
> /explain-code src/auth/login.ts

Frontmatter Reference [OFFICIAL]

Configure skill behavior with YAML frontmatter between --- markers at the top of SKILL.md. All fields are optional; only description is recommended.

Controlling Invocation [OFFICIAL]

By default, both you and Claude can invoke any skill. Two frontmatter fields restrict this:

• disable-model-invocation: true — Only you can invoke. Use for workflows with side effects (e.g., /deploy, /commit).
• user-invocable: false — Only Claude can invoke. Use for background knowledge that isn't actionable as a command.

# User-only skill (Claude won't auto-trigger)
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

# Model-only skill (hidden from / menu)
---
name: legacy-system-context
description: Background knowledge about the legacy system
user-invocable: false
---

Invocation and context-loading behavior:

Restricting Claude's access via /permissions:

# Allow only specific skills
Skill(commit)
Skill(review-pr *)

# Deny specific skills
Skill(deploy *)

# Disable all skills
Skill    # Add to deny rules

Permission syntax: Skill(name) for exact match, Skill(name *) for prefix match with any arguments.

Passing Arguments [OFFICIAL]

Skills accept arguments via placeholder substitutions:

Example:

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Implement the fix
3. Write tests
4. Create a commit

/fix-issue 123
# Claude receives: "Fix GitHub issue 123 following our coding standards..."

Indexed arguments:

---
name: compare-files
description: Compare two files
---

# Compare: $ARGUMENTS[0] vs $ARGUMENTS[1]
# Shorthand: $0 vs $1

Compare $0 and $1 for differences.

/compare-files "src/v1/api.ts" "src/v2/api.ts"
# $0 = "src/v1/api.ts", $1 = "src/v2/api.ts"

If $ARGUMENTS is not present in the skill content, arguments are appended as ARGUMENTS: .

Advanced Patterns [OFFICIAL]

Dynamic Context Injection

The !`command` syntax runs shell commands before the skill content is sent to Claude. The output replaces the placeholder:

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

Each !`command` executes immediately (before Claude sees anything). Claude only sees the final result with actual data.

Running in a Subagent

Add context: fork to run a skill in isolation. The skill content becomes the prompt that drives the subagent (no access to conversation history):

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

The agent field specifies which subagent to use. Options: built-in agents (Explore, Plan, general-purpose) or custom subagents from .claude/agents/. Default: general-purpose.

Warning: context: fork only makes sense for skills with explicit instructions. Guidelines without a task will return without meaningful output.

Extended Thinking

To enable extended thinking in a skill, include the word ultrathink anywhere in your skill content:

---
name: architecture-review
description: Deep architectural analysis
---

Use ultrathink to analyze the architecture deeply.

Review the overall structure, identify patterns, and suggest improvements.

Practical Examples

Example: Code Review Skill

.claude/skills/code-reviewer/SKILL.md:

---
name: code-reviewer
description: Reviews code for security vulnerabilities, bugs, performance issues, and style problems. Use when user asks to review, audit, or check code quality.
allowed-tools: [Read, Grep, Glob]
---

# Code Review Skill

## When to Activate
Use this skill when the user asks to:
- Review code for issues
- Audit security or find vulnerabilities
- Check code quality or best practices

## Review Process

### 1. Scope Detection
- Use Glob to identify files to review
- Prioritize recently modified files
- Focus on user-specified areas if mentioned

### 2. Analysis Layers
- **Security**: SQL injection, XSS, auth issues, exposed secrets
- **Bugs**: Logic errors, null checks, error handling
- **Performance**: N+1 queries, unnecessary loops, memory leaks
- **Style**: Naming conventions, code organization, readability

### 3. Reporting
Provide structured feedback organized by severity:
- **Critical/High**: Security issues
- **Medium**: Performance issues
- **Low**: Style and best practices

Each issue: file path, description, and fix suggestion.

Example: Test Generator Skill

.claude/skills/test-generator/SKILL.md:

---
name: test-generator
description: Generates comprehensive unit and integration tests. Use when user asks to write tests, add test coverage, or create test cases.
allowed-tools: [Read, Write, Grep, Glob, Bash]
---

# Test Generator Skill

## When to Activate
Use this skill when user requests:
- "Write tests for..."
- "Add test coverage"
- "Generate test cases"

## Test Generation Process

### 1. Analyze Target Code
- Read the file/function to test
- Identify inputs, outputs, side effects
- Check existing test patterns

### 2. Generate Comprehensive Tests
Cover all scenarios:
- Happy path (expected usage)
- Error cases (invalid inputs)
- Edge cases (empty, null, boundary values)
- Side effects (database, API calls)

### 3. Follow Project Patterns
- Check CLAUDE.md for testing conventions
- Match existing test file structure
- Use project's test framework

Example: Security Review Skill

.claude/skills/security-review/SKILL.md:

---
name: security-review
description: Comprehensive security audit of codebase. Use when asked to review security, audit vulnerabilities, or check for exploits.
allowed-tools: [Read, Grep, Glob]
disable-model-invocation: true
---

# Security Review: $ARGUMENTS

Perform a thorough security audit focusing on: $ARGUMENTS

## Review Checklist

### 1. Authentication & Authorization
- Check for weak password policies
- Verify JWT token validation
- Review session management
- Check for broken access control

### 2. Input Validation
- SQL injection vulnerabilities
- XSS (Cross-Site Scripting) risks
- Command injection possibilities
- Path traversal vulnerabilities

### 3. Data Protection
- Sensitive data exposure
- Encryption at rest and in transit
- API keys and secrets in code
- Database credential security

### 4. Dependencies
- Known vulnerabilities in packages
- Outdated dependencies
- License compliance issues

### 5. Configuration
- Security headers (CSP, HSTS, etc.)
- CORS configuration
- Error messages leaking information
- Debug mode in production

**Output Format** - Provide a detailed report with sections:
- Critical Issues (Fix Immediately)
- High Priority
- Medium Priority
- Low Priority / Recommendations
- Security Strengths
- Action Plan (prioritized list of fixes)

Usage:

/security-review "authentication and API endpoints"

Example: API Documentation Generator Skill

.claude/skills/api-docs/SKILL.md:

---
name: api-docs
description: Generate comprehensive API documentation from code. Use when asked to document APIs, create API docs, or generate OpenAPI specs.
allowed-tools: [Read, Write, Grep, Glob]
disable-model-invocation: true
---

# Generate API Documentation

Analyze the codebase and create comprehensive API documentation for: $ARGUMENTS

## Process

### 1. Discovery
- Find all API routes/endpoints
- Identify request/response types
- Note authentication requirements
- Document query parameters

### 2. Documentation
For each endpoint, document:
- Method and path
- Description
- Authentication requirements
- Request body/parameters
- Response codes and bodies
- Example requests

### 3. Output
- Create `/docs/API.md` with full documentation
- Create `/openapi.yaml` with OpenAPI spec if applicable

Usage:

/api-docs "all endpoints"
/api-docs "authentication routes"

File References with @ Syntax [OFFICIAL]

Reference files with @ prefix for quick file inclusion:

# Reference single file
/review-code @src/auth.ts

# Reference multiple files
/review-code @src/auth.ts @src/api.ts @tests/auth.test.ts

# Works in regular prompts too
> "Review @src/services/payment.ts for security issues"

# Reference files with skill arguments
/analyze-file @src/components/UserProfile.tsx

How @ References Work:

• @filename automatically expands to include file content
• Works with both absolute and relative paths
• Can reference multiple files in one command
• Files are read and included in context automatically
• Reduces need to explicitly say "read file X first"

Use Cases:

# Code review with context
> "Compare @src/api/v1.ts and @src/api/v2.ts and list differences"

# Refactoring across files
> "Make @src/models/User.ts consistent with @src/types/user.d.ts"

# Bug investigation
> "This error occurs in @src/services/auth.ts, check @logs/error.log for clues"

# Test generation
> "Generate tests for @src/utils/validator.ts"

Best Practices:

• Use @ references when you know exact file paths
• Combine with skills for reusable workflows
• Great for focused analysis of specific files
• Reduces token usage vs. reading entire directories

MCP Integration [OFFICIAL]

MCP servers can expose prompts that become invocable skills automatically:

{
  "prompts": [
    {
      "name": "search-docs",
      "description": "Search internal documentation",
      "arguments": [{"name": "query", "description": "Search query"}]
    }
  ]
}

This becomes available as /search-docs in Claude Code.

# Add MCP server
claude mcp add github -- gh-mcp

# MCP prompts become skills:
/github-pr-review      # Review current PR
/github-issues         # List open issues
/github-create-pr      # Create PR from current branch

Skill Best Practices [OFFICIAL]

1. Write Clear, Specific Descriptions

The description field is critical — it helps Claude decide when to activate:

Good:

description: "Generates API documentation from code comments. Use when user asks to document APIs, create API docs, update endpoint documentation, or generate OpenAPI specs."

Bad:

description: "Documentation generator"  # Too vague

2. Use Natural Trigger Words

Include terms users would naturally say:

# For security review skill
description: "Reviews code for security. Use when asked to: review security, audit code, find vulnerabilities, check for exploits, analyze risks."

# For performance optimization skill
description: "Optimizes code performance. Use when asked to: improve performance, optimize speed, reduce memory usage, make faster, profile code."

3. Restrict Tools Appropriately

# Analysis only (can't modify code)
allowed-tools: [Read, Grep, Glob]

# Can create/modify code
allowed-tools: [Read, Write, Edit, Bash]

# Research and implementation
allowed-tools: [Read, Write, Edit, WebFetch, WebSearch]

4. Keep Skills Focused

Good (focused):

• sql-optimizer — Optimizes SQL queries only
• api-docs-generator — Generates API documentation
• security-scanner — Finds security issues

Bad (too broad):

• database-everything — Too vague
• code-helper — What kind of help?

5. Provide Clear Instructions

Structure your SKILL.md:

1. When to Activate — Clear triggers
2. Process — Step-by-step what to do
3. Output Format — How to present results
4. Examples — Show expected behavior

6. Mind the Context Budget

Skill descriptions are loaded into context so Claude knows what's available. If you have many skills, they may exceed the character budget (2% of context window, fallback 16,000 characters). Run /context to check for warnings about excluded skills.

Override the limit with the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable.

Troubleshooting Skills [OFFICIAL]

Skill not triggering:

1. Check the description includes keywords users would naturally say
2. Verify the skill appears when you ask "What skills are available?"
3. Try rephrasing your request to match the description
4. Invoke directly with /skill-name to confirm it works

Skill triggers too often:

1. Make the description more specific
2. Add disable-model-invocation: true for manual-only invocation

Claude doesn't see all skills:

• Too many skill descriptions may exceed the character budget
• Run /context to check for a warning about excluded skills
• Set SLASH_COMMAND_TOOL_CHAR_BUDGET to a higher value

Migration: Commands to Skills

Custom slash commands (.claude/commands/ files) have been merged into the skills system. Your existing command files keep working unchanged. Skills are recommended for new work because they support:

• Supporting files — Bundle templates, scripts, and reference docs alongside your skill
• Invocation control — Choose whether you, Claude, or both can invoke
• Subagent execution — Run skills in isolated forked contexts
• Nested discovery — Automatic loading from subdirectories (monorepo support)

Migration path:

# Old structure (still works)
.claude/commands/review.md

# New structure (recommended)
.claude/skills/review/SKILL.md

Both create /review and work the same way. If both exist, the skill takes precedence.

Source: Agent Skills

Built-in Commands

Built-in commands are native CLI commands for managing your Claude Code session. They are hardcoded into Claude Code and are NOT skills — you cannot customize or override them.

Note: For custom workflow commands, use Skills instead. Built-in commands like /help and /compact are not available through the Skill tool.

Command Reference [OFFICIAL]

# Session Management
/help              # Show all available commands
/exit              # End current session
/clear             # Clear conversation history
/compact [instr]   # Compact context (optionally specify what to focus on)
/rewind            # Undo code changes in conversation (/undo is an alias) [v2.1.108]
/recap             # Summarize what happened while you were away [NEW v2.1.108]
/goal   # Keep working across turns until a completion condition is met [NEW v2.1.139]
/loop [interval]   # Run a prompt or slash command on a repeat (/proactive alias) [NEW v2.1.71]
/effort [level]    # Set reasoning effort: low / medium / high / xhigh / max / ultracode
                   #   (/effort auto resets to the model default) [NEW v2.1.76]
/focus             # Toggle focus view (Ctrl+O now toggles verbose transcript) [NEW v2.1.110]
/tui [fullscreen]  # Switch renderer mode in the same conversation [NEW v2.1.110]

# Session & History
/rename      # Give current session a name (auto-generates if omitted)
/resume [name|id]  # Resume a previous session by name or ID (includes background sessions)
/export            # Export conversation to file
/copy [N]          # Copy a response or code block to the clipboard (N = Nth-latest)
/branch            # Fork the conversation into a new session (/fork is an alias) [v2.1.77]
/fork              # Copy the conversation into a new background session [v2.1.212]
/subtask           # Run a sub-task as an in-session subagent [NEW v2.1.212]
/background        # Send the current session to the background [NEW]
/cd          # Move the session to a new working directory [NEW v2.1.169]
/btw               # Ask a side question without disturbing the main thread

# Usage & Stats
/usage             # Plan limits, usage, and per-category breakdown (merges /cost and /stats)
/stats             # Shortcut into the /usage stats tab
/usage-credits     # Enable usage credits (formerly /extra-usage) [v2.1.144]
/fast              # Toggle fast mode (Opus 5 and Opus 4.8 as of v2.1.219)
/insights          # Usage insights report

# Background Process Management
/bashes            # List all background processes
/tasks             # List all background tasks (agents, shells, etc.)
/kill          # Stop a background process

# Discovery & Debugging
/bug               # Report bugs (sends conversation to Anthropic)
/commands          # List all skills and commands
/debug             # Troubleshoot session issues [NEW v2.1.30]
/hooks             # Show configured hooks
/skills            # List available Skills
/plugin            # Plugin management interface
/context           # Context usage grid plus actionable optimization suggestions
/cost              # Shortcut into the /usage cost tab
/doctor            # Full setup checkup that can diagnose and fix issues (/checkup alias)
/reload-skills     # Re-scan skill directories without restarting [NEW v2.1.152]
/reload-plugins    # Activate pending plugin changes without restarting [NEW v2.1.69]
/powerup           # Interactive lessons teaching Claude Code features [NEW v2.1.90]
/team-onboarding   # Generate a teammate ramp-up guide from your usage [NEW v2.1.101]
/scroll-speed      # Tune mouse wheel scroll speed with a live preview [NEW v2.1.139]

# Configuration
/config            # General settings (type to search and filter)
/permissions       # Manage tool permissions (with search)
/privacy-settings  # View and update privacy settings
/status            # Show session status (Status tab)
/statusline        # Configure status line display
/model             # Switch between models
/config key=value  # Set any setting from the prompt (/config --help lists keys) [NEW v2.1.181]
/output-style      # ⚠️ Deprecated in v2.1.73 - use /config instead
/theme             # Theme picker; create named custom themes since v2.1.118
/color [name]      # Set the prompt-bar color for this session (/color default resets) [NEW v2.1.75]
/terminal-setup    # Configure terminal (Kitty, Alacritty, Zed, Warp)
/vim               # ⚠️ Removed in v2.1.92 - toggle vim mode via /config → Editor mode
/sandbox           # Enable sandboxed bash with filesystem/network isolation

# Workspace Management
/add-dir     # Add additional directory to workspace
/agents            # ⚠️ Wizard removed in v2.1.198 - ask Claude or edit .claude/agents/ directly
/init              # Initialize project with CLAUDE.md guide
/memory            # Edit CLAUDE.md memory files
/install-github-app # Set up Claude GitHub Actions for repository
/pr-comments       # View pull request comments
/review [pr]       # Fast single-pass code review [v2.1.202]
/code-review [lvl] # Multi-agent review at a chosen effort level; --fix applies findings,
                   #   --comment posts inline GitHub PR comments [NEW v2.1.147]
/simplify          # Cleanup-only review (reuse, simplification, efficiency) [v2.1.152]
/ultrareview [pr]  # Cloud multi-agent review of your branch or a PR [NEW v2.1.111]
/security-review   # Complete security review of pending changes
/workflows         # View dynamic workflow runs [NEW v2.1.154]
/deep-research     # Run a multi-agent research task (manual invocation only)
/dataviz           # Chart and dashboard design guidance skill [NEW v2.1.198]
/claude-api        # Skill for building with the Claude API and Anthropic SDK [NEW v2.1.69]
/less-permission-prompts  # Propose an allowlist from your transcripts [NEW v2.1.111]
/batch             # Run a batch of related tasks [NEW v2.1.63]
/todos             # List current TODO items

# MCP Server Management
/mcp               # MCP server management and OAuth authentication
/mcp enable   # Enable an MCP server
/mcp disable  # Disable an MCP server

# Remote Sessions (claude.ai subscribers)
/teleport          # Resume remote session from claude.ai by session ID
/remote-env        # Configure remote session environment
/remote-control    # Bridge this session to claude.ai/code for mobile/web control
/chrome            # Manage the Claude in Chrome connection (GA in v2.1.198)
/voice             # Voice dictation (20 languages as of v2.1.69)
/schedule          # Manage scheduled tasks

# Account & Updates
/login             # Switch Anthropic accounts
/logout            # Sign out from Anthropic account
/release-notes     # View release notes

# Plan Mode
/plan              # Enter plan mode for structured planning

Source: CLI Reference, Interactive Mode

Hooks System

Hooks are automated scripts that execute at specific points in Claude Code's workflow.

What Are Hooks? [OFFICIAL]

Hooks let you intercept and control Claude's actions:

# Examples of what hooks can do:
- Block editing of sensitive files (.env)
- Inject context at session start
- Run linting before file edits
- Validate git commits
- Audit all commands executed
- Add custom security checks

Two Types:

1. Bash Command Hooks (type: "command") - Run shell scripts
2. Prompt-Based Hooks (type: "prompt") - Use LLM for context-aware decisions

Hook Configuration [OFFICIAL]

Hooks are configured in .claude/settings.json or ~/.claude/settings.json:

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {"type": "command", "command": "script"}
        ]
      }
    ]
  }
}

Hook Events [OFFICIAL]

Hook configuration additions since v2.1.39:

Example: Protect Sensitive Files [OFFICIAL]

.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'FILE=$(echo \"$HOOK_INPUT\" | jq -r \".tool_input.file_path // empty\"); if [[ \"$FILE\" == *\".env\"* ]] || [[ \"$FILE\" == \".git/\"* ]]; then echo \"Cannot modify sensitive files\" >&2; exit 2; fi'"
          }
        ]
      }
    ]
  }
}

How it works:

• Runs before any Edit or Write tool
• Checks if file path contains ".env" or ".git/"
• Exits with code 2 to block the operation
• Claude receives error and doesn't edit the file

Example: Session Context Injection [OFFICIAL]

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cat .claude/session-context.txt"
          }
        ]
      }
    ]
  }
}

Creates: .claude/session-context.txt

Today's Focus: Working on authentication refactor
Recent Context: Migrated from sessions to JWT
Current Branch: feature/jwt-auth
Important: Don't modify legacy auth code in /old-auth

This context is injected at every session start.

Example: Intelligent Decision Hook [OFFICIAL]

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if the current task is complete. Arguments: $ARGUMENTS. Check if all subtasks are done, tests pass, and documentation updated. Respond with {\"decision\": \"stop\" or \"continue\", \"reason\": \"explanation\"}"
          }
        ]
      }
    ]
  }
}

Uses an LLM (Haiku) to intelligently decide if Claude should stop working.

Hook Input/Output [OFFICIAL]

Input (via stdin as JSON):

{
  "sessionId": "abc123",
  "tool_name": "Edit",
  "tool_input": {
    "file_path": "/src/app.ts",
    "old_string": "...",
    "new_string": "..."
  },
  "project_dir": "/home/user/project"
}

Output (exit codes):

• 0 - Success, continue
• 2 - Block the action
• Other - Non-blocking error (logged)

JSON Output (optional):

{
  "decision": "stop",
  "reason": "All tasks complete",
  "continue": false
}

Security Best Practices [OFFICIAL]

⚠️ Critical: "By using hooks, you are solely responsible for configured commands, which can modify or delete files your user can access."

Best Practices:

# 1. Always quote variables
FILE="$HOOK_INPUT"  # Good
FILE=$HOOK_INPUT    # Bad - can break with spaces

# 2. Validate paths
if [[ "$FILE" == ../* ]]; then
  echo "Path traversal attempt" >&2
  exit 2
fi

# 3. Use absolute paths
cd "$CLAUDE_PROJECT_DIR" || exit 1

# 4. Sanitize inputs
jq -r '.tool_input.file_path' <<< "$HOOK_INPUT"  # Good
eval "$SOME_VAR"  # Bad - code injection risk

# 5. Block sensitive operations
case "$FILE" in
  *.env|.git/*|.ssh/*)
    echo "Blocked: sensitive file" >&2
    exit 2
    ;;
esac

Debugging Hooks [OFFICIAL]

# Run Claude with debug mode
claude --debug

# Check hook configuration
> /hooks

# Test hook command manually
echo '{"tool_name":"Edit","tool_input":{"file_path":".env"}}' | bash your-hook-script.sh

# View logs
tail -f ~/.claude/logs/claude.log

Hook Recipes Library [OFFICIAL + COMMUNITY]

Comprehensive collection of production-ready hook patterns for common automation needs.

1. Auto-Format Code on Save [COMMUNITY]

Automatically formats code after Claude edits files using language-appropriate formatters.

Configuration (.claude/settings.json):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/format-code.sh"
          }
        ]
      }
    ]
  }
}

Script (~/.claude/hooks/format-code.sh):

#!/bin/bash
# Extract file path from JSON input
FILE=$(echo "$HOOK_INPUT" | jq -r '.tool_input.file_path // empty')

[[ -z "$FILE" ]] && exit 0

# Format based on extension
case "$FILE" in
  *.ts|*.tsx|*.js|*.jsx)
    # Try Biome first, fall back to Prettier
    if command -v biome &> /dev/null; then
      biome format --write "$FILE" &> /dev/null || true
    elif command -v prettier &> /dev/null; then
      prettier --write "$FILE" &> /dev/null || true
    fi
    ;;
  *.py)
    # Python: Ruff
    if command -v ruff &> /dev/null; then
      ruff format "$FILE" &> /dev/null || true
    fi
    ;;
  *.go)
    # Go: goimports + gofmt
    if command -v goimports &> /dev/null; then
      goimports -w "$FILE" &> /dev/null || true
    fi
    go fmt "$FILE" &> /dev/null || true
    ;;
  *.md)
    # Markdown: Prettier
    if command -v prettier &> /dev/null; then
      prettier --write "$FILE" &> /dev/null || true
    fi
    ;;
esac

Make executable: chmod +x ~/.claude/hooks/format-code.sh

2. ESLint Auto-Fix on Edit [COMMUNITY]

Automatically runs ESLint with --fix on JavaScript/TypeScript files.

Configuration:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'FILE=$(echo \"$HOOK_INPUT\" | jq -r \".tool_input.file_path // empty\"); if [[ \"$FILE\" =~ \\.(ts|tsx|js|jsx)$ ]] && command -v eslint &>/dev/null; then eslint --fix \"$FILE\" &>/dev/null || true; fi'"
          }
        ]
      }
    ]
  }
}

3. Block .gitignore Reads [COMMUNITY]

Prevents Claude from reading files matching .claudeignore patterns.

Configuration:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "claude-ignore"
          }
        ]
      }
    ]
  }
}

Installation: npm install -g claude-ignore && claude-ignore init

4. Run Tests Before Commits [COMMUNITY]

Validates that tests pass before allowing git commits.

Configuration:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/pre-commit-test.sh"
          }
        ]
      }
    ]
  }
}

Script (~/.claude/hooks/pre-commit-test.sh):

#!/bin/bash
COMMAND=$(echo "$HOOK_INPUT" | jq -r '.tool_input.command // empty')

# Only intercept git commit commands
if [[ "$COMMAND" == git*commit* ]]; then
  echo "Running tests before commit..." >&2

  # Run tests
  if npm test &>/dev/null; then
    echo "✅ Tests passed" >&2
    exit 0
  else
    echo "❌ Tests failed - blocking commit" >&2
    exit 2
  fi
fi

exit 0

5. Audit Logging Hook [COMMUNITY]

Logs all tool usage for security auditing.

Configuration:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'echo \"$(date -Iseconds) $TOOL_NAME: $(echo \\\"$HOOK_INPUT\\\" | jq -c .)\" >> ~/.claude/audit.log'"
          }
        ]
      }
    ]
  }
}

6. Token Usage Tracker [COMMUNITY]

Monitors and logs token usage per session.

Configuration:

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/log-session.sh"
          }
        ]
      }
    ]
  }
}

Script:

#!/bin/bash
SESSION_ID=$(echo "$HOOK_INPUT" | jq -r '.session_id // "unknown"')
TRANSCRIPT=$(echo "$HOOK_INPUT" | jq -r '.transcript_path // empty')

if [[ -f "$TRANSCRIPT" ]]; then
  TOKENS=$(jq '[.[] | select(.role=="assistant") | .usage.total_tokens] | add' "$TRANSCRIPT" 2>/dev/null || echo 0)
  echo "$(date -Iseconds) Session $SESSION_ID: $TOKENS tokens" >> ~/.claude/token-usage.log
fi

7. Commit Message Validation [COMMUNITY]

Enforces conventional commit message format.

Configuration:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/validate-commit.sh"
          }
        ]
      }
    ]
  }
}

Script:

#!/bin/bash
COMMAND=$(echo "$HOOK_INPUT" | jq -r '.tool_input.command // empty')

if [[ "$COMMAND" == git*commit*-m* ]]; then
  MSG=$(echo "$COMMAND" | sed -n 's/.*-m[[:space:]]*["'"'"']\([^"'"'"']*\)["'"'"'].*/\1/p')

  # Check conventional commit format: type(scope): message
  if [[ ! "$MSG" =~ ^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: ]]; then
    echo "❌ Commit message must follow format: type(scope): message" >&2
    echo "Valid types: feat, fix, docs, style, refactor, test, chore" >&2
    exit 2
  fi
fi

exit 0

8. Security Secret Scanner [COMMUNITY]

Prevents committing files containing potential secrets.

Configuration:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/detect-secrets.sh"
          }
        ]
      }
    ]
  }
}

Script:

#!/bin/bash
FILE=$(echo "$HOOK_INPUT" | jq -r '.tool_input.file_path // empty')
NEW_CONTENT=$(echo "$HOOK_INPUT" | jq -r '.tool_input.new_string // .tool_input.content // empty')

# Check for common secret patterns
if echo "$NEW_CONTENT" | grep -iE '(api[_-]?key|password|secret|token|auth)["\s:=]+\S{16,}' &>/dev/null; then
  echo "⚠️  Potential secret detected in $FILE" >&2
  echo "Please review and use environment variables instead" >&2
  exit 2
fi

exit 0

9. Auto-Documentation Update [COMMUNITY]

Updates README when code changes are made.

Configuration:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'echo \"📝 Consider updating documentation for recent changes\" >&2'"
          }
        ]
      }
    ]
  }
}

10. Performance Profiling [COMMUNITY]

Tracks execution time of tool operations.

Configuration:

{
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'echo \"$HOOK_INPUT\" > /tmp/claude-pre-$$.json; date +%s%N > /tmp/claude-time-$$.txt'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/profile-tool.sh"
          }
        ]
      }
    ]
  }
}

Script:

#!/bin/bash
START=$(cat /tmp/claude-time-$$.txt 2>/dev/null || echo 0)
END=$(date +%s%N)
DURATION=$(( (END - START) / 1000000 ))  # milliseconds
TOOL=$(echo "$HOOK_INPUT" | jq -r '.tool_name // "unknown"')

echo "$(date -Iseconds) $TOOL: ${DURATION}ms" >> ~/.claude/performance.log

rm -f /tmp/claude-pre-$$.json /tmp/claude-time-$$.txt

Source: Hooks Reference, Hooks Guide, Community GitHub repositories

MCP Integration

Model Context Protocol (MCP) connects Claude Code to external data sources and tools.

What is MCP? [OFFICIAL]

MCP allows Claude Code to:

• Access external data (Google Drive, Slack, Jira, Notion, etc.)
• Use specialized tools (databases, APIs, services)
• Integrate with enterprise systems
• Extend capabilities beyond local filesystem

Common Use Cases:

• Read/write Google Drive documents
• Search Slack conversations
• Query databases directly
• Fetch from internal APIs
• Access design files (Figma)
• Manage project tasks (Jira, Linear)

MCP Server Installation [OFFICIAL]

MCP servers can be added via CLI or configuration files:

CLI Installation (Recommended):

# Remote HTTP Server (recommended for hosted services)
claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# With authentication headers
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

# Local Stdio Server (for local packages)
claude mcp add --transport stdio airtable -- npx -y airtable-mcp-server
claude mcp add --transport stdio postgres -- npx -y @modelcontextprotocol/server-postgres "$DATABASE_URL"

# With environment variables
claude mcp add --transport stdio --env AIRTABLE_API_KEY=your_key airtable -- npx -y airtable-mcp-server

# Windows (requires cmd /c wrapper)
claude mcp add --transport stdio myserver -- cmd /c npx -y @some/package

MCP Server Management:

claude mcp list              # List all configured servers
claude mcp get github        # Get details for specific server
claude mcp remove github     # Remove a server
/mcp                         # Interactive management in Claude Code

Installation Scopes:

# Local scope (default) - stored in ~/.claude.json under project path
claude mcp add --transport http stripe https://mcp.stripe.com

# Project scope - stored in .mcp.json (shared via git)
claude mcp add --scope project --transport http paypal https://mcp.paypal.com/mcp

# User scope - stored in ~/.claude.json (available across all projects)
claude mcp add --scope user --transport http hubspot https://mcp.hubspot.com

Configuration File (.mcp.json):

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"],
      "env": {
        "DB_URL": "${DB_URL}",
        "API_KEY": "${API_KEY:-default-value}"
      }
    },
    "slack": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
        "SLACK_TEAM_ID": "${SLACK_TEAM_ID}"
      }
    }
  }
}

OAuth Authentication [OFFICIAL]

Many MCP servers support OAuth for secure authentication:

# Add server that requires OAuth
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# Within Claude Code, authenticate via browser
/mcp
# Follow browser steps to complete OAuth login

Manual OAuth Configuration:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "oauth": {
        "provider": "github",
        "scopes": ["repo", "read:user"]
      }
    }
  }
}

Claude Code opens a browser to complete the OAuth flow on first use.

Using MCP Tools [OFFICIAL]

Once configured, MCP tools appear with the pattern mcp____:

# Example: Google Drive search
> "Search our Google Drive for Q4 planning documents"

# Claude uses: mcp__google-drive__search_files

# Example: Database query
> "Show all users created in the last week"

# Claude uses: mcp__postgres__query with SQL

# Example: Slack search
> "Find conversations about the API redesign"

# Claude uses: mcp__slack__search_messages

MCP in Hooks [OFFICIAL]

You can reference MCP tools in hooks:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__postgres__query",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Database query requires review' && read -p 'Approve? (y/n) ' -n 1 -r && [[ $REPLY =~ ^[Yy]$ ]]"
          }
        ]
      }
    ]
  }
}

Popular MCP Servers [COMMUNITY]

# Official Servers
@modelcontextprotocol/server-google-drive      # Google Drive access
@modelcontextprotocol/server-slack             # Slack integration
@modelcontextprotocol/server-github            # GitHub API
@modelcontextprotocol/server-postgres          # PostgreSQL database
@modelcontextprotocol/server-sqlite            # SQLite database
@modelcontextprotocol/server-filesystem        # Extended file access

# Community Servers
# Check GitHub for community-built MCP servers

MCP Configuration Management [OFFICIAL]

# Enable all project MCP servers automatically
{
  "enableAllProjectMcpServers": true
}

# Whitelist specific servers
{
  "enabledMcpjsonServers": ["google-drive", "postgres"]
}

# Blacklist servers
{
  "disabledMcpjsonServers": ["risky-server"]
}

# Enterprise: Restrict to managed servers only
{
  "useEnterpriseMcpConfigOnly": true,
  "allowedMcpServers": ["approved-server-1", "approved-server-2"]
}

MCP Tool Search [NEW]

When MCP tool definitions exceed a threshold of the context window, they're automatically deferred via an MCPSearch tool:

# Configure tool search threshold (% of context window)
ENABLE_TOOL_SEARCH=auto:5 claude    # Activate at 5%
ENABLE_TOOL_SEARCH=auto:10 claude   # Activate at 10% (default)
ENABLE_TOOL_SEARCH=true claude      # Always enabled
ENABLE_TOOL_SEARCH=false claude     # Always disabled

# Or configure in settings.json
{
  "permissions": {
    "deny": ["MCPSearch"]  # Disable MCP tool search
  }
}

Source: MCP Documentation, Settings

MCP Setup Examples [OFFICIAL]

Quick-start configurations for popular MCP servers.

GitHub Integration

# Installation
claude mcp add --transport stdio github -- npx -y @modelcontextprotocol/server-github

# Or via .mcp.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Common operations: Create issues, manage PRs, search code, review repositories.

Slack Integration

# Installation
claude mcp add --transport stdio slack -- npx -y @modelcontextprotocol/server-slack

# Configuration
{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
        "SLACK_TEAM_ID": "T01234567"
      }
    }
  }
}

Usage: > "Search Slack for conversations about API redesign"

Google Drive Integration

# Installation with OAuth
claude mcp add --transport http gdrive https://mcp.google.com/drive

# Or stdio with credentials
{
  "mcpServers": {
    "gdrive": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-gdrive"],
      "env": {
        "GDRIVE_CREDENTIALS_PATH": "${HOME}/.gdrive-credentials.json"
      }
    }
  }
}

Authenticate: Run /mcp in Claude Code and follow OAuth flow.

PostgreSQL Database

# Installation
claude mcp add --transport stdio postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://user:pass@localhost/db

# Configuration
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${DATABASE_URL}"
      ]
    }
  }
}

Usage: > "Show all users created in the last week from the database"

Notion Integration

# Installation
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Requires Notion OAuth - authenticate via /mcp command

Common operations: Query databases, create pages, search workspace.

Stripe Payment Integration

# Configuration
{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["-y", "@stripe/mcp-server"],
      "env": {
        "STRIPE_API_KEY": "${STRIPE_API_KEY}"
      }
    }
  }
}

Usage: > "List recent Stripe transactions and summarize revenue"

MCP Troubleshooting [COMMUNITY]

Common issues and solutions from GitHub issues and production usage.

Issue: MCP Server Not Showing in List

# Problem
claude mcp list
# Output: "No MCP servers configured"

# Solutions
1. Check file location:
   - User scope: ~/.claude/settings.json
   - Project scope: .mcp.json (in project root)

2. Verify JSON syntax:
   cat .mcp.json | jq .

3. Check scope setting:
   claude mcp add --scope project  ...

4. Restart Claude Code after config changes

Issue: Tools Not Available Despite "Connected"

# Problem
/mcp shows "✓ Connected" but tools don't appear

# Solutions
1. Check tool output size (max 25,000 tokens):
   export MAX_MCP_OUTPUT_TOKENS=50000

2. Verify server actually started:
   ps aux | grep mcp

3. Check debug logs:
   claude --debug
   tail -f ~/.claude/logs/claude.log

4. Reset project approvals:
   claude mcp reset-project-choices

Issue: OAuth Authentication Fails

# Problem
Browser opens but OAuth fails or doesn't complete

# Solutions
1. Use /mcp command (not direct URL)

2. Check network/proxy settings:
   # Try without VPN/Cloudflare Warp

3. Clear OAuth cache:
   rm -rf ~/.claude/oauth-cache

4. Verify redirect URI in provider settings

Issue: Windows "Connection Closed" Error

# Problem
MCP server immediately closes on Windows

# Solution - Use cmd /c wrapper:
claude mcp add --transport stdio myserver -- cmd /c npx -y package-name

# In .mcp.json:
{
  "mcpServers": {
    "myserver": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "package-name"]
    }
  }
}

Issue: Environment Variables Not Expanding

# Problem
${VAR} shows literally instead of expanding

# Solutions
1. Check .env file exists and is loaded

2. Use default syntax:
   "${API_KEY:-default_value}"

3. Set in shell before running:
   export API_KEY=xxx && claude

4. Use settings.local.json for sensitive values

Issue: MCP Server Process Crashes

# Debug steps:
1. Test server directly:
   npx @modelcontextprotocol/server-github

2. Check stdout/stderr:
   claude --debug | grep mcp

3. Verify dependencies installed:
   npm list -g | grep mcp

4. Check memory/resource limits:
   ulimit -a

Sub-Agents

Sub-agents are specialized AI assistants configured for specific tasks.

What Are Sub-Agents? [OFFICIAL]

Sub-agents are instances of Claude optimized for particular workflows:

# Built-in Sub-Agents
- general-purpose: Complex multi-step tasks
- Explore: Fast codebase exploration

# Custom Sub-Agents
- You can create your own with custom prompts and tools

Using Sub-Agents [OFFICIAL]

Launch with the Task tool:

# Explore codebase
> "Find all database queries in the codebase"

# Claude uses:
Task subagent_type="Explore"
     prompt="Find all database queries and list files containing SQL, Prisma, or ORM code"

# General purpose research
> "Research best practices for API rate limiting and suggest implementation"

# Claude uses:
Task subagent_type="general-purpose"
     prompt="Research API rate limiting approaches, compare options, and recommend implementation for Express.js"

Creating Custom Sub-Agents [OFFICIAL]

Sub-agents are defined as Markdown files in .claude/agents/ or ~/.claude/agents/:

Example: Debug Assistant

.claude/agents/debugger.md:

---
name: debugger
description: Specialized debugging agent for production issues
model: claude-sonnet-4
allowedTools: [Read, Grep, Glob, Bash]
---

# Debug Assistant

You are a specialized debugging agent. Your role is to systematically investigate and identify the root cause of issues.

## Debugging Process

### 1. Gather Context
- Read error messages and stack traces
- Check recent code changes (git log)
- Review related log files
- Understand expected vs actual behavior

### 2. Hypothesis Generation
- List possible causes
- Prioritize by likelihood
- Consider recent changes first

### 3. Systematic Investigation
- Test each hypothesis methodically
- Use Grep to find related code
- Read implementation details
- Check for similar patterns elsewhere

### 4. Root Cause Analysis
- Identify the precise cause
- Explain why it happens
- Trace the execution path

### 5. Solution Proposal
- Suggest specific fixes
- Explain tradeoffs
- Provide code examples
- Recommend tests to prevent recurrence

## Constraints
- DO NOT modify code (read-only analysis)
- DO provide detailed explanations
- DO reference specific file:line locations
- DO consider edge cases

Example: Code Review Agent

.claude/agents/reviewer.md:

---
name: reviewer
description: Code review specialist focusing on quality and best practices
model: claude-sonnet-4
allowedTools: [Read, Grep, Glob]
---

# Code Reviewer

You are a senior code reviewer. Provide constructive, actionable feedback.

## Review Criteria

### Code Quality
- Readability and maintainability
- Naming conventions
- Code organization
- DRY principle adherence

### Correctness
- Logic errors
- Edge cases handling
- Error handling
- Null/undefined checks

### Performance
- Algorithm efficiency
- Unnecessary computations
- Memory usage
- Database query optimization

### Security
- Input validation
- SQL injection risks
- XSS vulnerabilities
- Authentication/authorization

### Testing
- Test coverage
- Test quality
- Edge cases tested

## Output Format
Provide structured feedback:
- **Strengths**: What's done well
- **Issues**: Problems found (with severity)
- **Suggestions**: Improvements
- **Examples**: Code snippets for fixes

Sub-Agent Features [OFFICIAL]

Model Selection

Choose different models per agent:

---
name: fast-explorer
model: claude-haiku-4  # Fast, cost-effective
---

---
name: deep-analyzer
model: claude-opus-4  # Most capable
---

Tool Restrictions

Limit tools for focused operation:

---
name: readonly-analyzer
allowedTools: [Read, Grep, Glob]  # Analysis only
---

---
name: implementation-agent
allowedTools: [Read, Write, Edit, Bash]  # Can modify code
---

Sub-Agent Patterns [COMMUNITY]

Parallel Analysis

> "Have multiple agents analyze different aspects"

# Launches multiple agents in parallel:
- Security review agent
- Performance analysis agent
- Code style agent
- Test coverage agent

# Aggregates results

Sequential Pipeline

> "Research → Design → Implement authentication"

# Sequential sub-agents:
1. Research agent: Find best practices
2. Design agent: Create architecture
3. Implementation agent: Write code
4. Review agent: Verify implementation

Specialized Teams

{
  "frontend-agent": "React/UI specialist",
  "backend-agent": "API/database specialist",
  "devops-agent": "Deployment/infrastructure specialist"
}

Source: Sub-Agents

Agent Teams

Agent Teams enable multiple Claude Code instances to collaborate on complex tasks with shared context and direct communication.

What Are Agent Teams? [OFFICIAL]

Agent Teams (experimental) allow you to coordinate multiple Claude Code sessions working togeth