Contents

Fast paths: Install · Commands · Config · MCP · Agents · Troubleshoot

Getting Started

Enable sound alerts when claude completes the task:

claude config set --global preferredNotifChannel terminal_bell

Quick Start

# 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) — useful when your environment already standardizes on Node.js
# 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          */ Open the agent/session dashboard
/*claude update          */ Run a manual update check

System Requirements

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

• Hardware: 4GB RAM minimum 8GB+ recommended

• Software: Git 2.23+ is optional for PR/worktree workflows. Node.js 18+ is only required for npm-based installation; the native installer bundles its own runtime.

• Internet: Connection for API calls

Initial Setup

# Universal
/* Authenticate via Anthropic account     */ claude auth login
/* Authenticate via Console/API billing   */ claude auth login --console
/* Switch accounts inside Claude          */ /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.

# 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="sonnet"                                  # Custom model name or alias to use
export ANTHROPIC_DEFAULT_SONNET_MODEL="sonnet"                   # Default Sonnet alias or pinned Sonnet model ID
export ANTHROPIC_DEFAULT_OPUS_MODEL="opus"                       # Default Opus alias or pinned Opus model ID
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                         # Force BashTool to skip login shell startup files
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 the 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

# Vertex AI region overrides follow VERTEX_REGION_CLAUDE_<MODEL_FAMILY>.
export VERTEX_REGION_CLAUDE_3_5_HAIKU="REGION"        # 3.x family example
export VERTEX_REGION_CLAUDE_4_6_SONNET="REGION"       # Sonnet family example
export VERTEX_REGION_CLAUDE_4_8_OPUS="REGION"         # Opus family example

# -- Session and runtime controls ---------------------------------------------
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)

# -- Provider, terminal, and telemetry controls --------------------------------
export CLAUDE_CODE_ENABLE_AUTO_MODE=1                  # Enable auto mode on Bedrock, Vertex, and Foundry for Opus 4.7/4.8
export CLAUDE_CODE_USE_POWERSHELL_TOOL=1               # Enable PowerShell tool where available; Windows provider sessions may default to it
export CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1 # Opt out of PowerShell -ExecutionPolicy Bypass behavior
export CLAUDE_CODE_NO_FLICKER=1                        # Prefer flicker-free alternate-screen rendering where supported
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1    # Let compatible gateways populate the model picker from /v1/models
export CLAUDE_CODE_FORCE_SYNC_OUTPUT=1                 # Force synchronized terminal output when auto-detection misses support
export CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1       # Let package-manager installs run background upgrades where supported
export ENABLE_PROMPT_CACHING_1H=true                   # Opt in to 1-hour prompt cache TTL when your provider supports it
export OTEL_LOG_TOOL_DETAILS=1                         # Include tool parameters in tool_decision telemetry events
export OTEL_METRICS_INCLUDE_ENTRYPOINT=true            # Include session entrypoint on OpenTelemetry metrics

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 "sonnet"                          # Default model override; use a full model ID only when pinning
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

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

Claude can save useful working context during your sessions, such as project conventions, tooling preferences, and architectural decisions it observes while helping you. Use /memory to inspect, edit, or remove saved memories.

Auto-memory is most useful for context you would otherwise repeat across sessions:

• Preferred build, test, and lint commands
• Local conventions that are not obvious from code alone
• Architecture decisions that influence future edits
• Team preferences that should shape how Claude proposes changes

Keep durable team rules in CLAUDE.md or .claude/rules/. Treat auto-memory as helpful working context, not as the only source of truth.

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

# Start and resume

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
claude -r "<session-id>" "finish this" # Resume by ID or name
claude --model sonnet # Pick the Sonnet alias for this run
claude --model opus # Pick the Opus alias for harder tasks

# Install, update, and auth

claude update # Manually update Claude Code
claude doctor # Diagnose install/version & setup
claude install # Start the native binary installer
claude migrate-installer # Switch from global npm to the native installer
claude auth login # Log in to your Anthropic account
claude auth status # Check authentication status
claude auth logout # Log out

# Background and remote sessions

