Content

Quick links: Install · Commands · Shortcuts · MCP · Troubleshoot

• Getting Started

  • Quick Start
  • Initial Setup

• Configuration & Environment

  • Environment Variables
  • Configuration Files

• Commands & Usage

  • Slash Command Reference
  • CLI Quick Reference

• Interface & Input

  • Keyboard Shortcuts
  • Vim Mode

• Advanced Features

  • Thinking Mode
  • Plan Mode
  • Fast Mode
  • Background Tasks
  • Claude in Chrome
  • Sandbox Mode
  • LSP Tool
  • Remote Sessions
  • Sub Agents
  • Agent Teams
  • Skills
  • Plugin System
  • Worktree Isolation
  • MCP Integration
  • Hooks System
  • Native Installer
  • Authentication CLI
  • Agent Management CLI
  • Remote Control
  • Managed Settings
  • Model Updates
  • Insights

• Security & Permissions

  • Dangerous Mode
  • Security Best Practices

• Automation & Integration

  • Automation & Scripting
  • Auto PR Review
  • Issue Triage

• Help & Troubleshooting

  • Installation Issues
  • MCP Issues
  • Best Practices

• Third-Party Integrations

  • DeepSeek Integration

Getting Started

Enable sound alerts when claude completes the task:

claude config set --global preferredNotifChannel terminal_bell

Quick Start

[!TIP] Send claude or npx claude in terminal to start the interface

Go to Help & Troubleshooting to fix issues...

# Native Installer (preferred — no Node.js required) ⭐️
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
# Windows
/* Via CMD (native)      */ curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
/* Via Powershell        */ irm https://claude.ai/install.ps1 | iex
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
# macOS / Linux / WSL
/* Via Terminal          */ curl -fsSL https://claude.ai/install.sh | bash
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
# Arch
/* Via Terminal          */ yay -S claude-code*/
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

# Alternative (npm) — deprecated in favor of native installer
# Requires Node.js 18+
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
# Windows
/* Via CMD (npm)         */ npm install -g @anthropic-ai/claude-code
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
# macOS
/* Via Terminal          */ brew install node && npm install -g @anthropic-ai/claude-code
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
# Linux
/* Via Terminal          */ sudo apt update && sudo apt install -y nodejs npm
/* Via Terminal          */ npm install -g @anthropic-ai/claude-code
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
# WSL/GIT
/* Via Terminal          */ npm install -g @anthropic-ai/claude-code
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
# Docker
/* Windows (CMD)         */ docker run -it --rm -v "%cd%:/workspace" -e ANTHROPIC_API_KEY="sk-your-key" node:20-slim bash -lc "npm i -g @anthropic-ai/claude-code && cd /workspace && claude"
/* macOS/Linux (bash/zsh)*/ docker run -it --rm -v "$PWD:/workspace" -e ANTHROPIC_API_KEY="sk-your-key" node:20-slim bash -lc 'npm i -g @anthropic-ai/claude-code && cd /workspace && claude'
/* No bash Fallback      */ docker run -it --rm -v "$PWD:/workspace" -e ANTHROPIC_API_KEY="sk-your-key" node:20-slim sh -lc 'npm i -g @anthropic-ai/claude-code && cd /workspace && claude'
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
# Check if claude is installed correctly
/* Linux                 */ which claude
/* Windows               */ where claude
/* Universal             */ claude --version
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
# Common Management
/*claude config          */ Configure settings
/*claude mcp list        */ Setup MCP servers, you can also replace "list" with add/remove
/*claude /agents         */ Configure/Setup Subagents for different tasks
/*claude update          */ Update to latest

[!Tip] Open Project Via Terminal Into VS Code / Cursor

$ - cd /path/to/project

$ - code .

Make sure you have the (Claude Code extension) installed in your VS Code / Cursor

System Requirements

• OS: macOS 10.15+, Ubuntu 20.04+/Debian 10+, or Windows 10/11 or WSL

• Hardware: 4GB RAM minimum 8GB+ recommended

• Software: Node.js 18+ or git 2.23+ (optional) & GitHub or GitLab CLI for PR workflows (optional)
• Node.js is only required for npm-based installation. The native installer bundles its own runtime.

• Internet: Connection for API calls

• Node.js 18+ (only required for npm-based installation; the native installer bundles its own runtime)

Initial Setup

[!Tip] Find API key from Anthropic Console

Do NOT commit real keys use git-ignored files, OS key stores, or secret managers

