Claude Code CLI 指南：安装、配置、命令、环境变量

# 1. Install (pick one)
npm install -g @anthropic-ai/claude-code          # npm users
brew install anthropic/claude/claude              # macOS + Homebrew
curl -sL claude.ai/install.sh | sh                # native installer

# 2. Launch in any project directory
cd ~/your-project && claude

# 3. Authenticate (browser opens automatically on first run)
/login

# 4. Ask your first question
> What does this repo do? Read the key files and summarize.

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

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

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

# Homebrew alternative
brew install --cask claude-code

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

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

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

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

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

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

claude install

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

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

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

# Amazon Bedrock via Mantle (v2.1.94+)
export CLAUDE_CODE_USE_MANTLE=1

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

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

claude doctor

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

claude auth logout && claude auth login

export DISABLE_AUTOUPDATER=1

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

claude update

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

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

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

claude                           # Launch in current directory

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

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

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

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

cd your-project
claude

claude "explain the authentication flow in this project"

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

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

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

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

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

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

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

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

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

# Bare mode: skip hooks, LSP, plugin sync, skill walks (v2.1.81+)
claude -p "count files" --bare

# Channel permission relay: send approval prompts to Telegram/Discord (v2.1.81+)
claude --channels

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

# Continue most recent session
claude -c

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

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

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

claude --from-pr 123                                                # GitHub PR number (assumes current repo's remote)
claude --from-pr https://github.com/org/repo/pull/123               # GitHub URL
claude --from-pr https://gitlab.com/org/repo/-/merge_requests/45    # GitLab MR (v2.1.119+)
claude --from-pr https://bitbucket.org/org/repo/pull-requests/67    # Bitbucket PR (v2.1.119+)
claude --from-pr https://ghe.example.com/org/repo/pull/89           # GitHub Enterprise (v2.1.119+)

# Name session at startup (v2.1.76+)
claude -n "auth-refactor"                  # --name flag sets display name[^125]

# Name current session
> /rename auth-refactor

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

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

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

# Or use the /plan command with an optional description (v2.1.72+)
/plan                                     # Enter plan mode
/plan refactor the auth module            # Enter plan mode with a description

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

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

ANTHROPIC_API_KEY=sk-ant-...                    # 直接 API 身份验证
ANTHROPIC_AUTH_TOKEN=token                      # 自定义授权请求头
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # 额外的请求头

ANTHROPIC_MODEL=claude-opus-4-7                 # 覆盖默认模型(2026年4月16日)
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7    # Opus 4.7(Max/Team Premium 默认)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # 子代理使用的模型
MAX_THINKING_TOKENS=10000                       # (仅限 Opus 4.6 和 Sonnet 4.6 — 在 Opus 4.7 中已移除)
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # 限制输出长度
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1          # 启用代理团队(v2.1.32+)

CLAUDE_CODE_USE_BEDROCK=1                       # 使用 AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1                        # 使用 Google Vertex AI
CLAUDE_CODE_USE_FOUNDRY=1                       # 使用 Microsoft Foundry
ANTHROPIC_BEDROCK_BASE_URL=https://...          # 自定义 Bedrock 端点
ANTHROPIC_BEDROCK_SERVICE_TIER=priority         # Bedrock 服务等级(v2.1.122+):'default'、'flex' 或 'priority';作为 X-Amzn-Bedrock-Service-Tier 请求头发送[^162]
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # 跳过 Bedrock 身份验证(用于网关)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # 跳过 Vertex 身份验证
AWS_BEARER_TOKEN_BEDROCK=token                  # Bedrock bearer 令牌
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # 覆盖 Vertex 区域

DISABLE_AUTOUPDATER=1                           # 阻止后台自动更新
DISABLE_UPDATES=1                               # 阻止所有更新路径,包括手动 `claude update`(v2.1.118+,比 DISABLE_AUTOUPDATER 更严格)[^160]
DISABLE_TELEMETRY=1                             # 退出使用情况遥测
DISABLE_ERROR_REPORTING=1                       # 禁用 Sentry
DISABLE_BUG_COMMAND=1                           # 禁用 /bug 命令
DISABLE_COST_WARNINGS=1                         # 隐藏成本警告
DISABLE_PROMPT_CACHING=1                        # 全局禁用提示缓存
DISABLE_PROMPT_CACHING_SONNET=1                 # 仅对 Sonnet 禁用
DISABLE_PROMPT_CACHING_OPUS=1                   # 仅对 Opus 禁用
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # 跳过非关键 API 调用
ENABLE_PROMPT_CACHING_1H=1                      # 启用 1 小时提示缓存 TTL(v2.1.108+,API/Bedrock/Vertex/Foundry)
ENABLE_PROMPT_CACHING_1H_BEDROCK=1              # 上述变量的弃用别名;v2.1.108+ 在 Bedrock 上仍然支持但会记录弃用通知
FORCE_PROMPT_CACHING_5M=1                       # 强制使用 5 分钟缓存 TTL(v2.1.108+)
ENABLE_TOOL_SEARCH=true                         # 在 Vertex AI 上重新启用工具搜索(v2.1.119+ 默认禁用,以避免不支持的 beta 请求头)。有效值:true、false、auto、auto:N[^160]
CLAUDE_CODE_HIDE_CWD=1                          # 在启动 logo 中隐藏工作目录(v2.1.119+)[^160]
CLAUDE_CODE_FORK_SUBAGENT=1                     # 在外部构建中启用 fork 子代理(v2.1.117+)[^160]