claude agents # Open the live session dashboard: running, blocked, completed
claude agents --json # Scriptable JSON list of live/background sessions
claude --bg "run the integration suite and summarize failures" # Start a background session
claude --bg --exec "npm test" # Run a shell command as an attachable background session
claude remote-control # Start remote-control mode for external tooling
claude --remote "Fix the bug" # Create web session on claude.ai
claude --teleport # Resume web session locally

# Config essentials

claude config # Interactive config wizard
claude config set model "sonnet" # Override default model for this project
claude config set attribution false # Disable "co-authored-by Claude" byline in git/PRs
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 worktree.baseRef "head" # Use local HEAD instead of origin/default for new worktrees
claude config set -g autoUpdates false # Turn off automatic updates globally
claude config set -g theme dark # Theme: dark | light | light-daltonized | dark-daltonized

# MCP essentials

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 add <name> <command> [args...] # Add local stdio server
claude mcp add --transport http <name> <url> # Add remote HTTP server
claude mcp reset-project-choices # Reset approvals for project .mcp.json servers
claude mcp serve # Run Claude Code itself as an MCP stdio server

# High-value flags

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 -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 --json-schema '{"type":"object"}' -p "query" # Get validated JSON output
claude --chrome # Enable Chrome browser integration
claude --agent code-reviewer # Run this session with a named agent
claude ultrareview 123 --json # Non-interactive comprehensive review for PR/target 123

# Slash shortcuts

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
/branch experiment-name # Branch the current conversation
/goal "all tests pass and README is updated" # Keep working until the completion condition is met
/loop 30m "check deploy health and summarize anomalies" # Schedule recurring work
/workflows # View dynamic workflows and background orchestration

# Notes: project scope is default for 'claude config'; use -g/--global for user-global settings.
# Settings precedence: Enterprise > CLI args > local project > shared project > user (~/.claude).

Interface & Input

Keyboard Shortcuts

Text Editing

Multiline Input

Quick Commands

Vim Mode

Vim Mode Switching

Vim Navigation

Vim Editing

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

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

Effort Levels

Use /effort to tune how much reasoning the selected model applies before answering. Higher effort levels are best for planning-heavy work, deep reviews, and long-context tasks.

/effort            # Open the effort picker
/effort low        # Faster, lighter reasoning
/effort medium     # Balanced default for many tasks
/effort high       # Deeper planning and review
/effort xhigh      # Highest effort for Opus 4.8-scale hard tasks

Prefer the lowest effort that still solves the task: higher effort can improve planning, code review, and long-context reasoning, but it usually increases latency and token usage.

Fast Mode

How to enable Fast Mode:

# Enable usage credits if your plan requires it, then toggle fast mode
/usage-credits
/fast

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

Key features:

• Faster responses - Reduced latency for quick tasks
• Opus support - Use with Opus models where fast mode is available
• Usage credits - Some plans require /usage-credits before /fast
• Visible state - The status bar and IDE indicators show when Fast Mode is active

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.

Auto Mode

Auto mode lets Claude evaluate and approve lower-risk actions automatically while still blocking or asking on higher-risk operations. It is useful for trusted development loops where repeated permission prompts slow down work.

# Enable auto mode for Bedrock, Vertex, and Foundry Opus 4.7/4.8 sessions
export CLAUDE_CODE_ENABLE_AUTO_MODE=1

{
  "autoMode": {
    "allow": ["$defaults"],
    "soft_deny": ["$defaults"],
    "hard_deny": []
  }
}

Key points:

• Enable auto mode through environment and settings so the policy is visible and repeatable.
• Use "$defaults" in autoMode.allow, autoMode.soft_deny, or autoMode.environment to add rules without replacing built-ins.
• settings.autoMode.hard_deny blocks actions unconditionally regardless of user intent.
• Denied actions can appear in /permissions recent activity, where supported, so you can retry or adjust policy.

Plan Mode

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

How to use background tasks:

Key features:

• Output is buffered and can be read from the persisted background output file path
• Background tasks have unique IDs for tracking and output retrieval
• Background sessions appear in /resume and the claude agents dashboard, marked with bg
• Use /tasks to list and manage background tasks
• Use claude agents --json for scripts, status bars, session pickers, and tmux integrations

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

# Run a command as an attachable background session
claude --bg --exec "npm test"

# Name a background session
claude --bg --name nightly-check "run the full verification suite"

Disable background tasks:

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

Workflows & Scheduling