# Universal
/* start login process                    */ claude /login
/* Setup long-lived authentication token  */ claude setup-token
/* Authenticate via Anthropic account     */ claude auth login
----------------------------------------------------------------------------------------------------------------------------------
# Windows
/* Set-api-key        */ set ANTHROPIC_API_KEY=sk-your-key-here-here
/* cmd-masked-check   */ echo OK: %ANTHROPIC_API_KEY:~0,8%***
/* Set-persistent-key */ setx ANTHROPIC_API_KEY "sk-your-key-here-here"
/* cmd-unset-key      */ set ANTHROPIC_API_KEY=
----------------------------------------------------------------------------------------------------------------------------------
# Linux
/* Set-api-key        */ export ANTHROPIC_API_KEY="sk-your-key-here-here"
/* masked-check       */ echo "OK: ${ANTHROPIC_API_KEY:0:8}***"
/* remove-session     */ unset ANTHROPIC_API_KEY
----------------------------------------------------------------------------------------------------------------------------------
# Powershell
/* ps-session         */ $env:ANTHROPIC_API_KEY = "sk-your-key-here-here"
/* ps-masked-check    */ "OK: $($env:ANTHROPIC_API_KEY.Substring(0,8))***"
/* ps-persist         */ [Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY","sk-your-key-here-here","User")
/* ps-rotate          */ $env:ANTHROPIC_API_KEY = "sk-new-key"
/* ps-remove          */ Remove-Item Env:\ANTHROPIC_API_KEY
----------------------------------------------------------------------------------------------------------------------------------
# Other...
# persist-bash/*      */ echo 'export ANTHROPIC_API_KEY="sk-your-key-here-here"' >> ~/.bashrc && source ~/.bashrc
# persist-zsh /*      */ echo 'export ANTHROPIC_API_KEY="sk-your-key-here-here"' >> ~/.zshrc  && source ~/.zshrc
# persist-fish/*      */ fish -lc 'set -Ux ANTHROPIC_API_KEY sk-your-key-here-here'
----------------------------------------------------------------------------------------------------------------------------------

Configuration & Environment

Environment Variables

You can also set any of these in settings.json under the "env" key for automatic application.

[!Important] Windows Users replace export with set or setx for perm

# Environment toggles (put in ~/.bashrc or ~/.zshrc)
export ANTHROPIC_API_KEY="sk-your-key-here-here"      # API key sent as X-Api-Key header (interactive usage: /login)
export ANTHROPIC_AUTH_TOKEN="my-auth-token"           # Custom Authorization header; Claude adds "Bearer " prefix automatically
export ANTHROPIC_CUSTOM_HEADERS="X-Trace-Id: 12345"   # Extra request headers (format: "Name: Value")

export ANTHROPIC_MODEL="claude-sonnet-4-6-20260217"                # Custom model name to use
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-6-20260217" # Default Sonnet model alias
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-6-20260130"   # Default Opus model alias (Opus 4.6 now available)
export ANTHROPIC_SMALL_FAST_MODEL="haiku-model"                  # Haiku-class model for background tasks (placeholder)
export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION="REGION"            # Override AWS region for the small/fast model on Bedrock (placeholder)

export AWS_BEARER_TOKEN_BEDROCK="bedrock_..."         # Amazon Bedrock API key/token for authentication

export BASH_DEFAULT_TIMEOUT_MS=60000                  # Default timeout (ms) for long-running bash commands
export BASH_MAX_TIMEOUT_MS=300000                     # Maximum timeout (ms) allowed for long-running bash commands
export BASH_MAX_OUTPUT_LENGTH=20000                   # Max characters in bash outputs before middle-truncation

export CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # (0 or 1) return to original project dir after each Bash command
export CLAUDE_BASH_NO_LOGIN=1                         # When set, BashTool does not use a login shell. Default behavior changed in v2.1.51 (login shell used only as fallback).
export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=600000       # Interval (ms) to refresh creds when using apiKeyHelper
export CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1            # (0 or 1) skip auto-installation of IDE extensions
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096             # Max number of output tokens for most requests

export CLAUDE_CODE_USE_BEDROCK=1                      # (0 or 1) use Amazon Bedrock
export CLAUDE_CODE_USE_VERTEX=0                       # (0 or 1) use Google Vertex AI
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=0                # (0 or 1) skip AWS auth for Bedrock (e.g., via LLM gateway)
export CLAUDE_CODE_SKIP_VERTEX_AUTH=0                 # (0 or 1) skip Google auth for Vertex (e.g., via LLM gateway)

export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=0     # (0 or 1) disable nonessential traffic (equivalent to DISABLE_* below)
export CLAUDE_CODE_DISABLE_TERMINAL_TITLE=0           # (0 or 1) disable automatic terminal title updates

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1         # (0 or 1) enable agent teams research preview
export CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 # (0 or 1) load CLAUDE.md from --add-dir paths
export CLAUDE_CODE_ENABLE_TASKS=false                 # Set to "false" to disable new task system

export DISABLE_AUTOUPDATER=0                          # (0 or 1) disable automatic updates (overrides autoUpdates setting)
export DISABLE_BUG_COMMAND=0                          # (0 or 1) disable the /bug command
export DISABLE_COST_WARNINGS=0                        # (0 or 1) disable cost warning messages
export DISABLE_ERROR_REPORTING=0                      # (0 or 1) opt out of Sentry error reporting
export DISABLE_NON_ESSENTIAL_MODEL_CALLS=0            # (0 or 1) disable model calls for non-critical paths
export DISABLE_TELEMETRY=0                            # (0 or 1) opt out of Statsig telemetry

export HTTP_PROXY="http://proxy:8080"                 # HTTP proxy server URL
export HTTPS_PROXY="https://proxy:8443"               # HTTPS proxy server URL

export MAX_THINKING_TOKENS=0                          # (0 or 1 to turn off/on) force a thinking budget for the model
export MCP_TIMEOUT=120000                             # MCP server startup timeout (ms)
export MCP_TOOL_TIMEOUT=60000                         # MCP tool execution timeout (ms)
export MAX_MCP_OUTPUT_TOKENS=25000                    # Max tokens allowed in MCP tool responses (default 25000)

export USE_BUILTIN_RIPGREP=0                          # (0 or 1) set 0 to use system-installed rg instead of bundled one

export VERTEX_REGION_CLAUDE_3_5_HAIKU="REGION"        # Region override for Claude 3.5 Haiku on Vertex AI (legacy model family name)
export VERTEX_REGION_CLAUDE_3_5_SONNET="REGION"       # Region override for Claude 3.5 Sonnet on Vertex AI (legacy model family name)
export VERTEX_REGION_CLAUDE_3_7_SONNET="REGION"       # Region override for Claude 3.7 Sonnet on Vertex AI (legacy model family name)
# Note: CLAUDE_3_5_* and CLAUDE_3_7_* use legacy model family names and may be updated in future versions.
export VERTEX_REGION_CLAUDE_4_0_OPUS="REGION"         # Region override for Claude 4.0 Opus on Vertex AI
export VERTEX_REGION_CLAUDE_4_0_SONNET="REGION"       # Region override for Claude 4.0 Sonnet on Vertex AI
export VERTEX_REGION_CLAUDE_4_1_OPUS="REGION"         # Region override for Claude 4.1 Opus on Vertex AI
export VERTEX_REGION_CLAUDE_4_6_OPUS="REGION"         # Region override for Claude 4.6 Opus on Vertex AI
export VERTEX_REGION_CLAUDE_4_6_SONNET="REGION"       # Region override for Claude 4.6 Sonnet on Vertex AI

# ── New in v2.1.32–2.1.63 ──────────────────────────────────────────────────────
export CLAUDE_CODE_SIMPLE=1                            # Minimal mode: disables MCP tools, attachments, hooks, CLAUDE.md, and skills
export CLAUDE_CODE_DISABLE_1M_CONTEXT=1                # Disable 1 M-token context window (use default shorter context)
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Disable background tasks entirely
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1        # Opt out of experimental beta features
export CLAUDE_CODE_AUTO_CONNECT_IDE=false              # Disable automatic IDE connection on startup
export CLAUDE_CODE_TMPDIR="/custom/tmp"                # Override the temp directory Claude Code uses
export CLAUDE_CODE_SHELL="/bin/zsh"                    # Override shell detection (force a specific shell)
export CLAUDE_CODE_SHELL_PREFIX="command-wrapper"      # Prefix/wrap every shell command Claude runs
export CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS=50000   # Override max output tokens for the Read tool
export CLAUDE_CODE_PROXY_RESOLVES_HOSTS=true           # Let the HTTP/HTTPS proxy handle DNS resolution
export CLAUDE_CODE_EXIT_AFTER_STOP_DELAY=30000         # Auto-exit SDK mode after idle for N ms
export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=30000         # Timeout (ms) for plugin git operations
export CLAUDE_CODE_ACCOUNT_UUID="uuid"                 # Override account UUID (SDK / automation flows)
export CLAUDE_CODE_USER_EMAIL="user@example.com"       # Override user email (SDK / automation flows)
export CLAUDE_CODE_ORGANIZATION_UUID="uuid"            # Override organization UUID (SDK / automation flows)
export ENABLE_CLAUDEAI_MCP_SERVERS=false               # Opt out from claude.ai-synced MCP servers
export FORCE_AUTOUPDATE_PLUGINS=1                      # Allow plugin auto-update even when main updater is disabled
export IS_DEMO=1                                       # Demo mode — hides email/org from the UI
export NO_PROXY="localhost,127.0.0.1"                  # Bypass proxy for specified hosts (comma-separated)

Global Config Options

claude config set -g theme dark                               # Theme: dark | light | light-daltonized | dark-daltonized
claude config set -g preferredNotifChannel iterm2_with_bell   # Notification channel: iterm2 | iterm2_with_bell | terminal_bell | notifications_disabled
claude config set -g autoUpdates true                         # Auto-download & install updates (applied on restart)
claude config set -g verbose true                             # Show full bash/command outputs

claude config set -g attribution false                        # Omit "co-authored-by Claude" in git commits/PRs
claude config set -g forceLoginMethod claudeai                 # Restrict login flow: claudeai | console
claude config set -g model "claude-sonnet-4-6-20260217"       # Default model override
claude config set -g statusLine '{"type":"command","command":"~/.claude/statusline.sh"}'  # Custom status line

claude config set -g enableAllProjectMcpServers true              # Auto-approve all MCP servers from .mcp.json
claude config set -g enabledMcpjsonServers '["memory","github"]'  # Approve specific MCP servers
claude config set -g disabledMcpjsonServers '["filesystem"]'      # Reject specific MCP servers

Configuration Files

(Memory type) Claude Code offers four memory locations in a hierarchical structure, each serving a different purpose:

All memory files are automatically loaded into Claude Code's context when launched. Files higher in the hierarchy take precedence and are loaded first, providing a foundation that more specific memories build upon.

.claude/rules/ Directory (v2.0.64+)

The .claude/rules/ directory lets you break project instructions into separate Markdown files instead of one large CLAUDE.md. Every *.md file inside is automatically loaded into context alongside CLAUDE.md. This is useful for:

• Modular organization: Separate concerns (e.g., api-conventions.md, testing-rules.md)
• Per-directory overrides: Nested rules/ directories can apply scoped rules
• Team collaboration: Different team members can own different rule files via PR review

Auto-Memory (v2.1.32+)

Claude now automatically saves useful context to memory during your sessions. Managed memories include things like project conventions, tooling preferences, and architectural decisions that Claude observed while working with you. Use /memory to view and manage auto-saved memories.

Commands & Usage

Slash Command Reference

Command Line Flags

The --output-format json flag is particularly useful for scripting and automation, allowing you to parse Claude's responses programmatically.

CLI Quick Reference & Configuration Examples

## Claude Cheat Sheet

# Basics / interactive

claude # Start interactive REPL
claude "explain this project" # Start REPL seeded with a prompt
claude -p "summarize README.md" # Non-interactive print mode (SDK-backed)
cat logs.txt | claude -p "explain" # Pipe input to Claude and exit
claude -c # Continue most recent conversation (alias for --continue)
claude -r "<session-id>" "finish this" # Resume specific session by ID (alias for --resume)
claude --model claude-sonnet-4-6-20260217 # Pick model for this run
claude --max-turns 3 -p "lint this" # Cap agentic turns in print mode
claude --replay-user-messages # Replay user messages to stdout for debugging / SDK workflows

# Update & install

claude update # Manually update Claude Code
claude doctor # Diagnose install/version & setup
claude install # Start native binary installer (beta)
claude migrate-installer # Migrate from global npm to local installer

# Authentication (v2.1.41+)

claude auth login # Log in to your Anthropic account
claude auth status # Check authentication status
claude auth logout # Log out

# Agent management (v2.1.50+)

claude agents # List all configured agents (project, user, plugin)
claude remote-control # Start remote-control mode for external tooling

# Config: interactive wizard + direct ops

claude config # Interactive config wizard
claude config get <key> # Get value (e.g., claude config get theme)
claude config set <key> <val> # Set value (e.g., claude config set theme dark)
claude config add <key> <vals…> # Append to array-type keys (e.g., claude config add env DEV=1)
claude config remove <key> <vals…> # Remove items from list-type keys
claude config list # Show all current settings for project (project scope is default)

# Example project-scoped settings

claude config set model "claude-sonnet-4-6-20260217" # Override default model for this project
claude config set attribution false # Disable "co-authored-by Claude" byline in git/PRs
claude config set forceLoginMethod claudeai # Restrict login flow: claudeai | console
claude config set enableAllProjectMcpServers true # Auto-approve all MCP servers from .mcp.json
claude config set defaultMode "acceptEdits" # Set default permission mode
claude config set disableBypassPermissionsMode disable # Prevent bypassPermissions mode (example key)

# Manage list settings (project scope)

claude config add enabledMcpjsonServers github # Approve a specific MCP server from .mcp.json
claude config add enabledMcpjsonServers memory # Add another
claude config remove enabledMcpjsonServers memory # Remove one entry
claude config add disabledMcpjsonServers filesystem # Explicitly reject a specific MCP server

# Global scope (use -g or --global)

claude config set -g autoUpdates false # Turn off automatic updates globally
claude config set --global preferredNotifChannel iterm2_with_bell
claude config set -g theme dark # Theme: dark | light | light-daltonized | dark-daltonized
claude config set -g verbose true # Show full bash/command outputs everywhere
claude config get -g theme # Confirm a global value

# MCP (Model Context Protocol) management

claude mcp # Launch MCP wizard / configure MCP servers
claude mcp list # List configured MCP servers
claude mcp get <name> # Show details for a server
claude mcp remove <name> # Remove a server
claude mcp add <name> <command> [args...] # Add local stdio server
claude mcp add --transport sse <name> <url> # Add remote SSE server
claude mcp add --transport http <name> <url> # Add remote HTTP server
claude mcp add <name> --env KEY=VALUE -- <cmd> [args...] # Pass env to server command
claude mcp add --transport sse private-api https://api.example/mcp \
 --header "Authorization: Bearer TOKEN" # Add with auth header
claude mcp add-json <name> '<json>' # Add server via JSON blob
claude mcp add-from-claude-desktop # Import servers from Claude Desktop
claude mcp reset-project-choices # Reset approvals for project .mcp.json servers
claude mcp serve # Run Claude Code itself as an MCP stdio server

# Other useful flags (print / SDK mode)

claude --add-dir ../apps ../lib # Add additional working directories
claude --allowedTools "Bash(git log:\*)" "Read" # Allow listed tools without permission prompts
claude --disallowedTools "Edit" # Disallow listed tools without permission prompts
claude --append-system-prompt "Custom instruction" # Append to system prompt (only with -p)
claude -p "query" --output-format json --input-format stream-json # Control IO formats for scripting
claude --verbose # Verbose logging (turn-by-turn)
claude --dangerously-skip-permissions # Skip permission prompts (use with caution)
claude --permission-mode plan # Start in plan mode (read-only analysis)
claude --max-turns 3 -p "query" # Limit agentic turns (print mode only)
claude --max-budget-usd 5.00 -p "query" # Cap spending per session (print mode only)
claude --json-schema '{"type":"object"}' -p "query" # Get validated JSON output
claude --chrome # Enable Chrome browser integration
claude --remote "Fix the bug" # Create web session on claude.ai
claude --teleport # Resume web session locally
claude --agents '{"name":{...}}' # Define subagents via JSON

# Session management

claude -c # Continue most recent conversation
claude -r "session-name" # Resume by name or ID
claude --fork-session -r abc123 # Fork instead of reusing original
claude -w "implement feature" # Start in an isolated git worktree
/rename auth-refactor # Name current session
/resume # Open session picker
/export output.md # Export conversation to file
/fork # Fork the current conversation

# Quick verification / notes

# - Project scope is default for 'claude config'; use -g/--global to affect all projects.

# - Settings precedence: Enterprise > CLI args > local project > shared project > user (~/.claude).

# - Use 'add' / 'remove' only with list-type keys (e.g., enabledMcpjsonServers).

# - The CLI reference and release notes are the authoritative sources for flags and recent additions.

Interface & Input

Keyboard Shortcuts

Text Editing

Multiline Input

Quick Commands

[!Tip] PDF Page Ranges: Use the pages parameter with the Read tool for PDFs (e.g., pages: "1-5"). Large PDFs (>10 pages) return a lightweight reference when @-mentioned instead of being inlined.

Vim Mode

[!Note] Enable vim-style editing with /vim command or configure permanently via /config.

Vim Mode Switching

Vim Navigation

Vim Editing

[!Tip] Configure your preferred line break behavior in terminal settings. Run /terminal-setup to install Shift+Enter binding for iTerm2, VS Code, Kitty, Alacritty, Zed, Warp, and WezTerm.

Command History

Claude Code maintains command history for the current session:

* History is stored per working directory
* Cleared with `/clear` command
* Use Up/Down arrows to navigate (see keyboard shortcuts above)
* **Ctrl+R**: Reverse search through history (if supported by terminal)
* **Note**: History expansion (`!`) is disabled by default

Advanced Features

Thinking Keywords

[!Note] Gives Claude extra pre-answer planning time by adding ONE of these keywords to your prompt. Order (lowest → highest) token consumption

think -------------> Lowest think hard think harder ultrathink --------> Highest

This makes Claude spend more time:

1. Planning the solution

2. breaking down steps

3. weighing alternatives/trade-offs

4. checking constraints & edge cases

   Higher levels usually increase latency and token usage pick the smallest that works.

Examples

# Small boost

claude -p "Think. Outline a plan to refactor the auth module."

# Medium boost

claude -p "Think harder. Draft a migration plan from REST to gRPC."

# Max boost

claude -p "Ultrathink. Propose a step-by-step strategy to fix flaky payment tests and add guardrails."

Fast Mode

[!Note] Fast Mode provides accelerated response times for Opus 4.6, optimized for rapid iteration and quick tasks.

How to enable Fast Mode:

# Enable fast mode in the REPL (requires extra-usage first)
/extra-usage
/fast

# Or toggle during conversation
# The status bar will show when Fast Mode is active

Key features:

• Faster responses - Reduced latency for quick tasks
• Available for Opus 4.6 - New in version 2.1.36
• Requires extra-usage - Must enable /extra-usage first

When to use Fast Mode:

• Quick code reviews and edits
• Rapid prototyping
• Simple questions and commands
• Iterative debugging

Fast Mode trades some depth for speed. Use normal mode for complex analysis and planning tasks.

Plan Mode

[!Note] Plan Mode instructs Claude to analyze the codebase with read-only operations, perfect for exploring codebases, planning complex changes, or reviewing code safely.

When to use Plan Mode:

• Multi-step implementation: When your feature requires making edits to many files
• Code exploration: When you want to research the codebase thoroughly before changing anything
• Interactive development: When you want to iterate on the direction with Claude

How to enable Plan Mode:

# Start a new session in Plan Mode
claude --permission-mode plan

# Or toggle during session with Shift+Tab
# (cycles through: Normal → Auto-Accept → Plan Mode)

# Enter plan mode from the prompt
/plan

# Run headless queries in Plan Mode
claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"

Configure Plan Mode as default:

// .claude/settings.json
{
  "permissions": {
    "defaultMode": "plan"
  }
}

Background Tasks

[!Note] Claude Code supports running bash commands in the background, allowing you to continue working while long-running processes execute.

How to use background tasks:

Key features:

• Output is buffered and Claude can retrieve it using the TaskOutput tool
• Background tasks have unique IDs for tracking and output retrieval
• Background tasks are automatically cleaned up when Claude Code exits
• Use /tasks to list and manage background tasks

Common backgrounded commands:

• Build tools (webpack, vite, make)
• Package managers (npm, yarn, pnpm)
• Test runners (jest, pytest)
• Development servers
• Long-running processes (docker, terraform)

Bash mode with ! prefix:

# Run bash commands directly without Claude interpretation
! npm test
! git status
! ls -la

Disable background tasks:

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

Remote Sessions

[!Note] For subscribers: Use --remote to start tasks on claude.ai and --teleport to resume them locally.

Start a remote session:

# Create a new web session on claude.ai with task description
claude --remote "Fix the login bug"

Resume a remote session:

# Resume a web session in your local terminal
claude --teleport

# Or use the slash command
/teleport

Claude in Chrome

Claude Code can control Google Chrome for browser-based tasks like testing, web scraping, and UI verification.

Setup:

claude --chrome                    # Launch with Chrome integration

Capabilities:

• Navigate to URLs, click elements, fill forms
• Take screenshots and analyze page content
• Execute JavaScript in the browser context
• Interact with web applications for testing

[!NOTE] Requires Google Chrome installed. Claude uses the Chrome DevTools Protocol for browser control.

Sandbox Mode

Sandbox mode restricts the BashTool to run commands in an isolated environment, preventing modifications to your actual filesystem.

/sandbox              # Toggle sandbox mode on/off

When sandboxed:

• File system writes are contained
• Network access may be restricted
• Useful for testing destructive commands safely

Available on Linux and macOS. Use claude --sandbox to start in sandbox mode.

LSP Tool (Language Server Protocol)

Claude Code integrates with language servers to provide IDE-level code intelligence:

• Go to Definition — Jump to where a symbol is defined
• Find References — Find all usages of a symbol across the codebase
• Hover Information — Get type information and documentation

The LSP tool activates automatically when a compatible language server is available for the current project. This enables Claude to navigate codebases more precisely than text search alone.

Tool results exceeding 50,000 characters are automatically persisted to disk to manage context efficiently.

Sub Agents

Sub‑Agents are purpose‑built helpers with their own prompts, tools, and isolated context windows. Treat this like a "mixture‑of‑experts" you compose per repo.

Built-in Subagents

Claude Code includes built-in subagents that Claude automatically uses when appropriate:

Claude delegates to Explore when it needs to search or understand a codebase without making changes, keeping exploration results out of your main conversation context.

When to use subagents:

• You need high signal responses (plans, reviews, diffs) without side quests.
• You want version‑controlled prompts and tool policies alongside the codebase.
• You work in PR‑driven teams and want scoped edits by role.
• The task produces verbose output you don't need in your main context.

Each Sub‑Agent Has Its Own Context

Design rules for your lineup

• Define one clear responsibility per agent.
• Keep the minimum tool set needed for that role.
• Prefer read‑only agents for analysis/review tasks.
• Give edit powers to as few agents as possible.

Caption: Agents selection UI in the terminal.

Configure Agents

Keep agents in the project so they're versioned with the repo and evolve via PRs.

Quick start

Update CLI and open the agents panel

claude update
/agents

Subagent Scopes

Define Agents via CLI

# Define custom subagents dynamically via JSON
claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  },
  "background-impl": {
    "description": "Implements features in an isolated worktree in the background.",
    "prompt": "Implement the requested feature. Commit when done.",
    "isolation": "worktree",
    "background": true
  }
}'

