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               # subagents 使用的模型
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          # 啟用 agent teams（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 身分驗證（適用於 gateway）
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # 略過 Vertex 身分驗證
AWS_BEARER_TOKEN_BEDROCK=token                  # Bedrock bearer token
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                        # 全域停用 prompt caching
DISABLE_PROMPT_CACHING_SONNET=1                 # 僅停用 Sonnet 的 prompt caching
DISABLE_PROMPT_CACHING_OPUS=1                   # 僅停用 Opus 的 prompt caching
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # 略過非關鍵的API呼叫
ENABLE_PROMPT_CACHING_1H=1                      # 啟用 1 小時 prompt cache TTL（v2.1.108+，API/Bedrock/Vertex/Foundry）
ENABLE_PROMPT_CACHING_1H_BEDROCK=1              # 上述變數的已棄用別名；v2.1.108+ 在 Bedrock 上仍會接受，但會記錄棄用警告
FORCE_PROMPT_CACHING_5M=1                       # 強制使用 5 分鐘 cache TTL（v2.1.108+）
ENABLE_TOOL_SEARCH=true                         # 在 Vertex AI 上重新啟用 tool search（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                     # 在外部建置版本上啟用 forked subagents（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            # Slash command 內容上限

HTTP_PROXY=http://proxy:8080                    # HTTP proxy
HTTPS_PROXY=https://proxy:8080                  # HTTPS proxy
NO_PROXY=localhost,example.com                  # 略過特定網域的 proxy
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 context window（改用標準 200K）[^103]
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000       # Plugin marketplace git 逾時（預設 120 秒，原為 30 秒）[^105]
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1        # 移除內建的 commit/PR 指示[^117]
CLAUDE_CODE_DISABLE_CRON=1                    # 在工作階段中停止已排程的 cron jobs[^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 log events 發出（v2.1.111+）[^153]
TRACEPARENT=00-...                            # W3C Trace Context parent（v2.1.110+，SDK/headless）[^153]
TRACESTATE=vendor=value                       # W3C Trace Context state（v2.1.110+，SDK/headless）[^153]

OTEL_LOGS_EXPORTER=none                       # OTel logs exporter（支援 'none' 進行停用；v2.1.85 修復了崩潰問題）
OTEL_METRICS_EXPORTER=none                    # OTel metrics exporter（支援 'none'；v2.1.85 修復了崩潰問題）
OTEL_TRACES_EXPORTER=none                     # OTel traces exporter（支援 '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 traces 中發出使用者 prompts（v2.1.101+，預設視為敏感資料）
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1    # 停用 release-notes 擷取（v2.0.17+）；v2.1.110 在設定後也會停止 headless/SDK 中的自動標題 Haiku 請求

CLAUDE_CODE_EXTRA_BODY='{...}'                # 將額外的 body 欄位注入API呼叫；v2.1.113 修復了 Vertex/subagent 呼叫中 output_config.effort 的 400 錯誤
CLAUDE_CODE_MAX_CONTEXT_TOKENS=200000         # 覆寫最大 context tokens（既有變數；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:...            # Fast model ID（支援 Bedrock ARN；v0.2.125 起停止對 ARN 中的斜線進行跳脫）

CLAUDE_CODE_PLUGIN_CACHE_DIR=~/.claude/plugins # Plugin 快取目錄（v2.1.72 修復了某些 shell 上字面 '~' 目錄的問題）
CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 # git pull 失敗時保留 plugin marketplace 快取（離線友善；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            # 啟用 proxy 端 DNS 解析（v2.0.55 將此從預設啟用改為選擇性啟用）
CLAUDE_CODE_API_KEY_HELPER_TTL_MS=300000      # 透過 apiKeyHelper 動態產生API金鑰的 TTL（v0.2.74 新增 apiKeyHelper 重新整理機制，預設 5 分鐘；v0.2.117 新增此環境變數）

${CLAUDE_SKILL_DIR}                            # 供 skills 自我參照以定位自身目錄[^117]

CLAUDE_CODE_ACCOUNT_UUID=uuid                  # 為SDK呼叫者同步提供 account UUID
CLAUDE_CODE_USER_EMAIL=[email protected]        # 為SDK呼叫者提供使用者電子郵件
CLAUDE_CODE_ORGANIZATION_UUID=uuid             # 為SDK呼叫者提供 organization 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 mode 開/關

> /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": "*"}              // Match all tools
{"matcher": "Bash"}           // Match Bash only
{"matcher": "Edit|Write"}     // Match Edit or Write
{"matcher": "mcp__github"}    // Match MCP server tools
{"matcher": ""}               // Match for events without tools (like UserPromptSubmit)

{
  "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?