Dynamic workflows coordinate many background agents for larger work than a single foreground turn can comfortably handle. Ask Claude to create a workflow, then use /workflows to inspect runs and status.

/workflows
/goal "the migration is implemented, tested, and documented"
/loop 15m "check the deployment dashboard and summarize any incidents"

Use workflows for broad, decomposable efforts. Use /goal for a single outcome that may require several turns. Use /loop for monitoring and scheduled checks.

Remote Sessions

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

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

claude update
/agents
claude agents
claude agents --json

claude agents shows running, blocked, completed, and background sessions in one place. It can launch new sessions, attach to background work, and script session lists with --json.

Subagent Scopes

Dispatched sessions honor the agent field in settings.json. Pass --agent <name> to override the configured default for a specific run.

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.

Background and isolated agents can switch between Claude-managed worktrees with EnterWorktree when the session needs to move between related isolated checkouts.

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)

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)

Skill Locations

Project skills override personal skills with the same name. Files in .claude/commands/ still work and support the same frontmatter. Plugins in .claude/skills directories are automatically loaded; use /reload-skills to re-scan skill directories without restarting the session.

Create a Skill

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

# Scaffold a plugin-backed skill in the current project
claude plugin init 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

Key commands:

claude plugin init my-plugin
/plugins install @org/claude-code-plugin
/plugins list
/plugins enable <plugin-name>
/plugins disable <plugin-name>
/plugins validate ./my-plugin
/plugins marketplace

# CLI aliases exist for scripting, for example:
claude plugin install https://github.com/org/claude-plugin-example

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",
  "defaultEnabled": false,
  "agents": ["agents/"],
  "skills": ["skills/"],
  "hooks": "hooks/hooks.json",
  "mcpServers": "mcp-servers/servers.json",
  "dependencies": ["required-plugin"]
}

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. Git/GitHub marketplace sources can use skipLfs to skip Git LFS downloads during clone and update.

Dependency behavior:

• claude plugin enable enables transitive dependencies automatically.
• claude plugin disable refuses when another enabled plugin depends on the target and reports the disable chain.
• defaultEnabled: false lets a plugin ship installed but disabled until the user explicitly enables it.

Worktree Isolation

Usage:

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

# Choose whether new worktrees branch from origin/default or local HEAD
claude config set worktree.baseRef "fresh" # default, uses origin/<default>
claude config set worktree.baseRef "head"  # use current local HEAD

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

For repositories where worktrees are impractical, worktree.bgIsolation: "none" lets background sessions edit the working copy directly without EnterWorktree.

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

# Start the native installer (interactive)
claude install

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

The npm installation method (npm install -g @anthropic-ai/claude-code) continues to work. Choose the installer that best fits your environment and automation model.

Authentication CLI

# Log in to your Anthropic account
claude auth login

# Check current authentication status
claude auth status

# Log out
claude auth logout

Agent Management CLI

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

# Script live sessions for status bars, session pickers, or tmux integrations
claude agents --json

# Dispatch with a specific agent, overriding settings.json for this run
claude --agent code-reviewer "review the current branch"

Remote Control

# 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

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

Model Guidance

Key highlights:

• Opus 4.8: highest-effort Opus path, with xhigh effort and fast mode support.
• Opus 4.7/4.8 on providers: Bedrock, Vertex, and Foundry support auto mode opt-in with CLAUDE_CODE_ENABLE_AUTO_MODE=1.
• Sonnet: use the sonnet alias for balanced coding, planning, and refactoring.
• Haiku/small-fast models: use ANTHROPIC_SMALL_FAST_MODEL overrides for background naming and side-query paths when needed.
• Gateway discovery: set CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 to populate compatible gateway model pickers from /v1/models.

Use in Claude Code:

# Set by family alias
claude --model sonnet
claude --model opus

# Configure in settings with aliases
claude config set model "sonnet"

# Pin only when you need exact reproducibility
claude --model <full-model-id>

Model selection tips:

• Use family aliases in general examples so shared docs age well.
• Pin full model IDs only in workflows that need reproducible model behavior.
• Teach /model and /fast for day-to-day model switching instead of provider-specific overrides.

Theming & Customization

Claude Code supports built-in themes, custom named themes, and session accent colors.