Create your core agents

• planner (read‑only): turns features/issues into small, testable tasks; outputs a task list or plan.md.
• codegen (edit‑capable): implements tasks; limited to src/ + tests/.
• tester (read‑only or patch‑only): writes one failing test or a minimal repro.
• reviewer (read‑only): leaves structured review comments; never edits.
• docs (edit‑capable): updates README.md/docs/ only.

*Policy tip: Prefer patch output for edit‑capable agents so changes land through your normal Git workflow.*

Caption: Choose only the tools an agent truly needs (e.g., advisory vs editing access).

Example prompts

Keep prompts short, testable, and repo‑specific. Check them into agents/:

Caption: Example prompt for a test‑coverage‑analyzer agent.

tester.prompt.md (sample)

Role: Write a single, focused failing test for the specific scenario I describe.
Scope: Only create/modify tests under tests/. Do not change src/.
Output: A brief rationale + a unified diff or patch.
If the scenario is unclear, ask exactly one clarifying question.

Expected output

Your tester agent should produce a small diff or patch plus a short rationale:

Caption: Example response from the test‑coverage‑analyzer agent.

Subagent Frontmatter Fields

Subagent files use YAML frontmatter for configuration:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
disallowedTools: Write, Edit
model: sonnet
permissionMode: default
skills:
  - api-conventions