BASH_DEFAULT_TIMEOUT_MS=30000                   # Bash 命令超时(30 秒)
BASH_MAX_TIMEOUT_MS=600000                      # 最大 bash 超时(10 分钟)
BASH_MAX_OUTPUT_LENGTH=50000                    # Bash 输出限制
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # 每次 bash 后重置 CWD
MCP_TIMEOUT=5000                                # MCP 服务器启动超时
MCP_TOOL_TIMEOUT=30000                          # MCP 工具执行超时
MAX_MCP_OUTPUT_TOKENS=25000                     # MCP 输出限制
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # 斜杠命令上下文限制

HTTP_PROXY=http://proxy:8080                    # HTTP 代理
HTTPS_PROXY=https://proxy:8080                  # HTTPS 代理
NO_PROXY=localhost,example.com                  # 为这些域名绕过代理
CLAUDE_CODE_CLIENT_CERT=/path/to/cert           # mTLS 证书
CLAUDE_CODE_CLIENT_KEY=/path/to/key             # mTLS 私钥
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE=pass          # mTLS 密码

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # 不更新终端标题
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # 跳过 IDE 扩展安装
CLAUDE_CODE_SHELL=/bin/zsh                      # 覆盖 shell 检测
USE_BUILTIN_RIPGREP=1                           # 使用内置 ripgrep(默认)
CLAUDE_CONFIG_DIR=~/.myconfig                   # 自定义配置目录
IS_DEMO=1                                       # 隐藏敏感 UI 元素[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # 禁用后台任务和 Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # 覆盖临时目录[^50]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # 禁用 1M 上下文窗口(使用标准 200K)[^103]
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000       # 插件市场 git 超时(默认 120 秒,原为 30 秒)[^105]
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1        # 移除内置的 commit/PR 指令[^117]
CLAUDE_CODE_DISABLE_CRON=1                    # 在会话中途停止已调度的 cron 作业[^121]
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=30000 # SessionEnd hooks 超时(默认值因情况而异)[^123]
CLAUDE_CODE_USE_POWERSHELL_TOOL=1             # 在 Linux/macOS 上启用 Windows PowerShell 工具(需要 PATH 中有 pwsh;v2.1.111+)[^153]
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1             # 在禁用遥测时强制启用 Session Recap(v2.1.108+)[^153]
OTEL_LOG_RAW_API_BODIES=1                     # 将完整的 API 请求/响应正文作为 OTel 日志事件发出(v2.1.111+)[^153]
TRACEPARENT=00-...                            # W3C Trace Context 父级(v2.1.110+,SDK/headless)[^153]
TRACESTATE=vendor=value                       # W3C Trace Context 状态(v2.1.110+,SDK/headless)[^153]

OTEL_LOGS_EXPORTER=none                       # OTel 日志导出器(支持 'none' 用于禁用;v2.1.85 修复了崩溃)
OTEL_METRICS_EXPORTER=none                    # OTel 指标导出器(支持 'none';v2.1.85 修复了崩溃)
OTEL_TRACES_EXPORTER=none                     # OTel 追踪导出器(支持 'none';v2.1.85 修复了崩溃)
OTEL_LOG_TOOL_CONTENT=1                       # 选择在 OTel spans 中发出工具内容(v2.1.101+,默认敏感)
OTEL_LOG_TOOL_DETAILS=1                       # 选择在 OTel tool_result 事件中发出 tool_parameters(v2.1.85+)
OTEL_LOG_USER_PROMPTS=1                       # 选择在 OTel 追踪中发出用户提示(v2.1.101+,默认敏感)
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1    # 禁用 release-notes 获取(v2.0.17+);v2.1.110 在设置时也会停止 headless/SDK 中的自动标题 Haiku 请求

CLAUDE_CODE_EXTRA_BODY='{...}'                # 向 API 调用注入额外的 body 字段;v2.1.113 修复了 Vertex/子代理调用上 output_config.effort 的 400 错误
CLAUDE_CODE_MAX_CONTEXT_TOKENS=200000         # 覆盖最大上下文 token 数(已有变量;v2.1.98 修复了同时设置 DISABLE_COMPACT 时的处理)
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS=25000 # 覆盖文件读取操作的默认 token 限制(v2.1.0+)
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1   # 流式失败时不回退到非流式 API(v2.1.83+)
ANTHROPIC_BETAS=beta1,beta2                   # 启用 beta API 请求头;v2.1.78 修复了 Haiku 模型上的静默忽略问题
ANTHROPIC_SMALL_FAST_MODEL=arn:...            # 快速模型 ID(支持 Bedrock ARN;v0.2.125 不再转义 ARN 中的斜杠)