/theme          # Pick a theme or create a custom one
/color          # Pick a session accent color
/color random   # Randomize session accent color

Custom themes can be edited as JSON under ~/.claude/themes/, and plugins can ship themes for teams. The Auto (match terminal) theme follows terminal light/dark mode where supported.

Code Review

Claude Code has separate review paths for correctness, cleanup, and broader branch-level review.

Use /code-review for local correctness review, /simplify for cleanup, and /ultrareview when you want a broader cloud review of a branch or PR.

Claude Code Insights

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 behavior to know:

• MCP servers are available in more headless claude -p workflows, so automation can use configured tools without opening the full REPL.
• Remote OAuth and claude.ai connector flows have improved reconnect and refresh handling; use /mcp to reconnect after changing .mcp.json.
• Large MCP tool results can be persisted or capped by server annotations, reducing context blowups for large outputs.
• Tool names still follow the mcp__server__tool pattern for permissions and hooks.

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
• Configure with the -s user flag
• Suitable for: Common tools like file systems, database clients

3. Project Scope (Team shared)

• Shared through .mcp.json file
• Configure with the -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 the web for outside 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: If the server response is missing a protocol version, try these checks:

1. Use wrapper scripts
2. Ensure MCP server returns correct protocol version
3. Run claude update and retry

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.

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",
            "args": ["--flag", "value"]
          }
        ]
      }
    ]
  }
}

HTTP Hooks

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)
  • command: The bash command to execute (can use $CLAUDE_PROJECT_DIR environment variable)
  • args: Optional exec-form arguments for command hooks, avoiding shell quoting issues
  • 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. Set continueOnBlock: true in hook config when you want a PostToolUse block reason to be fed back to Claude and allow the turn to continue.

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.

PermissionDenied

Fires after an auto mode classifier denial. Hooks can return { "retry": true } when the model should retry with the denial feedback.

MessageDisplay

Runs as assistant message text is displayed, allowing hooks to transform or hide displayed assistant content.

PostCompact

Runs after a compaction operation completes.

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 session or resumes one. Useful for loading 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

SessionStart hooks can also request reloadSkills: true and set hookSpecificOutput.sessionTitle, making newly installed skills available immediately and naming startup/resume sessions.

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

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, // Legacy PreToolUse field; prefer permissionDecision
  "reason": "Explanation for decision" // Legacy PreToolUse field; prefer permissionDecisionReason
}

PostToolUse Decision Control

PostToolUse hooks can control whether a tool call proceeds.

• "block" automatically prompts Claude with reason.
• continueOnBlock: true in the hook configuration feeds the block reason back while allowing Claude to continue the same turn.
• 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.sessionTitle" sets the session title on startup/resume.
• "reloadSkills": true re-scans skill directories after the hook finishes.

{
  "reloadSkills": true,
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "My additional context here",
    "sessionTitle": "Focused refactor"
  }
}

Terminal Sequence Output

Hooks can return terminalSequence to emit desktop notifications, window titles, or bells without needing direct terminal access.

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

#!/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

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

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.

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: "sonnet"

Issue Triage (suggest labels & severity)

When an 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: sonnet
    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
            })

Help & Troubleshooting

claude                  # Open Claude UI (if on PATH)
claude --version        # Show CLI version (e.g., 1.0.xx)
claude update           # Update the CLI (if supported)

claude doctor           # Open diagnostic / debug window

claude --debug          # Launch claude with diagnostics
claude --verbose        # Verbose logging

where claude            # Windows (cmd)
which claude            # macOS/Linux (bash/zsh)

npm bin -g              # Linux Verify your global bin path
npm prefix -g           # Windows Verify your global bin path

set PATH=%USERPROFILE%\AppData\Roaming\npm;C:\Program Files\nodejs;%PATH%
where claude
claude --debug

$env:Path = "$env:USERPROFILE\AppData\Roaming\npm;C:\Program Files\nodejs;$env:Path"
where claude
claude --debug

export PATH="$(npm config get prefix)/bin:$HOME/.local/bin:$PATH"
which claude
claude doctor

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

"%USERPROFILE%\AppData\Roaming\npm\claude.cmd" --version
"%USERPROFILE%\AppData\Roaming\npm\claude.cmd" doctor

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

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.