---

You are a code reviewer. Analyze the code and provide feedback.

Why This Shift Matters

Operational benefits

• Less context switching: you stay in one mental mode; agents do the rest.
• Cleaner PRs: narrow prompts + limited tools → smaller, reviewable diffs.
• Fewer regressions: tester/reviewer agents catch gaps before merge.
• Repeatability: prompts + policies live in the repo and travel with branches.

Security & governance

• Limit write access by path (e.g., src/, tests/, docs/).
• Favor read‑only analysis for high‑risk areas.
• Log/commit assistant outputs as patches for auditability.

A Mindset Shift

Do

• Treat agents as teammates with job descriptions.
• Start read‑only; grant write access last.
• Keep prompts in version control and iterate via PR.

Don't

• Ask one agent to plan, code, and test in a single turn.
• Give blanket write permissions.
• Accept multi‑file diffs when you asked for one test.

Agent Teams (Research Preview)

[!Note] Agent Teams is an experimental feature enabling multiple Claude instances to work in parallel on a shared codebase autonomously.

Enable Agent Teams:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Key Concepts:

• Multiple Claude instances run in parallel on the same codebase
• Each agent can specialize in different tasks (debugging, documentation, testing, etc.)
• Agents communicate through git-based synchronization
• Enables autonomous, long-running development workflows

Case Study: C Compiler Built by Agent Teams

Anthropic's research team demonstrated agent teams by tasking 16 parallel Claude instances to build a C compiler from scratch. Key results:

Lessons for Agent Teams:

1. Write high-quality tests - The task verifier must be nearly perfect
2. Design for parallelism - Agents should be able to work independently without blocking each other
3. Specialize agents - Dedicate agents to specific roles (code quality, documentation, performance)
4. Maintain context files - Keep READMEs and progress files updated for agent orientation

Read the full case study: Building a C Compiler with Parallel Claudes

Skills (Custom Slash Commands)

[!Note] Skills extend what Claude can do. Create a SKILL.md file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with /skill-name.

Skill Locations

Project skills override personal skills with the same name. Files in .claude/commands/ still work and support the same frontmatter.

Create a Skill

# Create skill directory
mkdir -p ~/.claude/skills/explain-code

Create ~/.claude/skills/explain-code/SKILL.md:

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works.
---

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?

Use the skill:

# Let Claude invoke automatically
How does this code work?

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

Skill Frontmatter Fields

Pass Arguments to Skills

Use $ARGUMENTS placeholder to receive arguments:

---
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

Usage: /fix-issue 123

Inject Dynamic Context

Use !`command` syntax to run shell commands before the skill content is sent to Claude:

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
---

## 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...

Run Skills in a Subagent

Add context: fork to run a skill in isolation:

---
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 can be Explore, Plan, general-purpose, or any custom subagent from .claude/agents/.

Plugin System

[!Note] Plugins extend Claude Code with custom commands, skills, agents, hooks, and MCP servers. Plugins can be loaded from local directories, Git repos, or the npm registry.

Key commands:

# Install a plugin from a Git repository
/plugins install https://github.com/org/claude-plugin-example

# Install from npm registry
/plugins install @org/claude-code-plugin

# List installed plugins
/plugins list

# Enable / disable a plugin
/plugins enable <plugin-name>
/plugins disable <plugin-name>

# Validate a plugin's structure
/plugins validate ./my-plugin

# Browse the plugin marketplace (community plugins)
/plugins marketplace

Plugin structure:

my-plugin/
├── plugin.json          # Plugin manifest (name, version, description)
├── agents/              # Custom agents (*.md frontmatter files)
├── skills/              # Custom skills (SKILL.md files)
├── hooks/               # Hook scripts
├── commands/            # Custom slash commands
└── mcp-servers/         # MCP server configurations

Plugin scopes:

Plugin manifest (plugin.json):

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "A Claude Code plugin",
  "agents": ["agents/"],
  "skills": ["skills/"],
  "hooks": "hooks/hooks.json",
  "mcpServers": "mcp-servers/servers.json"
}

Plugins auto-update by default. Set FORCE_AUTOUPDATE_PLUGINS=1 to force updates even when the main updater is disabled, or override with CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS for slow repos.

Worktree Isolation (v2.1.49+)

[!Note] The --worktree (-w) flag starts Claude in an isolated git worktree, allowing it to make changes in a separate branch without affecting your working directory.

Usage:

# Start Claude in an isolated worktree
claude -w "implement the new feature"

# Claude will:
# 1. Create a temporary git worktree from your current branch
# 2. Run in that isolated worktree
# 3. Commit changes and optionally create a PR
# 4. Clean up the worktree when done

Agent-level worktree isolation:

---
name: background-coder
description: Implements features in isolation
isolation: worktree
background: true
---

Implement the requested feature in this isolated worktree.

Worktree isolation is especially powerful combined with background: true for agents, enabling parallel development workflows where multiple agents work on separate features simultaneously.

Native Installer (v2.1.15+)

[!Note] Claude Code now offers a native binary installer as an alternative to the npm global install. The native installer provides faster startup, auto-updates, and doesn't require Node.js on your PATH.

# Start the native installer (interactive)
claude install

# Migrate from npm global install to native installer
claude migrate-installer

# Windows ARM64 is supported natively since v2.1.41

The npm installation method (npm install -g @anthropic-ai/claude-code) continues to work. A deprecation notice for npm-based installs was introduced in v2.1.15, but both methods are supported.

Authentication CLI (v2.1.41+)

[!Note] Manage authentication directly from the CLI without entering the REPL.

# Log in to your Anthropic account
claude auth login

# Check current authentication status
claude auth status

# Log out
claude auth logout

Agent Management CLI (v2.1.50+)

[!Note] List and inspect all configured agents from the command line.

# List all agents (project, user, plugin, CLI-defined)
claude agents

Remote Control (v2.1.51+)

[!Note] The claude remote-control subcommand allows external tools and build systems to drive Claude Code programmatically.

# Start Claude in remote-control mode
claude remote-control

This is useful for IDE extensions, CI/CD pipelines, or custom orchestration tools that want to interact with Claude Code via its SDK interface.

Managed Settings (v2.1.51+)

[!Note] Enterprise administrators can push managed settings via macOS plist or Windows Registry, providing organization-wide configuration control.

macOS (plist):

Settings can be deployed via MDM profiles to /Library/Managed Preferences/com.anthropic.claude-code.plist.

Windows (Registry):

Settings can be deployed via Group Policy to HKLM\SOFTWARE\Policies\Anthropic\ClaudeCode.

Managed settings take precedence over user/project settings and cannot be overridden by individual users.

Model Updates

Claude Sonnet 4.6 (February 17, 2026)

[!Note] Claude Sonnet 4.6 delivers frontier-level performance at Sonnet pricing ($3/$15 per million tokens) with a 1M-token context window.

Key highlights:

• Approaches Opus-level performance on coding, reasoning, and agent planning tasks
• 1M token context window (previously only available on Max plan for Sonnet 4.5)
• Improved coding benchmarks: significant gains on SWE-bench, agentic coding, and multi-file refactoring
• Better long-context reasoning: improved accuracy across needle-in-a-haystack and long-document tasks
• Enhanced computer use: more reliable browser automation and GUI interaction
• Same pricing as Sonnet 4.5: $3 input / $15 output per million tokens

Use in Claude Code:

# Set as default model
claude --model sonnet

# Or pin the specific version
claude --model claude-sonnet-4-6-20260217

# Configure in settings
claude config set model "claude-sonnet-4-6-20260217"

Sonnet 4.5 with 1M context has been removed from the Max plan in favor of Sonnet 4.6. Claude Opus 4.6 (released in v2.1.32) remains available for the most demanding tasks.

Claude Code Insights

[!Note] The /insights command generates an interactive HTML report analyzing your coding habits from the past 30 days.

Run Insights:

# In Claude Code terminal
/insights

# Open the generated report
start ~/.claude/usage-data/report.html     # Windows
open ~/.claude/usage-data/report.html      # Mac
xdg-open ~/.claude/usage-data/report.html  # Linux

How It Works:

1. Session Collection - Pulls session logs from ~/.claude/projects/, filters agent sub-sessions and short sessions
2. Metadata Extraction - Extracts duration, token usage, tools used, languages detected, git activity
3. Facet Extraction - Uses Haiku model to analyze transcripts and identify goals, satisfaction signals, friction points
4. Report Generation - Creates interactive HTML report with personalized suggestions

Report Sections:

Everything runs locally using the Anthropic API. Session data stays on your machine.

MCP Integration

Understanding MCP (Model Context Protocol)

What is MCP?

MCP extends Claude's capabilities by connecting to external services, databases, APIs, and tools (filesystem, Puppeteer, GitHub, Context7 etc...)

MCP Architecture:

Claude Code ←→ MCP Protocol ←→ MCP Servers ←→ External Services

claude.ai MCP Connectors

Claude Code can use MCP servers configured in your claude.ai account, bringing cloud-hosted tools to your CLI workflow.

# Enabled by default — to opt out:
export ENABLE_CLAUDEAI_MCP_SERVERS=false

This allows you to access the same MCP tool integrations available in claude.ai directly from the command line, without local MCP server configuration.

MCP Setup & Configuration

Basic MCP Commands

claude mcp                   # Interactive MCP configuration
claude mcp list              # List configured servers
claude mcp add <name> <cmd>  # Add new server
claude mcp remove <name>     # Remove server

MCP Configuration File Location

~/.claude.json      # Global File
`.mcp.json`         # Project-scoped servers are stored in a File at your project's root directory

Quick Start

If you're in a hurry, here's the fastest way to add:

# Add file system access (most commonly used)
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Desktop

# Verify if successful
claude mcp list