CLAUDE_CODE_PLUGIN_CACHE_DIR=~/.claude/plugins # 插件缓存目录(v2.1.72 修复了某些 shell 上字面量 '~' 目录的问题)
CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 # 当 git pull 失败时保留插件市场缓存(便于离线使用;v2.1.90+)
CLAUDE_CODE_MCP_SERVER_NAME=server1           # 传递给 MCP headersHelper 脚本,使一个 helper 可以服务多个服务器(v2.1.85+)
CLAUDE_CODE_MCP_SERVER_URL=https://...        # 与名称一起传递给 MCP headersHelper 脚本(v2.1.85+)

CLAUDE_CODE_SHELL_PREFIX="time "              # 为每个 Claude 调用的 shell 命令添加前缀(v1.0.61+)
CLAUDE_CODE_GIT_BASH_PATH=C:\Program\ Files\Git\bin\bash.exe  # Windows 上自定义 Git Bash 路径(v2.1.98+)
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY=60000       # SDK:N 毫秒空闲后退出(v2.0.35+)
CLAUDE_CODE_AUTO_CONNECT_IDE=false            # 禁用 IDE 自动连接(v1.0.61+)

CLAUDE_CODE_PROXY_RESOLVES_HOSTS=1            # 选择启用代理端 DNS 解析(v2.0.55 将其从默认开启改为按需启用)
CLAUDE_CODE_API_KEY_HELPER_TTL_MS=300000      # 通过 apiKeyHelper 动态生成的 API 密钥的 TTL(apiKeyHelper 刷新于 v0.2.74 添加,默认 5 分钟;环境变量于 v0.2.117 添加)

${CLAUDE_SKILL_DIR}                            # 供 skills 自我引用以定位自身目录[^117]

CLAUDE_CODE_ACCOUNT_UUID=uuid                  # 同步为 SDK 调用方提供账户 UUID
CLAUDE_CODE_USER_EMAIL=[email protected]        # 为 SDK 调用方提供用户邮箱
CLAUDE_CODE_ORGANIZATION_UUID=uuid             # 为 SDK 调用方提供组织 UUID

ANTHROPIC_LOG=debug                             # 启用 API 请求日志记录

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

claude --model opus

export ANTHROPIC_MODEL=opus

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

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

claude --model sonnet[1m]
claude --model opus[1m]           # Opus 4.7 配 1M 上下文

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

> /status

> /fast            # 切换 fast 模式开/关

> /effort              # 打开交互式滑块（方向键 + Enter）
> /effort xhigh        # 直接设置

// .claude/settings.json
{
  "autoMode": {
    "allow": [
      "Bash(npm test:*)",        // 您的添加,前置
      "$defaults",                // 内置 allow 列表插入此处
      "Bash(git push:origin/feature/*)"  // 后续追加
    ]
  }
}

> /cost

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

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

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

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

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

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

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

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

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

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

# Enable at startup
claude --enable-auto-mode

# Or cycle into it during a session
Shift+Tab  # Cycles through: default → acceptEdits → auto → plan

claude --dangerously-skip-permissions

claude --permission-mode auto  # or acceptEdits, plan, bypassPermissions

Shift+Tab  # Cycles through modes

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

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

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

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

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

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

> /sandbox

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true,
      "deniedDomains": ["pastebin.com", "transfer.sh", "0x0.st"]
    }
  }
}

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

{"matcher": "*"}              // 匹配所有工具
{"matcher": "Bash"}           // 仅匹配Bash
{"matcher": "Edit|Write"}     // 匹配Edit或Write
{"matcher": "mcp__github"}    // 匹配MCP服务器工具
{"matcher": ""}               // 匹配无工具的事件（如UserPromptSubmit）

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

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

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

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

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

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

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "http",
            "url": "https://api.example.com/notify",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

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

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "linear",
            "tool": "create_comment",
            "input": {"issue_id": "ENG-123", "body": "Auto-updated by Claude Code"}
          }
        ]
      }
    ]
  }
}

# Stderr-flagged warning when an Edit takes more than 10 seconds
DUR=$(jq -r '.duration_ms')
if [ "$DUR" -gt 10000 ]; then
  echo "[slow-edit] ${DUR}ms — investigate $TOOL_INPUT_FILE_PATH" >&2
fi

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

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

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

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

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

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

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

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

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

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

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

claude --debug

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

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

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

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

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "alwaysLoad": true
    }
  }
}

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

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

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

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

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

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

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

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

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

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

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

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

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

export MAX_MCP_OUTPUT_TOKENS=50000

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

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

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