Responce if it worked like it should:

Additional Methods:

# Basic syntax
claude mcp add <name> <command> [parameters...]

# Actual example: Add local file system access
claude mcp add my-filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

# Example with environment variables
claude mcp add api-server -e API_KEY=your-key-here -- /path/to/server

# Add MCP server with pre-configured OAuth credentials
claude mcp add <name> --client-id <id> --client-secret <secret> -- <cmd>

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Documents"
      ],
      "env": {}
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-github-token"
      }
    }
  }
}

# Add project-level MCP server
claude mcp add shared-tools -s project -- npx -y @your-team/mcp-tools

{
  "mcpServers": {
    "shared-tools": {
      "command": "npx",
      "args": ["-y", "@your-team/mcp-tools"],
      "env": {}
    }
  }
}

MCP Server Scope Detailed

Understanding scope is crucial to avoid "server not found" errors:

1. Local Scope (Default)

• Only available in current directory
• Configuration stored in the projects section of ~/.claude.json
• Suitable for: Personal project-specific tools

2. User Scope (Global)

• Available in all projects
• Added using -s user flag
• Suitable for: Common tools like file systems, database clients

3. Project Scope (Team shared)

• Shared through .mcp.json file
• Added using -s project flag
• Suitable for: Team-shared project-specific tools

Practical MCP Server Recommendations

Here's the most worthwhile MCP server list to install:

1. File System Access

claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Projects ~/Desktop

Use: Let Claude directly read and write files, modify code

2. GitHub Integration

claude mcp add github -s user -e GITHUB_TOKEN=your-token -- npx -y @modelcontextprotocol/server-github

Use: Manage issues, PRs, code reviews

3. Web Browser Control

claude mcp add puppeteer -s user -- npx -y @modelcontextprotocol/server-puppeteer

Use: Automated web operations, crawling, testing

4. Database Connection (PostgreSQL)

claude mcp add postgres -s user -e DATABASE_URL=your-db-url -- npx -y @modelcontextprotocol/server-postgres

Use: Directly query and manipulate databases

5. Fetch Tool (API Calls)

claude mcp add fetch -s user -- npx -y @kazuph/mcp-fetch

Use: Call various REST APIs

6. Search Engine

claude mcp add search -s user -e BRAVE_API_KEY=your-key -- npx -y @modelcontextprotocol/server-brave-search

Use: Search for latest information

7. Slack Integration

claude mcp add slack -s user -e SLACK_TOKEN=your-token -- npx -y @modelcontextprotocol/server-slack

Use: Send messages, manage channels

8. Time Management

claude mcp add time -s user -- npx -y @modelcontextprotocol/server-time

Use: Time zone conversion, date calculation

9. Memory Storage

claude mcp add memory -s user -- npx -y @modelcontextprotocol/server-memory

Use: Save information across conversations

10. Sequential Thinking (Thought Chain)

claude mcp add thinking -s user -- npx -y @modelcontextprotocol/server-sequential-thinking

Use: Step-by-step thinking for complex problems

Common Errors and Solutions

Error 1: Tool Name Validation Failed

API Error 400: "tools.11.custom.name: String should match pattern '^[a-zA-Z0-9_-]{1,64}$'"

Solution:

• Ensure server name only contains letters, numbers, underscores and hyphens
• Name length should not exceed 64 characters
• Don't use special characters or spaces

Error 2: MCP Server Not Found

MCP server 'my-server' not found

Solution:

1. Check if scope settings are correct
2. Run claude mcp list to confirm server has been added
3. Ensure you're in the correct directory (for local scope)
4. Restart Claude Code

Error 3: Protocol Version Error

"protocolVersion": "Required"

Solution: This is a known bug in Claude Code, temporary solutions:

1. Use wrapper scripts
2. Ensure MCP server returns correct protocol version
3. Update to latest version of Claude Code

Error 4: Windows Path Issues

Error: Cannot find module 'C:UsersusernameDocuments'

Solution: Windows paths need to use forward slashes or double backslashes:

# Wrong
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Documents

# Correct
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:/Users/username/Documents
# or
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:\\Users\\username\\Documents

Error 5: Permission Issues

Permission denied

Solution:

1. macOS/Linux: Use sudo (not recommended) or modify file permissions
2. Windows: Run as administrator
3. Best method: Install MCP servers in user directory

Debugging Techniques

When encountering problems, these debugging methods can help you quickly locate issues:

1. Enable Debug Mode

claude --debug

2. View MCP Status

In Claude Code, enter:

/mcp

3. View Log Files

macOS/Linux:

tail -f ~/Library/Logs/Claude/mcp*.log

Windows:

type "%APPDATA%\Claude\logs\mcp*.log"

4. Manually Test Server

# Directly run server command to see if there's output
npx -y @modelcontextprotocol/server-filesystem ~/Documents

Special Notes for International Users

1. Non-English Path Issues

Avoid using non-English characters in paths:

# Avoid
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem ~/文档

# Recommended
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

2. Proxy Configuration

If you're using a proxy:

# Set npm proxy
npm config set proxy http://your-proxy:port
npm config set https-proxy http://your-proxy:port

# Then add MCP server
claude mcp add ...

3. Mirror Sources

Use mirror sources to accelerate downloads:

# Temporary use
claude mcp add fs -- npx -y --registry=https://registry.npmjs.org @modelcontextprotocol/server-filesystem ~/Documents

# Or permanent setting
npm config set registry https://registry.npmjs.org

Best Practice Recommendations

1. Add as needed: Don't add too many MCP servers at once, it will affect performance
2. Regular cleanup: Use claude mcp remove <name> to delete unused servers
3. Security first: Only add trusted MCP servers, especially those requiring network access
4. Backup configuration: Regularly backup ~/.claude.json file
5. Team collaboration: Use project scope to share common configurations

Advanced Techniques

1. Create Custom MCP Server

If existing MCP servers can't meet your needs, you can create your own:

// my-mcp-server.js
import { Server } from "@modelcontextprotocol/sdk";

const server = new Server({
  name: "my-custom-server",
  version: "1.0.0",
});

server.setRequestHandler("tools/list", async () => {
  return {
    tools: [
      {
        name: "my_custom_tool",
        description: "Custom tool",
        inputSchema: {
          type: "object",
          properties: {
            input: { type: "string" },
          },
        },
      },
    ],
  };
});

server.start();

2. Batch Configuration Script

Create a script to configure all common MCP servers at once:

#!/bin/bash
# setup-mcp.sh

echo "Configuring common MCP servers..."

# File system
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Projects

# GitHub
read -p "Enter GitHub Token: " github_token
claude mcp add github -s user -e GITHUB_TOKEN=$github_token -- npx -y @modelcontextprotocol/server-github

# Other servers...

echo "MCP servers configured successfully!"

Popular MCP Servers

Development Tools

# npm install -g git-mcp-server

# claude mcp add git "git-mcp-server"
# claude mcp add github "github-mcp-server --token $GITHUB_TOKEN"

Database Integration

npm install -g postgres-mcp-server
npm install -g mysql-mcp-server
npm install -g sqlite-mcp-server

# Setup examples may look like this:
# export POSTGRES_URL="postgresql://user:password@localhost:5432/mydb"
# claude mcp add postgres "postgres-mcp-server --url $POSTGRES_URL"

MCP Tool Permissions

# Allow specific MCP tools
claude --allowedTools "mcp__git__commit,mcp__git__push"

# Allow all tools from specific server
claude --allowedTools "mcp__postgres__*"

# Combined with built-in tools
claude --allowedTools "Edit,View,mcp__git__*"

Hooks System

This page provides reference documentation for implementing hooks in Claude Code.

[!TIP] For a quickstart guide with examples, see Get started with Claude Code hooks.

Configuration

Claude Code hooks are configured in your settings files:

• ~/.claude/settings.json - User settings
• .claude/settings.json - Project settings
• .claude/settings.local.json - Local project settings (not committed)
• Enterprise managed policy settings

Structure

Hooks are organized by matchers, where each matcher can have multiple hooks:

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

HTTP Hooks (v2.1.63+)

In addition to shell commands, hooks can POST JSON to a URL and receive a JSON response:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "http",
            "url": "https://hooks.example.com/validate",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

HTTP hooks send the same JSON payload that command hooks receive via stdin, as a POST body. The response JSON follows the same output schema. This is useful for centralized policy enforcement or remote hook execution without local scripts.

• matcher: Pattern to match tool names, case-sensitive (only applicable for PreToolUse and PostToolUse)
  • Simple strings match exactly: Write matches only the Write tool
  • Supports regex: Edit|Write or Notebook.*
  • Use * to match all tools. You can also use empty string ("") or leave matcher blank.
• hooks: Array of commands to execute when the pattern matches
  • type: "command" (shell command) or "http" (POST JSON to a URL, v2.1.63+)
  • command: The bash command to execute (can use $CLAUDE_PROJECT_DIR environment variable)
  • timeout: (Optional) How long a command should run, in seconds, before canceling that specific command.

For events like UserPromptSubmit, Notification, Stop, and SubagentStop that don't use matchers, you can omit the matcher field:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/prompt-validator.py"
          }
        ]
      }
    ]
  }
}

Project-Specific Hook Scripts

You can use the environment variable CLAUDE_PROJECT_DIR (only available when Claude Code spawns the hook command) to reference scripts stored in your project, ensuring they work regardless of Claude's current directory:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-style.sh"
          }
        ]
      }
    ]
  }
}

Hook Events

PreToolUse

Runs after Claude creates tool parameters and before processing the tool call.

Common matchers:

• Task - Subagent tasks (see subagents documentation)
• Bash - Shell commands
• Glob - File pattern matching
• Grep - Content search
• Read - File reading
• Edit, MultiEdit - File editing
• Write - File writing
• WebFetch, WebSearch - Web operations

PostToolUse

Runs immediately after a tool completes successfully.

Recognizes the same matcher values as PreToolUse.

Notification

Runs when Claude Code sends notifications. Notifications are sent when:

1. Claude needs your permission to use a tool. Example: "Claude needs your permission to use Bash"
2. The prompt input has been idle for at least 60 seconds. "Claude is waiting for your input"

UserPromptSubmit

Runs when the user submits a prompt, before Claude processes it. This allows you to add additional context based on the prompt/conversation, validate prompts, or block certain types of prompts.

Stop

Runs when the main Claude Code agent has finished responding. Does not run if the stoppage occurred due to a user interrupt.

SubagentStop

Runs when a Claude Code subagent (Task tool call) has finished responding.

TeammateIdle

Triggered when an agent teammate becomes idle (multi-agent workflows).

TaskCompleted

Triggered when a background task completes (multi-agent workflows).

ConfigChange

Fires when Claude Code configuration files change (e.g., settings, CLAUDE.md, .mcp.json). Useful for reloading external state or triggering side effects on config edits.

WorktreeCreate

Fires when Claude creates a new git worktree (via --worktree / -w flag or isolation: worktree in agent definitions). Useful for setting up worktree-specific resources.

WorktreeRemove

Fires when a git worktree is cleaned up after use. Useful for tearing down worktree-specific resources.

Setup

Triggered via --init, --init-only, or --maintenance CLI flags. Useful for one-time project setup tasks, plugin installation, or maintenance scripts.

PermissionRequest

Fires when Claude shows a permission prompt to the user. Useful for logging or automating permission decisions.

PreCompact

Runs before Claude Code is about to run a compact operation.

Matchers:

• manual - Invoked from /compact
• auto - Invoked from auto-compact (due to full context window)

SessionStart

Runs when Claude Code starts a new session or resumes an existing session (which currently does start a new session under the hood). Useful for loading in development context like existing issues or recent changes to your codebase.

Matchers:

• startup - Invoked from startup
• resume - Invoked from --resume, --continue, or /resume
• clear - Invoked from /clear

Hook Input

Hooks receive JSON data via stdin containing session information and event-specific data:

{
  // Common fields
  session_id: string
  transcript_path: string  // Path to conversation JSON
  cwd: string              // The current working directory when the hook is invoked

  // Event-specific fields
  hook_event_name: string
  ...
}

PreToolUse Input

The exact schema for tool_input depends on the tool.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  }
}

PostToolUse Input

The exact schema for tool_input and tool_response depends on the tool.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "success": true
  }
}

Notification Input

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Notification",
  "message": "Task completed successfully"
}

UserPromptSubmit Input

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "Write a function to calculate the factorial of a number"
}

Stop and SubagentStop Input

stop_hook_active is true when Claude Code is already continuing as a result of a stop hook. Check this value or process the transcript to prevent Claude Code from running indefinitely.

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "hook_event_name": "Stop",
  "stop_hook_active": true,
  "last_assistant_message": "I've completed all the requested changes."
}

The last_assistant_message field (v2.1.47+) contains the final text Claude produced before stopping. Useful for validating completeness or logging outcomes.

PreCompact Input

For manual, custom_instructions comes from what the user passes into /compact. For auto, custom_instructions is empty.

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": ""
}

SessionStart Input

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "hook_event_name": "SessionStart",
  "source": "startup"
}

Hook Output

There are two ways for hooks to return output back to Claude Code. The output communicates whether to block and any feedback that should be shown to Claude and the user.

Simple: Exit Code

Hooks communicate status through exit codes, stdout, and stderr:

• Exit code 0: Success. stdout is shown to the user in transcript mode (CTRL-R), except for UserPromptSubmit and SessionStart, where stdout is added to the context.
• Exit code 2: Blocking error. stderr is fed back to Claude to process automatically. See per-hook-event behavior below.
• Other exit codes: Non-blocking error. stderr is shown to the user and execution continues.

[!WARNING] Reminder: Claude Code does not see stdout if the exit code is 0, except for the UserPromptSubmit hook where stdout is injected as context.

Exit Code 2 Behavior

Advanced: JSON Output

Hooks can return structured JSON in stdout for more sophisticated control:

Common JSON Fields

All hook types can include these optional fields:

{
  "continue": true, // Whether Claude should continue after hook execution (default: true)
  "stopReason": "string" // Message shown when continue is false
  "suppressOutput": true, // Hide stdout from transcript mode (default: false)
}

If continue is false, Claude stops processing after the hooks run.

• For PreToolUse, this is different from "permissionDecision": "deny", which only blocks a specific tool call and provides automatic feedback to Claude.
• For PostToolUse, this is different from "decision": "block", which provides automated feedback to Claude.
• For UserPromptSubmit, this prevents the prompt from being processed.
• For Stop and SubagentStop, this takes precedence over any "decision": "block" output.
• In all cases, "continue" = false takes precedence over any "decision": "block" output.

stopReason accompanies continue with a reason shown to the user, not shown to Claude.

PreToolUse Decision Control

PreToolUse hooks can control whether a tool call proceeds.

• "allow" bypasses the permission system. permissionDecisionReason is shown to the user but not to Claude. (Deprecated "approve" value + reason has the same behavior.)
• "deny" prevents the tool call from executing. permissionDecisionReason is shown to Claude. ("block" value + reason has the same behavior.)
• "ask" asks the user to confirm the tool call in the UI. permissionDecisionReason is shown to the user but not to Claude.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow" | "deny" | "ask",
    "permissionDecisionReason": "My reason here (shown to user)"
  },
  "decision": "approve" | "block" | undefined, // Deprecated for PreToolUse but still supported
  "reason": "Explanation for decision" // Deprecated for PreToolUse but still supported
}

PostToolUse Decision Control

PostToolUse hooks can control whether a tool call proceeds.

• "block" automatically prompts Claude with reason.
• undefined does nothing. reason is ignored.

{
  "decision": "block" | undefined,
  "reason": "Explanation for decision"
}

UserPromptSubmit Decision Control

UserPromptSubmit hooks can control whether a user prompt is processed.

• "block" prevents the prompt from being processed. The submitted prompt is erased from context. "reason" is shown to the user but not added to context.
• undefined allows the prompt to proceed normally. "reason" is ignored.
• "hookSpecificOutput.additionalContext" adds the string to the context if not blocked.

{
  "decision": "block" | undefined,
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "My additional context here"
  }
}

Stop/SubagentStop Decision Control

Stop and SubagentStop hooks can control whether Claude must continue.

• "block" prevents Claude from stopping. You must populate reason for Claude to know how to proceed.
• undefined allows Claude to stop. reason is ignored.

{
  "decision": "block" | undefined,
  "reason": "Must be provided when Claude is blocked from stopping"
}

SessionStart Decision Control

SessionStart hooks allow you to load in context at the start of a session.

• "hookSpecificOutput.additionalContext" adds the string to the context.

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "My additional context here"
  }
}

Exit Code Example: Bash Command Validation

#!/usr/bin/env python3
import json
import re
import sys

# Define validation rules as a list of (regex pattern, message) tuples
VALIDATION_RULES = [
    (
        r"\bgrep\b(?!.*\|)",
        "Use 'rg' (ripgrep) instead of 'grep' for better performance and features",
    ),
    (
        r"\bfind\s+\S+\s+-name\b",
        "Use 'rg --files | rg pattern' or 'rg --files -g pattern' instead of 'find -name' for better performance",
    ),
]


def validate_command(command: str) -> list[str]:
    issues = []
    for pattern, message in VALIDATION_RULES:
        if re.search(pattern, command):
            issues.append(message)
    return issues


try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})
command = tool_input.get("command", "")

if tool_name != "Bash" or not command:
    sys.exit(1)

# Validate the command
issues = validate_command(command)

if issues:
    for message in issues:
        print(f"• {message}", file=sys.stderr)
    # Exit code 2 blocks tool call and shows stderr to Claude
    sys.exit(2)

JSON Output Example: UserPromptSubmit to Add Context and Validation

[!NOTE] For UserPromptSubmit hooks, you can inject context using either method:

• Exit code 0 with stdout: Claude sees the context (special case for UserPromptSubmit)
• JSON output: Provides more control over the behavior

#!/usr/bin/env python3
import json
import sys
import re
import datetime

# Load input from stdin
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

prompt = input_data.get("prompt", "")

# Check for sensitive patterns
sensitive_patterns = [
    (r"(?i)\b(password|secret|key|token)\s*[:=]", "Prompt contains potential secrets"),
]

for pattern, message in sensitive_patterns:
    if re.search(pattern, prompt):
        # Use JSON output to block with a specific reason
        output = {
            "decision": "block",
            "reason": f"Security policy violation: {message}. Please rephrase your request without sensitive information."
        }
        print(json.dumps(output))
        sys.exit(0)

# Add current time to context
context = f"Current time: {datetime.datetime.now()}"
print(context)

"""
The following is also equivalent:
print(json.dumps({
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": context,
  },
}))
"""

# Allow the prompt to proceed with the additional context
sys.exit(0)

JSON Output Example: PreToolUse with Approval

#!/usr/bin/env python3
import json
import sys

# Load input from stdin
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})

# Example: Auto-approve file reads for documentation files
if tool_name == "Read":
    file_path = tool_input.get("file_path", "")
    if file_path.endswith((".md", ".mdx", ".txt", ".json")):
        # Use JSON output to auto-approve the tool call
        output = {
            "decision": "approve",
            "reason": "Documentation file auto-approved",
            "suppressOutput": True  # Don't show in transcript mode
        }
        print(json.dumps(output))
        sys.exit(0)

# For other cases, let the normal permission flow proceed
sys.exit(0)

Working with MCP Tools

Claude Code hooks work seamlessly with Model Context Protocol (MCP) tools. When MCP servers provide tools, they appear with a special naming pattern that you can match in your hooks.

MCP Tool Naming

MCP tools follow the pattern mcp__<server>__<tool>, for example:

• mcp__memory__create_entities - Memory server's create entities tool
• mcp__filesystem__read_file - Filesystem server's read file tool
• mcp__github__search_repositories - GitHub server's search tool

Configuring Hooks for MCP Tools

You can target specific MCP tools or entire MCP servers:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
          }
        ]
      },
      {
        "matcher": "mcp__.*__write.*",
        "hooks": [
          {
            "type": "command",
            "command": "/home/user/scripts/validate-mcp-write.py"
          }
        ]
      }
    ]
  }
}

Examples

[!TIP] For practical examples including code formatting, notifications, and file protection, see More Examples in the get started guide.

Security Considerations

Disclaimer

USE AT YOUR OWN RISK: Claude Code hooks execute arbitrary shell commands on your system automatically. By using hooks, you acknowledge that:

• You are solely responsible for the commands you configure
• Hooks can modify, delete, or access any files your user account can access
• Malicious or poorly written hooks can cause data loss or system damage
• Anthropic provides no warranty and assumes no liability for any damages resulting from hook usage
• You should thoroughly test hooks in a safe environment before production use

Always review and understand any hook commands before adding them to your configuration.

Hooks Security Considerations

Here are some key practices for writing more secure hooks:

1. Validate and sanitize inputs - Never trust input data blindly
2. Always quote shell variables - Use "$VAR" not $VAR
3. Block path traversal - Check for .. in file paths
4. Use absolute paths - Specify full paths for scripts (use $CLAUDE_PROJECT_DIR for the project path)
5. Skip sensitive files - Avoid .env, .git/, keys, etc.

Configuration Safety

Direct edits to hooks in settings files don't take effect immediately. Claude Code:

1. Captures a snapshot of hooks at startup
2. Uses this snapshot throughout the session
3. Warns if hooks are modified externally
4. Requires review in /hooks menu for changes to apply

This prevents malicious hook modifications from affecting your current session.

Hook Execution Details

• Timeout: 60-second execution limit by default, configurable per command.
  • A timeout for an individual command does not affect the other commands.
• Parallelization: All matching hooks run in parallel
• Environment: Runs in current directory with Claude Code's environment
  • The CLAUDE_PROJECT_DIR environment variable is available and contains the absolute path to the project root directory
• Input: JSON via stdin
• Output:
  • PreToolUse/PostToolUse/Stop: Progress shown in transcript (Ctrl-R)
  • Notification: Logged to debug only (--debug)

Debugging

Basic Troubleshooting

If your hooks aren't working:

1. Check configuration - Run /hooks to see if your hook is registered
2. Verify syntax - Ensure your JSON settings are valid
3. Test commands - Run hook commands manually first
4. Check permissions - Make sure scripts are executable
5. Review logs - Use claude --debug to see hook execution details

Common issues:

• Quotes not escaped - Use \" inside JSON strings
• Wrong matcher - Check tool names match exactly (case-sensitive)
• Command not found - Use full paths for scripts

Advanced Debugging

For complex hook issues:

1. Inspect hook execution - Use claude --debug to see detailed hook execution
2. Validate JSON schemas - Test hook input/output with external tools
3. Check environment variables - Verify Claude Code's environment is correct
4. Test edge cases - Try hooks with unusual file paths or inputs
5. Monitor system resources - Check for resource exhaustion during hook execution
6. Use structured logging - Implement logging in your hook scripts

Debug Output Example

Use claude --debug to see hook execution details:

[DEBUG] Executing hooks for PostToolUse:Write
[DEBUG] Getting matching hook commands for PostToolUse with query: Write
[DEBUG] Found 1 hook matchers in settings
[DEBUG] Matched 1 hooks for query "Write"
[DEBUG] Found 1 hook commands to execute
[DEBUG] Executing hook command: <Your command> with timeout 60000ms
[DEBUG] Hook command completed with status 0: <Your stdout>

Progress messages appear in transcript mode (Ctrl-R) showing:

• Which hook is running
• Command being executed
• Success/failure status
• Output or error messages

Security & Permissions

Tool Permission Patterns

# Allow specific tools (read/edit files)
claude --allowedTools "Edit,Read"

# Allow tool categories incl. Bash (but still scoped below)
claude --allowedTools "Edit,Read,Bash"

# Scoped permissions (all git commands)
claude --allowedTools "Bash(git:*)"

# Multiple scopes (git + npm)
claude --allowedTools "Bash(git:*),Bash(npm:*)"

Dangerous Mode

[!Warning] NEVER use in Production systems, shared machines, or any systems with important data Only use with isolated environments like a Docker container, using this mode can cause data loss and comprimise your system!

claude --dangerously-skip-permissions

Automation & Integration

Automation & Scripting with Claude Code

GitHub Actions you can copy/paste :p

1. Install the Claude GitHub App on your org/repo (required for Actions to comment on PRs/issues).
2. In your repo, add a secret ANTHROPIC_API_KEY Settings → Secrets and variables → Actions → New repository secret
3. Copy the workflows below into .github/workflows/.
4. Open a test PR (or a new issue) to see them run.

[!TIP] Pin Actions to a release tag (e.g. @v1) when you adopt them long‑term. The snippets below use branch tags for readability.

Auto PR Review (inline comments)

Creates a structured review (with inline comments) as soon as a PR opens or updates.

File: .github/workflows/claude-pr-auto-review.yml

name: Auto review PRs
on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

permissions:
  contents: read
  pull-requests: write

jobs:
  auto-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Claude PR review
        uses: anthropics/claude-code-action@main
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # Claude will fetch the diff and leave inline comments
          direct_prompt: |
            Review this pull request’s diff for correctness, readability, testing, performance, and DX.
            Prefer specific, actionable suggestions. Use inline comments where relevant.
          # GitHub tools permitted during the run:
          allowed_tools: >-
            mcp__github__get_pull_request_diff,
            mcp__github__create_pending_pull_request_review,
            mcp__github__add_comment_to_pending_review,
            mcp__github__submit_pending_pull_request_review

Security Review on Every PR

Runs a focused security scan and comments findings directly on the PR.

File: .github/workflows/claude-security-review.yml

name: Security Review
on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
          fetch-depth: 2

      - name: Claude Code Security Review
        uses: anthropics/claude-code-security-review@main
        with:
          claude-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          comment-pr: true
          # Optional:
          # exclude-directories: "docs,examples"
          # claudecode-timeout: "20"
          # claude-model: "claude-sonnet-4-6-20260217"

Issue Triage (suggest labels & severity)

When a new issue opens, Claude proposes labels/severity and posts a tidy triage comment. You can enable auto‑apply labels by flipping a single flag

File: .github/workflows/claude-issue-triage.yml

name: Claude Issue Triage
on:
  issues:
    types: [opened, edited, reopened]

permissions:
  contents: read
  issues: write

jobs:
  triage:
    runs-on: ubuntu-latest
    env:
      CLAUDE_MODEL: claude-sonnet-4-6-20260217
    steps:
      - name: Collect context & similar issues
        id: gather
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          TITLE="${{ github.event.issue.title }}"
          BODY="${{ github.event.issue.body }}"
          # naive similar search by title words
          Q=$(echo "$TITLE" | tr -dc '[:alnum:] ' | awk '{print $1" "$2" "$3" "$4}')
          gh api -X GET search/issues -f q="repo:${{ github.repository }} is:issue $Q" -f per_page=5 > similars.json
          echo "$TITLE" > title.txt
          echo "$BODY" > body.txt

      - name: Ask Claude for triage JSON
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          cat > payload.json << 'JSON'
          {
            "model": "${{ env.CLAUDE_MODEL }}",
            "max_tokens": 1500,
            "system": "You are a pragmatic triage engineer. Be specific, cautious with duplicates.",
            "messages": [{
              "role": "user",
              "content": [{
                "type":"text",
                "text":"Given the issue and similar candidates, produce STRICT JSON with keys: labels (array of strings), severity (one of: low, medium, high, critical), duplicate_url (string or empty), comment_markdown (string brief). Do not include any extra keys."
              },
              {"type":"text","text":"Issue title:\n"},
              {"type":"text","text": (include from file) },
              {"type":"text","text":"\n\nIssue body:\n"},
              {"type":"text","text": (include from file) },
              {"type":"text","text":"\n\nSimilar issues (JSON):\n"},
              {"type":"text","text": (include from file) }]
            }]
          }
          JSON
          # Inject files safely
          jq --arg title "$(cat title.txt)" '.messages[0].content[2].text = $title' payload.json \
          | jq --arg body "$(cat body.txt)" '.messages[0].content[4].text = $body' \
          | jq --arg sims "$(cat similars.json)" '.messages[0].content[6].text = $sims' > payload.final.json

          curl -s https://api.anthropic.com/v1/messages \
            -H "x-api-key: $ANTHROPIC_API_KEY" \
            -H "anthropic-version: 2023-06-01" \
            -H "content-type: application/json" \
            -d @payload.final.json > out.json
          jq -r '.content[0].text' out.json > triage.json || echo '{}' > triage.json
          # Validate JSON to avoid posting garbage
          jq -e . triage.json >/dev/null 2>&1 || echo '{"labels":[],"severity":"low","duplicate_url":"","comment_markdown":"(triage failed to parse)"}' > triage.json

      - name: Apply labels (optional)
        if: ${{ false }} # flip to `true` to auto-apply labels
        uses: actions/github-script@v7
        with:
          script: |
            const triage = JSON.parse(require('fs').readFileSync('triage.json','utf8'))
            if (triage.labels?.length) {
              await github.rest.issues.addLabels({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: context.issue.number,
                labels: triage.labels
              })
            }

      - name: Post triage comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs')
            const triage = JSON.parse(fs.readFileSync('triage.json','utf8'))
            const md = `### 🤖 Triage
            - **Suggested labels:** ${triage.labels?.join(', ') || '—'}
            - **Severity:** ${triage.severity || '—'}
            ${triage.duplicate_url ? `- **Possible duplicate:** ${triage.duplicate_url}\n` : ''}
            ---
            ${triage.comment_markdown || ''}`
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: md
            })

[!NOTE] The triage workflow posts a suggestion comment by default. Flip the Apply labels step to true if you want labels applied automatically.

Configuration & Customization

• Model selection: set CLAUDE_MODEL (e.g., claude-sonnet-4-6-20260217) where shown.
• Secrets: ANTHROPIC_API_KEY is required. The built‑in GITHUB_TOKEN is sufficient for posting comments and applying labels.
• Permissions: each workflow declares the least privileges it needs (pull-requests: write and/or issues: write). Adjust only if your org requires stricter policies.
• Scope: use paths: filters on triggers to limit when workflows run (e.g., only for /src or exclude /docs).

Troubleshooting

Check the Actions logs first—most issues are missing secrets/permissions or a mis‑indented YAML block.

• No comments appear on PRs: Verify the Claude GitHub App is installed and the workflow has pull-requests: write permission.
• 403 when applying labels: Ensure the job or step has issues: write. The default GITHUB_TOKEN must have access to this repo.
• Anthropic API errors: Confirm ANTHROPIC_API_KEY is set at repository (or org) level and not expired.
• “YAML not well‑formed”: Validate spacing—two spaces per nesting level; no tabs.

Help & Troubleshooting

[!TIP] Q:claude not found, but npx claude works?

A: Your PATH is missing the npm global bin. See the PATH issue section for Windows or Linux

Q: Which Node.js version do I need?

A: Node.js 18+ (ideally 20+). Check with node --version.

Q: Where do I see logs

A: Run claude doctor and claude --verbose the diagnostic window will point to log locations.

Q: Do I need to reboot after editing PATH?

A: No reboot required, but you must open a new terminal window.

C:\Users\<you>\AppData\Roaming\npm
C:\Program Files\nodejs</kbd>

C:\Users\<you>\.claude\local\bin
C:\Users\<you>\.local\bin

where claude
claude doctor

node --version

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

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

echo $env:ANTHROPIC_API_KEY
claude -p "test" --verbose

echo $ANTHROPIC_API_KEY
claude -p "test" --verbose

claude config get allowedTools

claude config set allowedTools "[]"

claude config set allowedTools '["Edit","View"]'

claude --debug

claude mcp list
claude mcp remove <server-name>

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

Remove-Item -LiteralPath "$env:USERPROFILE\AppData\Roaming\npm\claude*" -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath "$env:USERPROFILE\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code" -Recurse -Force -ErrorAction SilentlyContinue

Remove-Item -LiteralPath "$env:USERPROFILE\.claude\downloads\*" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath "$env:USERPROFILE\.claude\local\bin\claude.exe" -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath "$env:USERPROFILE\.claude\local" -Recurse -Force -ErrorAction SilentlyContinue

Remove-Item -LiteralPath "$env:USERPROFILE\.claude.json" -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath "$env:USERPROFILE\.claude" -Recurse -Force -ErrorAction SilentlyContinue

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

Write-Host "`n=== Node & npm ==="; node --version; npm --version
Write-Host "`n=== Where is claude? ==="; where claude
Write-Host "`n=== Try doctor ==="; try { claude doctor } catch { Write-Host "claude not on PATH" }
Write-Host "`n=== API key set? ==="; if ($env:ANTHROPIC_API_KEY) { "Yes" } else { "No" }

echo "=== Node & npm ==="; node --version; npm --version
echo "=== Where is claude? ==="; which claude || echo "claude not on PATH"
echo "=== Try doctor ==="; claude doctor || true
echo "=== API key set? ==="; [ -n "$ANTHROPIC_API_KEY" ] && echo Yes || echo No

Best Practices

Curated guidance for safe, fast, and correct use of the Claude Code CLI and interactive REPL. All commands and flags here match the current Anthropic docs as of Feb 28, 2026.

Effective Prompting

# Good: Specific and detailed
claude "Review UserAuth.js for security vulnerabilities, focusing on JWT handling"

# Bad: Vague
claude "check my code"

Tip: claude "query" starts the interactive REPL pre-seeded with your prompt; claude -p "query" runs print mode (non‑interactive) and exits.

Security Best Practices

1. Start with minimal permissions

   • Prefer explicit allows and denies, either on the CLI or in settings files.

   # Allow only what you need for this run
   claude --allowedTools "Read" "Grep" "LS" "Bash(npm run test:*)"
   

   Or commit a project policy at .claude/settings.json:

   {
     "permissions": {
       "allow": ["Read", "Grep", "LS", "Bash(npm run test:*)"],
       "deny": [
         "WebFetch",
         "Bash(curl:*)",
         "Read(./.env)",
         "Read(./secrets/**)"
       ]
     }
   }
   

2. Handle secrets correctly

   • Use environment variables for SDK/automation flows:

   export ANTHROPIC_API_KEY="your_key"   # for SDK/print mode
   

   • In the interactive REPL, prefer /login instead of hard‑coding tokens.
   • Deny access to sensitive files in settings (replaces older ignorePatterns):

   {
     "permissions": {
       "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
     }
   }
   

3. Audit permissions regularly

   # Project settings
   claude config list
   claude config get permissions.allow
   claude config get permissions.deny
   
   # Global settings
   claude config list -g
   

4. Avoid bypass modes in production

   • Do not use --dangerously-skip-permissions outside isolated/dev sandboxes.
   • For unattended runs, combine narrow --allowedTools with --disallowedTools and project settings.

Performance Tips

1. Use machine‑readable output in automations

   claude -p "summarize this error log" --output-format json
   # valid: text | json | stream-json
   

2. Bound non‑interactive work

   claude -p "run type checks and summarize failures" --max-turns 3
   # optionally also bound thinking:
   export MAX_THINKING_TOKENS=20000
   

3. Keep sessions tidy

   # Retain recent sessions only (default is 30 days)
   claude config set -g cleanupPeriodDays 20
   

4. Limit context scope

   # Grant access only to relevant paths to reduce scanning/noise
   claude --add-dir ./services/api ./packages/ui
   

5. Pick the right model

   • CLI aliases: --model sonnet or --model opus (latest of that family).
   • As of Feb 2026, Sonnet 4.6 is the default Sonnet — frontier performance at Sonnet pricing with a 1M-token context window.
   • For reproducibility in settings, pin a full model ID (e.g., "claude-sonnet-4-6-20260217").

Monitoring & Alerting

1) Health checks Use the built‑in doctor command to verify installation and environment.

# Every 15 minutes
*/15 * * * * /usr/local/bin/claude doctor >/dev/null 2>&1 || \
mail -s "Claude Code doctor failed" admin@company.com </dev/null

2) Log analysis batch job

# Daily analysis with non-interactive JSON output (print mode)
0 6 * * * tail -1000 /var/log/app.log | \
claude -p "Analyze errors, regressions, and suspect patterns; output JSON." \
--output-format json > /tmp/daily-analysis.json

3) Telemetry (optional) Claude Code emits OpenTelemetry metrics/events. Set exporters in settings/env (e.g., OTLP) and ship to your observability stack (Datadog, Honeycomb, Prometheus/Grafana, etc.).

Collaboration Best Practices

Team Workflows

1) Share versioned configuration

// .claude/settings.json (checked into the repo)
{
  "permissions": {
    "allow": [
      "Read",
      "Grep",
      "LS",
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
    ],
    "deny": [
      "WebFetch",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
    ],
  },
  // Pin a model here for reproducibility if desired, using a full model ID:
  "model": "claude-sonnet-4-6-20260217",
}

2) Documentation automation

# Update docs with explicit tasks
claude "Update README.md to reflect the latest API endpoints and examples."
claude "Generate TypeScript types from schema.prisma and write to /types."

3) Code review standards

# Review a local diff with constrained tools
git fetch origin main
git diff origin/main...HEAD > /tmp/diff.patch
claude --allowedTools "Read" "Grep" "Bash(git:*)" \
  "Review /tmp/diff.patch using team standards:
   - Security best practices
   - Performance considerations
   - Code style compliance
   - Test coverage adequacy"

Knowledge Sharing

1) Project runbooks

claude "Create a deployment runbook for this app: steps, checks, rollback."
claude "Document onboarding for new developers: setup, commands, conventions."

2) Architecture docs

claude "Update architecture docs to reflect new microservices."
claude "Create sequence diagrams for the authentication flow."

Tip: Keep durable context in CLAUDE.md at the project root. In the REPL, use /memory to manage it and @path to import file content into prompts.

Common Pitfalls to Avoid

Security

❌ Don’t

• Use --dangerously-skip-permissions on production systems
• Hard‑code secrets in commands/config
• Grant overly broad permissions (e.g., Bash(*))
• Run with elevated privileges unnecessarily

✅ Do

• Store secrets in env vars and credential helpers
• Start from minimal permissions.allow and expand gradually
• Audit with claude config list / claude config get
• Isolate risky operations in containers/VMs

Performance

❌ Don’t

• Load an entire monorepo when you only need a package
• Max out thinking/turn budgets for simple tasks
• Ignore session cleanup

✅ Do

• Use --add-dir for focused context
• Right‑size with --max-turns and MAX_THINKING_TOKENS
• Set cleanupPeriodDays to prune old sessions

Workflow

❌ Don’t

• Skip project context (CLAUDE.md)
• Use vague prompts
• Ignore errors/logs
• Automate without testing

✅ Do

• Maintain and update CLAUDE.md
• Be specific and goal‑oriented in prompts
• Monitor via logs/OTel as appropriate
• Test automation in safe environments first

Third-Party Integrations

DeepSeek Integration

1. Have claude Code installed

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

2. Config Environment Variables

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=${YOUR_API_KEY}
export ANTHROPIC_MODEL=deepseek-chat
export ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat

3. Now all you need to do is launch claude

Find more information from the Official Deepseek Docs