Global Config Options
Use `/config` for interactive settings, or pass one or more `key=value` pairs. Run `/config --help` for the keys supported by your installed build. ```bash /config # Open the settings UI /config theme=dark model=sonnet # Update supported keys directly ``` For version-controlled or managed configuration, edit JSON settings files directly: | Scope | File | | :---- | :--- | | User | `~/.claude/settings.json` | | Project (shared) | `.claude/settings.json` | | Project (private) | `.claude/settings.local.json` | | Managed | macOS: `/Library/Application Support/ClaudeCode/`Linux/WSL: `/etc/claude-code/`
Windows: `C:\Program Files\ClaudeCode\` | ```json { "model": "sonnet", "theme": "dark", "autoUpdatesChannel": "stable", "permissions": { "defaultMode": "default" } } ``` Settings-file precedence is **managed policy → `--settings` → local → project → user**. Other flags and environment variables are not levels in this stack; each key decides whether they win (`--model` and `ANTHROPIC_MODEL` beat any `model` setting, even a managed one, which is only a starting default). List keys such as `permissions.allow` merge across files, so read [settings precedence](https://code.claude.com/docs/en/settings#settings-precedence) before relying on last-writer-wins behavior; [All settings](https://code.claude.com/docs/en/settings-reference) lists every key. With no permission mode configured, interactive sessions start in auto mode; `permissions.defaultMode` overrides that, but `auto` and `bypassPermissions` apply only from user or managed settings (or `--settings` / `--permission-mode`). `~/.claude.json` stores global state, session/trust data, and local/user MCP configuration; it is not the user settings file. To hide all commit and PR attribution, set `"attribution": false`. Versions before v2.1.281 skip a settings file that contains it, so in files they also read use `"attribution": { "commit": "", "pr": "", "sessionUrl": false }`.
Configuration Files
Claude Code combines human-authored instructions from several locations: | Memory Type | Location | Purpose | Use Case Examples | Shared With | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------- | | **Enterprise policy** | macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`Linux: `/etc/claude-code/CLAUDE.md`
Windows: `C:\Program Files\ClaudeCode\CLAUDE.md` | Organization-wide instructions managed by IT/DevOps | Company coding standards, security policies, compliance requirements | All users in organization | | **Project memory** | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Team-shared instructions for the project | Project architecture, coding standards, common workflows | Team members via source control | | **User memory** | `~/.claude/CLAUDE.md` | Personal preferences for all projects | Code styling preferences, personal tooling shortcuts | Just you (all projects) | | **Project memory (local)** | `./CLAUDE.local.md` | Personal project preferences (add to `.gitignore`) | Your sandbox URLs, preferred test data, personal overrides | Just you (current project) | | **Project rules** | `.claude/rules/**/*.md` | Modular project rules (loaded alongside CLAUDE.md) | Linting rules, API conventions, path-scoped standards | Team members via source control | | **User rules** | `~/.claude/rules/**/*.md` | Personal rules, loaded before project rules | Preferred tools, personal workflow conventions | Just you (all projects) | > Instruction files are concatenated rather than overriding one another. User and ancestor-project files load at startup; `CLAUDE.md` files in subdirectories load lazily when Claude works there. In monorepos, skip other teams' or unrelated ancestor files with the `claudeMdExcludes` setting (glob patterns; a managed `CLAUDE.md` can't be excluded). `CLAUDE.md` is context, not an enforcement boundary. Run `/doctor prompt-audit` for a report of outdated, broken, or conflicting instructions; it edits nothing until you approve. Use `@path` to import another file. When no `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` exists in the working directory or above it, Claude Code reads `AGENTS.md` instead; user and managed `CLAUDE.md` files and `.claude/rules/` still load. If any of those project files exists (even just `CLAUDE.local.md`), `AGENTS.md` is skipped: import it with `@AGENTS.md`, or set **Project instructions** to `claude-md-and-agents-md` in `/config` to load both. #### `.claude/rules/` Directory The `.claude/rules/` directory lets you break project instructions into separate Markdown files instead of one large `CLAUDE.md`. Markdown files are discovered recursively. Add `paths` frontmatter with glob patterns when a rule should load only for matching files. This is useful for: - **Modular organization**: Separate concerns (e.g., `api-conventions.md`, `testing-rules.md`) - **Per-directory scoping**: `paths`-scoped rules and rules in a subdirectory's `.claude/rules/` load on demand when Claude reads, writes, or edits files they cover, adding to other rules rather than overriding them - **Team collaboration**: Different team members can own different rule files via PR review #### Auto-Memory Claude can save useful working context under `~/.claude/projects/
Commands & Usage
Slash Command Reference
Type `/` to see what your installed build, plan, platform, plugins, MCP servers, and skills actually provide. The table below is a high-value snapshot; use the [official command reference](https://code.claude.com/docs/en/commands) for the live list. | Command | Purpose | | :------ | :------ | | `/add-dirCommand Line Flags
| Flag / Command | Description | Example | | :--------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- | | `-d, --debug` | Enable debug mode (shows detailed debug output). | `claude -d -p "query"` | | `--include-partial-messages` | Include partial streaming events; requires print mode and `stream-json`. | `claude -p --output-format stream-json --verbose --include-partial-messages "query"` | | `--include-hook-events` | Include hook lifecycle events in `stream-json` output. | `claude -p --output-format stream-json --verbose --include-hook-events "query"` | | `--forward-subagent-text` | Forward subagent text/thinking with `parent_tool_use_id` in `stream-json`. | `claude -p --output-format stream-json --verbose --forward-subagent-text "query"` | | `--verbose` | Override verbose mode setting from config (shows expanded logging / turn-by-turn output). | `claude --verbose` | | `-p, --print` | Print response and exit (useful for piping output). | `claude -p "query"` | | `--output-formatCLI Quick Reference & Configuration Examples
```md ## 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 headless print mode cat logs.txt | claude -p "explain" # Pipe input to Claude and exit claude -c # Continue most recent conversation claude -r "Interface & Input
Keyboard Shortcuts
| Shortcut | Description | Context | | :--------------------------- | :--------------------------------- | :--------------------------------------- | | `Ctrl+C` | Interrupt, or clear input | Interrupts a running operation; when idle, clears the prompt (`Up` restores it), and a second press exits | | `Ctrl+D` | Exit Claude Code session | Press twice on an empty prompt; with text, deletes the next character | | `Ctrl+G` | Open in default text editor | Edit your prompt or custom response | | `Ctrl+L` | Redraw the screen | Keeps your input and conversation; `/clear` starts a new conversation | | `Ctrl+O` | Toggle transcript viewer | Shows detailed tool usage, timestamps, and model | | `Ctrl+R` | Reverse search command history | Search through previous commands | | `Ctrl+V` (`Cmd+V` in iTerm2); `Alt+V` on Windows/WSL | Paste image from clipboard | Inserts an image chip at the cursor | | `Ctrl+B` | Background running tasks | Backgrounds bash commands and agents | | `Ctrl+X`, then `Ctrl+K` | Stop all background agents | Press the chord twice within 3 seconds to confirm | | `Ctrl+T` | Toggle task checklist | Stays empty on models newer than Opus 4.7/Sonnet 4.6/Haiku 4.5 unless `CLAUDE_CODE_ENABLE_TODO_TOOLS=1`; `/tasks` is the background-work view | | `Ctrl+S` | Stash or restore the current prompt | Preserves text, cursor, and pasted content | | `Ctrl+Enter` or `Ctrl+X Ctrl+S` | Send queued messages now | Sends queued messages and your draft now; running shells and subagents move to the background, otherwise the turn is interrupted; use `Ctrl+X Ctrl+S` if `Ctrl+Enter` arrives as Enter | | `Ctrl+Z` | Suspend Claude Code | Unix only; `fg` resumes (undo is `Ctrl+_`) | | `Up/Down arrows` | Navigate command history | Recall previous inputs | | `Left/Right arrows` | Cycle through dialog tabs | Navigate between tabs in dialogs | | `←` on an empty prompt | Open agent view | Backgrounds the session and opens `claude agents`; detaches an attached session | | `Esc` | Interrupt Claude, or close a dialog | Stops the current response or tool call, keeping work so far; declines a permission prompt | | `Esc` + `Esc` | Clear the draft, or rewind | With text, clears it (`Up` recalls it); on an empty prompt, opens the rewind menu to restore or summarize code and conversation | | `Shift+Tab` (or `Alt+M`) | Cycle enabled permission modes | Includes Manual, Accept Edits, Plan, and enabled Auto/Bypass modes; `Alt+M` is a Windows fallback | | `Option+P` (macOS) / `Alt+P` | Switch model | Switch models without clearing prompt | | `Option+T` (macOS) / `Alt+T` | Toggle extended thinking | No effect on Opus 5.5, Sonnet 5.5, Haiku 5.5, or Fable models, which always think; works on macOS without Option as Meta | | `Option+O` (macOS) / `Alt+O` | Toggle fast mode | Enable/disable supported fast mode | > [!Tip] > **Custom shortcuts:** run `/keybindings` to open `~/.claude/keybindings.json`, whose `bindings` array holds blocks like `{ "context": "Chat", "bindings": { "ctrl+e": "chat:externalEditor", "ctrl+s": null } }` (`null` unbinds). Changes apply without a restart; `Ctrl+C`/`Ctrl+D` are reserved and vim keys can't be remapped. > [!Note] > **Fullscreen rendering** (flicker-free, with mouse support) is the default for most new installs. Switch with `/tui fullscreen` or `/tui default` (`/tui` alone shows the active renderer), or set `CLAUDE_CODE_NO_FLICKER=1`/`0` per launch. In its transcript viewer, `?` lists the extra keys.Text Editing
| Shortcut | Description | Context | | :--------------------- | :--------------------------- | :------------------------------------ | | `Ctrl+K` | Delete to end of line | Stores deleted text for pasting | | `Ctrl+U` | Delete to start of line | Stores deleted text; repeat to clear across lines in multiline input | | `Ctrl+W` | Delete back to whitespace | Removes a whole path or `--flag=value` in one press | | `Ctrl+Y` | Paste deleted text | Pastes text last deleted with Ctrl+K/U/W or Alt+D | | `Alt+Y` (after Ctrl+Y) | Cycle paste history | Cycle through previously deleted text | | `Alt+B` | Move cursor back one word | Requires Option as Meta on macOS | | `Alt+F` | Move cursor forward one word | Stops at word end (`_`, `.`, `/` separate words); requires Option as Meta on macOS | | `Alt+D` | Delete to end of word | Stores deleted text; requires Option as Meta on macOS | | `Ctrl+_` | Undo last input edit | Also `Ctrl+Shift+-` |Multiline Input
| Method | Shortcut | Context | | :--------------- | :------------- | :-------------------------------- | | Quick escape | `\` + `Enter` | Works in all terminals | | Option key | `Option+Enter` | macOS, after enabling Option as Meta (see tip below) | | Shift+Enter | `Shift+Enter` | Native in iTerm2, WezTerm, Ghostty, Kitty, Warp, Apple Terminal, and Windows Terminal; see tip below for others | | Control sequence | `Ctrl+J` | Line feed character for multiline | | Paste mode | Paste directly | For code blocks, logs | > [!Tip] > Run `/terminal-setup` once for Shift+Enter in VS Code, Cursor, Zed, and Alacritty before 0.16 (foot, Alacritty 0.16+, and other kitty-protocol terminals work natively); gnome-terminal and JetBrains terminals have none, so use `Ctrl+J`. In tmux, add `set -s extended-keys on` and `set -as terminal-features 'xterm*:extkeys'` to `~/.tmux.conf`. `Option+` shortcuts on macOS need Option as Meta (Terminal.app: Settings → Profiles → Keyboard; iTerm2: Option keys to "Esc+"; VS Code: `"terminal.integrated.macOptionIsMeta": true`).Quick Commands
| Shortcut | Description | Notes | | :----------- | :---------------- | :------------------------------------ | | `/` at start | Command or skill | See built-in commands and skills | | `!` at start | Shell mode | Runs the command and Claude responds to its output; `"respondToBashCommands": false` only adds it to context | | `@` | File or session mention | Autocompletes file paths; after a letter, also suggests your other live sessions for Claude to message | | `?` on empty input | Shortcut help | Toggles the shortcut help panel | > [!Tip] > **PDF Page Ranges:** For PDFs over 10 pages, the Read tool takes one page or range per call in its `pages` parameter (e.g., `pages: "1-5"`, up to 20 pages; comma lists like `"6,9,15"` error). Page reads need `pdftoppm` (`brew install poppler` / `apt-get install poppler-utils`). Large PDFs (>10 pages) return a lightweight reference when @-mentioned instead of being inlined. > [!Tip] > **Voice and spelling:** `/voice` turns on dictation (hold `Space` to record, or `/voice tap` to tap to start and again to send); it needs a Claude.ai login and a local mic, so not API-key/Bedrock/Agent Platform/Foundry auth, SSH, or cloud sessions. `"spellcheck": { "enabled": true }` in `~/.claude/settings.json` underlines misspellings (needs `aspell`, `hunspell`, or `ispell`).Vim Mode
> [!Note] > Enable vim-style editing from `/config` -> Editor mode, or set `"editorMode": "vim"` in `~/.claude/settings.json`. Add `"vimInsertModeRemaps": { "jj": "Vim Mode Switching
| Command | Action | From mode | | :------ | :-------------------------- | :-------- | | `Esc` or `Ctrl+[` | Enter NORMAL mode | INSERT, VISUAL | | `i` | Insert before cursor | NORMAL | | `I` | Insert at beginning of line | NORMAL | | `a` | Insert after cursor | NORMAL | | `A` | Insert at end of line | NORMAL | | `o` | Open line below | NORMAL | | `O` | Open line above | NORMAL | | `v` / `V` | Visual selection (character / line); `d`, `y`, `c`, `p`, `>`/`<`, `~`/`u`/`U`, `J` act on it | NORMAL |Vim Navigation
| Command | Action | | :-------------- | :------------------------ | | `h`/`j`/`k`/`l` | Move left/down/up/right | | `w` | Next word | | `e` | End of word | | `b` | Previous word | | `0` | Beginning of line | | `$` | End of line | | `^` | First non-blank character | | `gg` | Beginning of input | | `G` | Beginning of last line | | `f`/`F`/`t`/`T` + char | Jump to, or just before/after, a character on the line; `;` / `,` repeat / reverse | | `%` | Matching `()`, `[]`, or `{}` bracket (also with `d`/`c`/`y`) | | `/` | Reverse history search (same as `Ctrl+R`) |Vim Editing
| Command | Action | | :------------- | :---------------------- | | `x` | Delete character | | `dd` | Delete line | | `D` | Delete to end of line | | `dw`/`de`/`db` | Delete word/to end/back | | `cc` | Change line | | `C` | Change to end of line | | `cw`/`ce`/`cb` | Change word/to end/back | | `r{char}`, `s`/`S` | Replace character; substitute character/line | | `yy`/`Y`, `yw`/`ye`/`yb` | Yank line, word/to end/back | | `p` / `P` | Paste after / before cursor | | `>>` / `<<`, `J` | Indent / dedent line; join lines | | `ciw`, `di"`, `ya(` … | Text objects: `i`/`a` + `w`, `W`, `"`, `'`, `(`, `[`, or `{`, with `d`/`c`/`y` | | `u` / `.` | Undo / repeat last change | > [!Tip] > Enter still submits your prompt in INSERT mode, unlike standard Vim. Use `o`/`O` in NORMAL mode, or `Ctrl+J`, to insert a newline.Command History
Claude Code keeps a history of the prompts you type (in `~/.claude/history.jsonl`), and Up-arrow recall also reaches earlier sessions of the same project: * History is stored per working directory * `/clear` doesn't erase history; recall lists the new session's prompts first, then earlier ones * Up/Down (or `Ctrl+P`/`Ctrl+N`) first move the cursor within a multiline prompt, then step through history * **Ctrl+R** is built in and works in any terminal: the inline search covers all projects (`Ctrl+R` again for older matches, `Tab`/`Esc` to accept, `Enter` to accept and run). In fullscreen it opens a dialog where `Ctrl+S` cycles the scope (session, project, all projects) * **Drafts cleared with `Ctrl+C`** come back with `Up`; the last ten, with pasted text and images, are kept until you exit * History expansion with `!` is disabled by default ---Advanced Features
Thinking Keywords
> [!Note] > **`ultrathink` is the only documented prompt keyword for a one-turn request for deeper reasoning.** Phrases such as `think`, `think hard`, and `think harder` are ordinary prompt text; they are not graduated Claude Code controls. Use `/effort` for an explicit session setting. `ultrathink` adds an in-context instruction for that turn without changing your saved effort level. Typed at the terminal prompt on Opus 5.5, Sonnet 5.5, Haiku 5.5, or Fable 5.1 through Anthropic's API (v2.1.311+), it can also raise that turn to `xhigh`; the word turns rainbow-colored when it can. Elsewhere, such as on Bedrock, set `/effort` instead. ```md 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. ```bash /effort # Slider: Enter saves for this model, s = this session only, Tab toggles Ultracode /effort low # Faster, lighter reasoning /effort medium # Balanced; default on Opus 5.5, Sonnet 5.5, and Haiku 5.5 /effort high # Deeper planning and review; default on most other models /effort xhigh # Deeper reasoning at higher token spend; default on Opus 4.7 /effort max # Session-only maximum; test for diminishing returns /effort ultracode # Workflow orchestration for this session at the current level ("off" to stop) /effort auto # Clear the saved level and return to the model's default ``` Available levels depend on the model. `/effort` saves a level per model (under `modelSettings`); the `effortLevel` setting accepts `low` through `xhigh` as the fallback for models without one, though a top-level `effortLevel` in user settings doesn't apply to Opus 5.5. `max` normally applies only to the current session, although `CLAUDE_CODE_EFFORT_LEVEL=max` can force it for sessions launched with that environment variable. `maxEffortLevel` caps effort on every provider. Ultracode is a toggle, not an effort level: with it on, Claude orchestrates dynamic workflows for substantive tasks at the session's current level. Set `"ultracode": true` in settings to start every session with it; `claude --effort ultracode` turns it on and also sets `xhigh`. It requires workflows and an xhigh-capable model. Prefer the lowest effort that reliably solves the task because higher effort increases latency and token use.Advisor Tool (Experimental)
The advisor pairs the main model with a second, at-least-as-capable model that Claude may consult at important planning, debugging, or completion decisions. Each consultation sends the full conversation, including tool calls and results; it counts toward subscription usage or is billed at the advisor model's API rates. ```bash /advisor # Open the picker and save the user default /advisor opus # Save Opus as the advisor /advisor off # Clear the saved advisorModel setting claude --advisor opus # Use Opus for this session without changing the saved default ``` The feature runs through the first-party Anthropic API, for subscription or API-billed accounts; it is unavailable on Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry, and opt-in on Claude Platform on AWS (v2.1.300+), where no advisor runs until you pick one. Claude decides when to consult it. `advisorModel` is the persistent settings key, while the intentionally hidden `--advisor` launch flag is session-only; `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1` turns the tool off entirely. With Fable access you can pick Fable as the advisor (the only advisor a Fable main model accepts); where Fable bills to usage credits, accept that once with `/model fable` first. See the [advisor guide](https://code.claude.com/docs/en/advisor) for supported main/advisor pairings.Fast Mode
> [!Note] > **Fast mode runs the same Opus model and capabilities up to 2.5× faster at a higher price per token, without trading model quality for speed. It is generally available on Opus 5.5 and in research preview on Opus 5 and Opus 4.8.** ```bash /fast # Space toggles, Enter confirms and saves your fastMode default /fast on # Turn it on directly (session-only in cloud sessions) # Option+O on macOS or Alt+O on Windows/Linux also toggles it ``` Fast mode supports **Opus 5.5** (the default fast-mode model), **Opus 5**, and **Opus 4.8**, at \$8/\$40 per MTok input/output on Opus 5.5 and \$10/\$50 on the other two. It is unavailable for Sonnet, Haiku, and Opus 4.7, and on Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, and Claude Platform on AWS. VS Code has a **Toggle fast mode** command, and claude.ai/code has a Fast mode switch in the model menu. Subscription users need usage credits; Team and Enterprise also require Owner enablement. Use it for latency-sensitive interactive work, and standard mode for cost-sensitive or long autonomous tasks. Lower `/effort` is the separate control that may trade reasoning depth for speed.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. ```bash # Start in auto mode, or cycle to it with Shift+Tab claude --permission-mode auto # Inspect the built-in and effective classifier configuration claude auto-mode defaults claude auto-mode config claude auto-mode critique # AI feedback on your custom rules # Remove a cached/custom classifier config and return to defaults claude auto-mode reset # Add --yes to skip confirmation ``` ```json { "autoMode": { "environment": [ "$defaults", "Source control: github.example.com/acme-corp and all repos under it" ], "hard_deny": [ "$defaults", "Never send repository contents to third-party code-review APIs" ] } } ``` Key points: - Auto mode is available on every supported provider (on Bedrock, Agent Platform, and Foundry only with Sonnet 5+, Opus 4.7+, Haiku 5.5, and Fable models); `CLAUDE_CODE_ENABLE_AUTO_MODE` is a no-op compatibility variable. With no mode configured, interactive terminal and VS Code sessions start in auto mode where it's available (otherwise Manual), while `claude -p` and Agent SDK runs start in `default` (Manual). Choose another starting mode with `--permission-mode` or `permissions.defaultMode`; `disableAutoMode: "disable"` in managed settings removes auto mode. - The classifier trusts the working directory and current repository remotes by default. Add organization infrastructure under `autoMode.environment` only when needed; `/auto-mode-setup` drafts entries from your project and recent sessions, and `/permissions` has an **Auto mode** tab for viewing and editing rules. - Put `autoMode` in user settings, managed settings, or `--settings`. Repository `.claude/settings.json` and `.claude/settings.local.json` cannot inject classifier policy. - Include `"$defaults"` in `allow`, `soft_deny`, `hard_deny`, or `environment` to extend the built-in rules. An array without it replaces that section's built-in list, so an empty `hard_deny` drops the built-in data-exfiltration rule. - Where supported, classifier checks run server-side at no extra charge (`/status` shows an **Auto mode server** row). Behind a gateway or proxy that blocks them, Claude Code makes its own classifier requests, which count toward usage; `CLAUDE_CODE_AUTO_MODE_SERVER=0` forces that. - Explicit `permissions.deny` and content-scoped `permissions.ask` rules are evaluated before the classifier. Use those for non-negotiable blocks or human checkpoints.Plan Mode
> [!Note] > **Plan Mode tells Claude to research and propose changes without editing your source, and is designed for exploration, planning, and review. It permits read-only shell exploration; when auto mode is available and `useAutoModeDuringPlan` is on (the default), the classifier reviews other commands instead of prompting.** Plan Mode is a workflow mode, not a hard isolation boundary. In interactive terminal sessions where bypass permissions is available (such as with `--dangerously-skip-permissions`), its blocks aren't enforced: Claude is still told not to edit, but edits and commands it attempts run without prompting (explicit ask rules and critical-path `rm`/`rmdir` removals still prompt). Use sandboxing plus explicit deny/ask rules or managed policy when command execution must be technically constrained. When the plan is ready, choose **Yes, and use auto mode** (**Yes, auto-accept edits** without auto mode), **Yes, manually approve edits**, or **No, keep planning**; `Ctrl+G` opens it in your editor first. **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:** ```bash # Start a new session in Plan Mode claude --permission-mode plan # Or toggle during session with Shift+Tab # (cycles through Manual, Accept Edits, Plan, and any other enabled modes) # 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:** In `.claude/settings.json`: ```json { "permissions": { "defaultMode": "plan" } } ``` ---Background Tasks
> [!Note] > **Claude Code supports background commands and full background sessions, allowing you to continue working while long-running processes or agents execute.** **How to use background tasks:** | Method | Description | | :----- | :---------- | | Prompt Claude | Ask Claude to run a shell command or subagent in the background | | `Ctrl+B` | Move a running Bash tool invocation or agent to the background (tmux users press twice) | | `/background` (`/bg`) | Detach this entire conversation and free the terminal | | `←` on an empty prompt | Background this session and open agent view (`leftArrowOpensAgents` in `/config` turns this off) | | `/fork` | Copy this conversation into a worktree-isolated background session while you stay here | | `claude --bg` | Launch a new background Claude session; it cannot be combined with `-p` | | `!Workflows & Scheduling
Dynamic workflows coordinate many background agents for larger work than a single foreground turn can comfortably handle. Ask for one in your own words ("use a workflow to…") or include `ultracode` in your prompt, then use `/workflows` to inspect runs and status. `/deep-researchCloud Sessions
> [!Note] > **For eligible subscribers: use `--cloud` to start a cloud session on claude.ai and `--teleport` to copy a cloud session into a local checkout. `--remote` remains only as a deprecated alias for `--cloud`.** **Start a cloud session:** ```bash # Create a new cloud session on claude.ai with task description claude --cloud "Fix the login bug" ``` The cloud VM clones your GitHub remote at the current branch, not your local checkout, so push local commits first. With no git remote, or when the Claude GitHub App isn't installed on the GitHub repository, Claude Code uploads a bundle of your local repository instead (untracked files are left out; `CCR_FORCE_BUNDLE=1` forces a bundle, for example for a GitLab or Bitbucket repository). Queue a follow-up into a running cloud session with `claude -p "next step" --cloudClaude in Chrome
With the [Claude in Chrome extension](https://code.claude.com/docs/en/chrome), Claude Code can drive browser-based testing and UI verification from the CLI. **Setup:** ```bash claude --chrome # Launch with Chrome integration /chrome # Status, reconnect, site permissions, browser choice, "Enabled by default" ``` **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 - Read console errors and DOM state for live debugging - Upload local files to page upload fields (up to 10 MB per upload; files denied to `Read` are refused) - Record interactions as GIFs and save screenshots to disk > [!NOTE] > Requires Chrome, Edge, or another Chromium browser (Brave, Arc, Vivaldi, Opera), the Claude in Chrome extension v1.0.36+, and a claude.ai subscription sign-in (API keys and `claude setup-token` tokens keep it off). It is unavailable through WSL and third-party model providers, and an organization admin can turn it off. Project settings files can't turn it on; use `--chrome` or **Enabled by default** in `/chrome`, a setting shared with the VS Code extension. Review the extension's site permissions before granting access; in auto mode, classifier-approved browser calls skip the extension's per-site check, so add permission deny rules for sites Claude must never act on. ---Desktop and IDEs
The Claude Desktop Code tab supports macOS, Windows (including sessions inside a WSL 2 distribution), and a Linux beta for Ubuntu/Debian. It provides parallel local or cloud sessions, worktrees, diffs, an editor, terminal, and browser; SSH execution is also available. Desktop and the CLI share CLAUDE.md files, settings, hooks, skills, and MCP servers from `~/.claude.json` and `.mcp.json`, but each keeps its own session list. Desktop's local Code tab sessions also load MCP servers from `claude_desktop_config.json`, which the CLI ignores; on macOS and WSL, `claude mcp add-from-claude-desktop` copies them into `~/.claude.json`. Agent teams are not supported in Desktop. Run `/desktop` to move the current terminal session into the app, or `claude --desktop` (v2.1.285+) to open Desktop from your shell on the current directory, or on a session with `--continue` or `--resumeSandbox Mode
Sandboxing is an OS-enforced boundary for the shell commands Claude runs (Bash, PowerShell, and Monitor) and the processes they start; Claude's file tools, MCP servers, and hooks run outside it, and it is separate from Claude Code's tool-permission rules. It is off by default: turn it on with `/sandbox` or `"sandbox": { "enabled": true }` in `~/.claude/settings.json`, then pick **auto-allow** (sandboxed commands run without prompting) or **regular permissions** on the `/sandbox` Mode tab. With default settings, sandboxed commands can write inside the working directory and temporary directories, read broadly except for denied paths, and reach the network only through a hostname-filtering proxy. ```bash /sandbox # Inspect dependencies and configure filesystem/network isolation ``` Platform support: - macOS uses Seatbelt. - Linux and WSL 2 use bubblewrap plus socat (`sudo apt-get install bubblewrap socat` on Ubuntu/Debian). On Ubuntu 24.04+, if `sysctl kernel.apparmor_restrict_unprivileged_userns` returns `1`, AppArmor stops bubblewrap from creating user namespaces; add an AppArmor profile for `bwrap` (`/sandbox` and the startup warning explain how). - Native Windows and WSL 1 do not support sandboxing. Useful hardening settings include `sandbox.failIfUnavailable: true` to fail closed, `sandbox.allowUnsandboxedCommands: false` (**Strict sandbox mode** on the `/sandbox` Overrides tab) to remove the unsandboxed retry path, `sandbox.network.strictAllowlist: true` for an exact network allowlist, and credential rules with `mode: "deny"` or `mode: "mask"`. Commands you type at the `!` prompt run outside the sandbox even in strict mode, except in background sessions and Linux sessions with `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` set. Put tools that can't run sandboxed, such as `docker`, in `sandbox.excludedCommands` (for example `"docker compose *"`); they run with your full access, so keep patterns narrow. On Linux, `sandbox.allowNestedUserNamespaces: true` in `~/.claude/settings.json` (v2.1.305+) lets Chromium's or Electron's own sandbox, a nested bubblewrap, or `unshare` run inside the sandbox, but it turns off a security boundary; it isn't enough for rootless Podman or Buildah, which need `sandbox.excludedCommands` instead. Masking credential files works on Linux and WSL 2; on macOS a masked file is blocked like `deny`. Every `mask` entry needs `sandbox.network.tlsTerminate`, or the placeholder reaches the server unchanged and authentication fails (`claude doctor` warns `TLS termination is unavailable`). Masks can also extract structured values, mask selected JWT claims, and re-sign AWS SigV4 requests. `mask` entries, `network.tlsTerminate`, `credentials.allowPlaintextInject`, `awsPairs`, and `sigv4` are honored only from user, managed, or `--settings` configuration, never from a repository's `.claude/settings.json` or `.claude/settings.local.json`. Sandboxing reduces the impact of shell commands; it is not a substitute for reviewing permissions and secrets exposure. ---LSP Tool (Language Server Protocol)
Claude Code integrates with language servers to provide IDE-level code intelligence: - **Diagnostics after edits** — Type errors and warnings go back to Claude automatically after each file edit (`Found N new diagnostic issues`; Ctrl+O expands them) - **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 - **Symbols and call hierarchy** — List file or workspace symbols, find implementations, and trace call hierarchies LSP support is provided by plugins. Install the language-server binary separately, then install its LSP plugin from the official marketplace with `/plugin`; for TypeScript, run `npm install -g typescript-language-server typescript`, then `/plugin install typescript-lsp@claude-plugins-official`. A server merely being present on `PATH` is not enough, though Claude Code may then offer the matching plugin. This enables Claude to navigate codebases more precisely than text search alone. Plugin language servers don't start in cloud sessions, so the LSP tool is inactive there. > Large tool results are saved to a file, and Claude gets a preview plus the path. This applies to successful Bash output over about 30,000 characters (adjustable up to 128,000 with the `bashOutputMaxChars` setting) and to MCP results over the limits described under [MCP Integration](#mcp-integration). ---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: | Subagent | Model | Tools | Purpose | | :------- | :---- | :---- | :------ | | **Explore** | Inherits the parent model (Opus under a Fable parent, except on Bedrock, Agent Platform, Foundry, and similar providers) | Read-only | File discovery, code search, and codebase exploration | | **Plan** | Inherits the parent model | Read-only | Planning complex changes without making edits | | **General-purpose** | Inherits the parent model | Inherited | General task delegation | > 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. Explore and Plan start without your `CLAUDE.md` files or git status and can't be resumed. Set `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1` to remove both, or deny one with `Agent(Explore)` in `permissions.deny`. **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.Configure Agents
> Keep agents **in the project** so they're versioned with the repo and evolve via PRs.Quick start
> Ask Claude to create an agent, mention one with `@agent-name`, or edit its Markdown definition directly. `/agents` now prints this guidance; it no longer opens the old wizard. ```bash claude update # Project agent: .claude/agents/Subagent Scopes
| Location | Scope | Priority | | :------- | :---- | :------- | | Managed policy agents | Organization | 1 (highest) | | `--agents` CLI flag | Current session only | 2 | | `.claude/agents/` | Current project | 3 | | `~/.claude/agents/` | All your projects | 4 | | Plugin's `agents/` directory | Where plugin is enabled | 5 (lowest) | Plugin subagents ignore `hooks`, `mcpServers`, and `permissionMode`; copy the file into `.claude/agents/` or `~/.claude/agents/` to use them. Dispatched sessions honor the `agent` field in `settings.json`. Pass `--agentDefine Agents via CLI
```bash # 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 } }' ``` With `-p`, `--agents` also takes a JSON file path: `claude -p --agents ./agents.json "Review my changes"`. In PowerShell, wrap inline JSON in a here-string (`@'` … `'@`) instead of single quotes.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.\* Grant each agent only the tools its role needs (`tools` is an allowlist, `disallowedTools` a denylist): `Read, Grep, Glob` for advisory agents, plus `Edit` and `Write` for editing ones.Example prompts
> Keep prompts short, testable, and repo‑specific. Check them into `.claude/agents/`:Expected output
> Your tester agent should produce a small diff or patch plus a short rationale:Subagent Frontmatter Fields
Subagent files use YAML frontmatter for configuration: ```markdown --- 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. ``` | Field | Required | Description | | :---------------- | :------- | :------------------------------------------------------------------ | | `name` | Yes | Unique identifier such as `code-reviewer` (max 256 characters, no `:`, no leading `-`); needn't match the filename | | `description` | Yes | When Claude should delegate to this subagent | | `tools` | No | Tools the subagent can use (inherits all if omitted) | | `disallowedTools` | No | Tools to deny, removed from inherited or specified list | | `model` | No | `sonnet`, `opus`, `haiku`, `fable`, a full model ID, or `inherit`; if omitted, see the model order below | | `effort` | No | Model-dependent effort override for this subagent | | `maxTurns` | No | Maximum agentic turns; hitting it returns partial output Claude can resume | | `autoCompactWindow` | No | Auto-compact earlier: plain integer `100000`–`1000000` (`200k` reads as 200); can lower, never raise, `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | | `permissionMode` | No | `default`/`manual`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, or `plan` | | `skills` | No | Skills to preload into the subagent's context (max 32; the Skill tool can load others) | | `hooks` | No | Lifecycle hooks scoped to this subagent | | `mcpServers` | No | MCP servers available to this subagent | | `memory` | No | Persistent memory scope: `user`, `project`, or `local` | | `omitClaudeMd` | No | `true` skips user, project, and local `CLAUDE.md` files (managed policy still loads) | | `isolation` | No | Set to `worktree` to run the agent in an isolated git worktree, branched per [`worktree.baseRef`](#worktree-isolation) | | `background` | No | `true` keeps it in the background even when Claude asks to wait for it | | `color` | No | Display color in the task list and transcript: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, or `cyan` | | `initialPrompt` | No | First user turn when this definition runs as the main session via `--agent` or the `agent` setting | | `experimental` | No | Experimental options; `cacheTtl: 5m` or `1h` sets the prompt-cache TTL (agent files only) | Field names are case-sensitive. Unknown fields are silently ignored and a file missing `name` or `description` is skipped; `claude --debug` logs unknown fields and most skip reasons. **Model order:** a model Claude passes for one spawn, then the definition's `model`, then `CLAUDE_CODE_SUBAGENT_MODEL`, then the main model. That variable is only a default and doesn't move Explore or Plan; add `CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1` to apply it to every subagent, teammate, and workflow agent. Asking for an effort ("use a subagent at high effort") overrides `effort` for that spawn; `/tasks` shows each subagent's model and effort. Organization model allowlists still apply to frontmatter. A restricted family alias steps down to the newest permitted model in that family where supported; when a workflow agent, forked skill/command, or resumed background agent must run on the parent model instead, Claude Code warns rather than silently implying the requested model was honored. **Background by default:** subagents Claude spawns from the main conversation start in the background, with every MCP tool but only core built-in tools. Claude can still wait for one under `claude -p` and the Agent SDK, but in the terminal, desktop app, and VS Code only with fork mode off (`CLAUDE_CODE_FORK_SUBAGENT=0`, e.g. in the `settings.json` `env` block, then restart). `Ctrl+B` (**Run in background** in VS Code) backgrounds a waiting subagent. Ask Claude to resume a finished subagent to continue with its history. **Forks:** a fork (`subagent_type: "fork"`) inherits the whole conversation, model, tools, prompt cache, and permission mode, so it can't leave plan mode. Fork mode is on by default except under `claude mcp serve`; start a fork yourself with `/subtaskWhy 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/`) with a frontmatter `PreToolUse` hook that exits `2` on out-of-scope files (a `disallowedTools` entry like `Edit(src/**)` removes the whole tool). > - Favor read‑only analysis for high‑risk areas. > - Log/commit assistant outputs as patches for auditability.A Mindset Shift
**Do** > - Treat agents as teammates with job descriptions. > - Start read‑only; grant write access _last_. > - Keep prompts in version control and iterate via PR. **Don't** > - Ask one agent to plan, code, and test in a single turn. > - Give blanket write permissions. > - Accept multi‑file diffs when you asked for one test. ---Agent Teams (Research Preview)
> [!Note] > **Agent Teams is an experimental feature enabling multiple Claude instances to work in parallel on a shared codebase autonomously.** **Enable Agent Teams:** ```bash export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 ``` **Key Concepts:** - A lead session coordinates separate teammate sessions through a shared task list and direct messages. - Teammates can specialize in independent work such as debugging, documentation, and testing. - Agent teams coordinate through Claude Code messaging, not git synchronization. - Teammates do not receive automatic worktree isolation. Partition files carefully or explicitly create worktrees to avoid conflicting edits. - Teams cost substantially more tokens than subagents; start with three to five teammates and use them only for genuinely parallel work. **Using Agent Teams:** - Enabling teams makes any subagent Claude spawns with a `name` launch as a teammate, without asking (except forks and calls passing `isolation`); set the variable to `0` to revert. `claude -p` and the Agent SDK never spawn teammates. - Ask in plain language (`Spawn three teammates to review PR #142: security, performance, and test coverage.`) or reuse a subagent definition (`Spawn a teammate using the security-reviewer agent type.`). Teammate models follow the [subagent model order](#subagent-frontmatter), ending with the lead's model. - Teammates run in-process by default: select one in the agent panel and press Enter to message it, `x` to stop it, or Ctrl+T to toggle the task list. For split panes, set `"teammateMode": "auto"` in `~/.claude/settings.json` or run `claude --teammate-mode auto`; panes need tmux or iTerm2 (`it2` CLI) and don't work in VS Code's terminal, Windows Terminal, or Ghostty. - Teammates start in the lead's permission mode (except `dontAsk`) and route permission prompts to the lead; gate their work with `TeammateIdle`, `TaskCreated`, and `TaskCompleted` [hooks](#hooks-system). - Limits: one team per session, no nested teams, a fixed lead, and `/resume` or `/rewind` don't restore in-process teammates. **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: | Metric | Value | | :------------------ | :------------------------------------- | | **Claude Sessions** | ~2,000 | | **API Cost** | ~$20,000 | | **Lines of Code** | 100,000 | | **Capability** | Compiled Linux 6.9 on x86, ARM, RISC-V | | **Test Pass Rate** | 99% on GCC torture test suite | **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](https://www.anthropic.com/research/building-c-compiler) ---Skills (Custom Slash Commands)
> [!Note] > **Skills extend what Claude can do. Create a `SKILL.md` file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with `/skill-name`.**Skill Locations
| Location | Scope | Description | | :--------------------------------------- | :------- | :-------------------------------------------- | | `Create a Skill
```bash # Create skill directory mkdir -p ~/.claude/skills/explain-code # Optional: scaffold a personal skills-directory plugin (a separate layout) claude plugin init explain-tools --with skills ``` `claude plugin init` writes under `~/.claude/skills/Skill Frontmatter Fields
| Field | Required | Description | | :------------------------- | :---------- | :---------------------------------------------------------- | | `name` | No | Command name shown in the `/` menu (uses directory name if omitted) | | `description` | Recommended | What the skill does and when to use it | | `when_to_use` | No | Extra trigger phrases or examples, appended to `description` (1,536-character combined cap) | | `argument-hint` | No | Hint shown during autocomplete (e.g., `[filename]`) | | `arguments` | No | Named positional arguments for `$name` substitution (e.g., `[issue, branch]`) | | `disable-model-invocation` | No | Set `true` to prevent Claude from auto-invoking | | `user-invocable` | No | Set `false` to hide from / menu | | `allowed-tools` | No | Tools allowed without asking for the turn that invokes the skill. Not gated by workspace trust, so review it in cloned repos | | `disallowed-tools` | No | Tools removed from the model while the skill is active | | `model` | No | Model to use when this skill is active | | `effort` | No | Effort override while the skill is active | | `context` | No | Set to `fork` to run in a forked subagent context | | `agent` | No | Which subagent to use when `context: fork` is set | | `background` | No | With `context: fork`, defaults to `true`; set `false` to wait for the result | | `hooks` | No | Hooks registered on invocation that stay active for the rest of the session (`once: true` removes a hook after its first successful run) | | `paths` | No | Glob patterns limiting automatic activation to matching files | | `shell` | No | `bash` (default) or `powershell` for dynamic shell context |Pass Arguments to Skills
Use `$ARGUMENTS` placeholder to receive arguments: ```markdown --- 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` Use `$0`, `$1`, ... (or `$ARGUMENTS[N]`) for positional arguments and `$name` for names declared in `arguments`. `${CLAUDE_SKILL_DIR}` (the skill's folder, for bundled scripts), `${CLAUDE_PROJECT_DIR}`, `${CLAUDE_SESSION_ID}`, and `${CLAUDE_EFFORT}` are also substituted.Inject Dynamic Context
Use `` !`command` `` syntax to run shell commands before the skill content is sent to Claude: ```markdown --- name: pr-summary description: Summarize changes in a pull request context: fork agent: Explore allowed-tools: Bash(gh *) --- ## Pull request context - PR diff: !`gh pr diff` - PR comments: !`gh pr view --comments` - Changed files: !`gh pr diff --name-only` ## Your task Summarize this pull request... ``` > Injected commands never prompt: one that isn't already allowed (by `allowed-tools`, an allow rule, or the read-only set) aborts the skill with `Shell command permission check failed`, hence `allowed-tools` above. Auto mode instead has Claude run it as a reviewed tool call, except in a forked skill that sets `agent`. For multi-line commands, open a fenced block with `` ```! ``.Run Skills in a Subagent
Add `context: fork` to run a skill in isolation: ```markdown --- 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/`. > Forked skills run in the background by default as of v2.1.218. Add `background: false` when the invoking turn must wait or the skill needs a foreground-only tool. ---Plugin System
> [!Note] > **Plugins package skills, agents, hooks, MCP and LSP servers, output styles, workflows, executables, and mods that change Claude Code's own behavior and interface. Experimental plugin components also include monitors and themes. The official marketplace is registered automatically unless policy disables it.** **Key commands:** ```bash claude plugin init my-plugin /plugin # Open the plugin manager /plugin marketplace addWorktree Isolation
> [!Note] > **The `--worktree` (`-w`) flag starts Claude in an isolated git worktree, allowing it to make changes in a separate branch without affecting your working directory.** **Usage:** ```bash # Start Claude in an isolated worktree claude -w feature-auth # Claude will: # 1. Create .claude/worktrees/feature-auth/ on a new worktree-feature-auth branch from the configured base ref # 2. Run in that isolated worktree # 3. Keep edits and Bash commands isolated from the original checkout # 4. On exit, offer to keep or remove it (clean worktrees of unnamed sessions are removed automatically) # Branch from a PR: quote "#1234", or pass a GitHub PR or GitLab MR URL claude -w "#1234" ``` Add `.claude/worktrees/` to `.gitignore`. A worktree is a fresh checkout, so list gitignored files it needs, such as `.env`, in a `.worktreeinclude` file (`.gitignore` syntax) at the project root to copy them in. Choose the branch source in settings: ```json { "worktree": { "baseRef": "fresh" } } ``` `fresh` (the default) uses `origin/Native Installer
> [!Note] > **The native installer is the recommended installation path. It starts faster, updates itself, and does not depend on Node.js being on your PATH.** ```bash # Install the stable native build from an existing Claude Code installation claude install stable # Other supported targets claude install latest claude installAuthentication CLI
> [!Note] > **Manage authentication directly from the CLI without entering the REPL.** ```bash # Log in to your Anthropic account claude auth login # Check current authentication status (JSON by default, --text for readable output; exits 1 when logged out) claude auth status # Log out claude auth logout # Print a one-year subscription OAuth token for CI and scripts (not saved) claude setup-token ``` Supply the `setup-token` output as `CLAUDE_CODE_OAUTH_TOKEN`; [Initial Setup](#initial-setup) covers its plan requirements and limits. ---Agent Management CLI
> [!Note] > **`claude agents` manages live interactive and background sessions. It does not list the Markdown subagent definitions in `.claude/agents/`.** ```bash # Open the interactive background-agent view claude agents # Script active sessions; include completed sessions with --all claude agents --json claude agents --json --all # Start a prompt as a background session (in an untrusted folder it asks for trust, or exits if it can't ask) claude --bg "review this branch and report the findings" # Manage a background session by ID (attach and logs also accept part of its name) claude attachRemote Control
> [!Note] > **Remote Control lets claude.ai/code or the Claude mobile app control Claude Code processes that continue running on your machine. It is not a headless SDK or CI transport.** ```bash # Start a persistent local Remote Control server in this directory claude remote-control # Give the server a recognizable name claude remote-control --name my-workstation # Isolate on-demand sessions in git worktrees claude remote-control --spawn worktree # Bring back a session after stopping the server (works for about four hours) claude remote-control --continue # the session the server started with claude remote-control --session-idManaged Settings
> [!Note] > **Enterprise administrators can enforce organization-wide settings through server-managed policy, MDM/registry policy, or a system-level `managed-settings.json`.** **macOS (plist):** Settings can be deployed via MDM profiles to `/Library/Managed Preferences/com.anthropic.claudecode.plist`. **Windows (Registry):** Settings can be deployed via Group Policy as JSON in a `REG_SZ` (or `REG_EXPAND_SZ`) value named `Settings` under `HKLM\SOFTWARE\Policies\ClaudeCode`. The same value under user-writable `HKCU\SOFTWARE\Policies\ClaudeCode` is only a fallback, ignored whenever an admin policy (HKLM or a managed settings file) is present, even an invalid one. **Filesystem policy:** - macOS: `/Library/Application Support/ClaudeCode/managed-settings.json` - Linux/WSL: `/etc/claude-code/managed-settings.json` - Windows: `C:\Program Files\ClaudeCode\managed-settings.json` To split a file-based policy between teams, add `*.json` drop-ins to a `managed-settings.d/` directory beside it. Claude Code merges the main file first, then the drop-ins alphabetically (name them like `10-telemetry.json`): later single values win, lists combine, and nested blocks merge key by key. The legacy `C:\ProgramData\ClaudeCode\` path is not read. Managed settings take precedence over command-line, local, project, and user settings and cannot be overridden by individual users. Machine-local policy environment variables merge per key with server-delivered settings rather than being discarded wholesale. When several managed sources reach a machine, Claude Code by default (`managedSourcesBehavior: "first-wins"`) uses only the highest-ranked one that sets a policy key (remote settings from claude.ai or a Claude apps gateway, then MDM plist or HKLM, then `managed-settings.json` and drop-ins), apart from a few keys such as `env` that it reads from every source. Set `"managedSourcesBehavior": "merge"` in the top source to combine them; `/status` shows the source in use and any `Skipped sources`. A managed file, drop-in, plist, or HKLM value that isn't a valid JSON object stops Claude Code from starting, so validate policy JSON before you deploy it. **Commonly enforced policy keys:** - `allowedProviders` limits which API providers a machine may use, for example `["anthropic", "bedrock"]`. - `deniedModels` blocks specific models even when `availableModels` allows them; `availableModelsMatch: "exact"` makes each `availableModels` ID allow only the version it names, so new releases stay blocked until listed (both managed-only). - `modelPricing` makes cost figures in `/usage`, the status line, and telemetry use your contracted rates instead of list price. - `managedMcpServers` gives every user a set of HTTP/SSE MCP servers alongside their own. `allowedMcpServers` now governs only servers users add, so a `managed-mcp.json` server it used to filter out loads after an upgrade; list it in `deniedMcpServers` to keep it off. ---Model Updates
### Model Guidance > [!Note] > **Prefer aliases for interactive work and pin a full provider model ID only when reproducibility matters. Alias mappings vary by account, organization policy, provider, region, and Claude Code version.** | Alias | Current intent | | :---- | :------------- | | `default` | Account- and policy-appropriate default (currently Opus 5.5 everywhere except Microsoft Foundry, which uses Sonnet 4.5) | | `best` | The model `fable` resolves to when Fable is available to you, otherwise the same model as `opus` | | `fable` | Fable 5.1 (`claude-fable-5-1`); Fable 5 in Claude apps gateway sessions | | `opus` | Newest allowed Opus (currently Opus 5.5 on the Anthropic API) | | `sonnet` | Newest allowed Sonnet (currently Sonnet 5.5 on the Anthropic API) | | `haiku` | Newest allowed Haiku (currently Haiku 5.5 on the Anthropic API) | | `sonnet[1m]`, `opus[1m]` | 1M-context variants for models without a native 1M window; no effect on Sonnet 5+ or Opus 4.7+, which already have one | | `opusplan` | Opus for planning, then Sonnet for execution | **Use in Claude Code:** ```bash # Select for this launch claude --model sonnet claude --model opus # Inside a session; normally also saves the user default /model sonnet # Set a default from the prompt /config model=sonnet # Pin only when you need exact reproducibility claude --modelTheming & Customization
Claude Code supports built-in themes, custom named themes, and session accent colors. ```bash /theme # Pick a theme or create a custom one /color # Pick a random session accent color /color purple # red, blue, green, yellow, purple, orange, pink, or cyan /color default # Reset to the theme's 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. **Output styles** set Claude's tone, response format, and working style for a session. `/output-style` lists them and `/output-style concise` switches (also under `/config`); the choice is saved to `.claude/settings.local.json`. Built-ins are Proactive, Concise, Explanatory, and Learning; custom styles are Markdown files in `~/.claude/output-styles/` or `.claude/output-styles/`, and plugins can ship them. `maxProseWidth` caps prose width in wide terminals while tables and code blocks keep the full width. **Status line:** `/statusline show model, git branch and context % as a bar` has Claude Code write a script under `~/.claude/` and add it to your settings; with no argument it builds one from your shell prompt. To configure it yourself: ```json { "statusLine": { "type": "command", "command": "~/.claude/statusline.sh", "padding": 2 } } ``` The command receives session JSON on stdin, such as `model.display_name`, `context_window.used_percentage`, `cost.total_cost_usd`, `rate_limits`, and `prompt_cache`, and prints the line to show. A custom status line hides most footer hints, including `esc to interrupt`, and stays blank until you trust the folder. See [Customize your status line](https://code.claude.com/docs/en/statusline). ---Code Review
Claude Code has separate review paths for correctness, cleanup, and broader branch-level review. | Command | Behavior | | :------ | :--------------- | | `/code-review [level] [--fix] [--comment] [--max-findingsClaude Code Insights
> [!Note] > **The `/insights` command generates an interactive HTML report analyzing your recent Claude Code sessions on this machine.** **Run Insights:** ```bash # 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 ``` Each run analyzes up to 200 sessions it hasn't seen before (skipping very short ones), keeps a timestamped copy beside `report.html`, and uses your usual provider and account, so it counts against your plan or API usage. Reports are deleted after `cleanupPeriodDays` (30 days by default). Not available in cloud sessions. **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 Claude (the default Opus model, or the session model where the account can't reach it) to analyze transcripts and identify goals, satisfaction signals, friction points 4. **Report Generation** - Creates interactive HTML report with personalized suggestions **Report Sections:** | Section | Description | | :-------------------- | :---------------------------------------------------------- | | **What's Working** | Your strengths and successful patterns | | **What's Hindering** | Where Claude struggled or where you caused friction | | **Friction Analysis** | Breakdown of problem areas with specific examples | | **Stats Dashboard** | Tool usage, language breakdown, coding time distribution | | **Quick Wins** | Copy-paste suggestions for CLAUDE.md improvements | | **Features to Try** | Personalized recommendations (skills, hooks, headless mode), plus an estimate of permission prompts auto mode could have handled | > Source transcripts and the generated report remain stored locally, but transcript-derived material sent to the model leaves the machine and follows the active provider and account's data-use and retention policy. ---Artifacts
> [!Note] > **Artifacts turn session output, such as annotated diffs, dashboards, side-by-side options, or progress checklists, into a live page on claude.ai that updates as the session continues.** Claude may publish one on its own when a page suits the output, or you can ask: `Make an artifact that walks through this PR with the diff annotated inline.` - A new artifact is private to you. Share it from the page header with specific people or your whole organization (Team/Enterprise), or as a public link (on Team/Enterprise only after an Owner enables public sharing). - `/artifacts` lists the artifacts you own or that are shared with you; `Ctrl+]` reopens the session's most recent one. Set `CLAUDE_CODE_ARTIFACT_AUTO_OPEN=0` to stop the browser opening on publish. - Requires a Pro, Max, Team, or Enterprise plan, a claude.ai `/login`, and the Anthropic API (not Bedrock, Google Cloud's Agent Platform, or Foundry). Off by default with `claude -p`, in the Agent SDK and GitHub Action, and when `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` is set. To turn it off yourself, set `"enableArtifact": false` or `CLAUDE_CODE_DISABLE_ARTIFACT=1`. > [!Warning] > Claude builds the page from anything the session can read, including files and MCP connector data. Check what a page shows before you share it. See the [artifacts guide](https://code.claude.com/docs/en/artifacts). ---MCP Integration
Understanding MCP (Model Context Protocol)
#### What is MCP? > MCP extends Claude Code with tools and resources exposed by trusted local processes or remote services. MCP behavior to know: - **HTTP** is the recommended transport for remote servers and falls back to the deprecated **SSE** transport for servers that only speak it. **stdio** is for local processes. WebSocket (`ws`) is added only as JSON (`.mcp.json` or `claude mcp add-json`) and supports header auth, not OAuth. - MCP servers are available in `claude -p` workflows, including servers passed with `--mcp-config`; `--strict-mcp-config` ignores every other MCP source. A `-p` run shows no trust or approval prompt and connects a repository's `.mcp.json` servers even in an untrusted folder, so in repositories you don't control use `--bare` (only servers named on the command line) or `disabledMcpjsonServers`. It can't complete OAuth either; run `claude mcp loginclaude.ai MCP Connectors
Claude Code can use MCP servers configured in your claude.ai account, bringing cloud-hosted tools to your CLI workflow. ```bash # 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. Connectors load only with a claude.ai subscription login (not an API key, `apiKeyHelper`, Bedrock/Agent Platform/Foundry, or a `claude setup-token` token); check `/status` if one is missing. `"disableClaudeAiConnectors": true` in any settings file turns them off persistently; `/mcp` toggles one connector for the current project. #### Channels (research preview) A channel is an MCP server, installed as a plugin, that pushes events (chat messages, CI results, alerts) into an already running session so Claude can react and reply while you're away. The preview ships Telegram, Discord, and iMessage plugins (they need [Bun](https://bun.sh)). A channel delivers only when named at launch, e.g. `claude --channels plugin:telegram@claude-plugins-official`; being in `.mcp.json` isn't enough. Channels need claude.ai or Console API-key auth, aren't available on Bedrock/Agent Platform/Foundry, and Team/Enterprise admins must enable them (`channelsEnabled`). See [channels](https://code.claude.com/docs/en/channels).MCP Setup & Configuration
###### Basic MCP Commands ```bash claude mcp list # List and health-check configured servers claude mcp get|
### 1. Command Line Addition
> **Claude Code provides simple command line tools to add MCP servers:**
```bash
# Basic syntax (everything after -- is the server command)
claude mcp add [options] |
|
### 2. Direct Configuration File Editing
> Prefer `claude mcp add` because it writes the correct scope and transport schema. The example below is a shared project configuration.
**1. Choose the scope and file:**
- Shared project: ` |
| ### 3. Project-level Configuration (Recommended for team collaboration) > If you want team members to all use the same MCP configuration: ```bash # Add project-level MCP server claude mcp add shared-tools -s project -- npx -y @your-team/mcp-tools ``` **This will create a `.mcp.json` file in the project root directory:** ```json { "mcpServers": { "shared-tools": { "command": "npx", "args": ["-y", "@your-team/mcp-tools"], "env": {} } } } ``` |
Hooks System
Hooks run deterministic handlers at Claude Code lifecycle points. They execute with the user's privileges, so review project and plugin hooks as carefully as build scripts. > [!TIP] > Use the [hooks reference](https://code.claude.com/docs/en/hooks) for exact event schemas and the [hooks guide](https://code.claude.com/docs/en/hooks-guide) for worked examples.Configuration
Claude Code hooks are configured in [settings files](https://code.claude.com/docs/en/settings): - `~/.claude/settings.json` - User settings - `.claude/settings.json` - Project settings - `.claude/settings.local.json` - Local project settings (not committed) - Enterprise managed policy settings - Plugin `hooks/hooks.json`, while the plugin is enabled - Subagent frontmatter, only while that subagent runs (a `Stop` hook there becomes `SubagentStop`) - Skill frontmatter, from when the skill is invoked until the session ends (`once: true` removes a skill hook after its first successful run) > [!NOTE] > A plugin that registers in-process JavaScript hooks is a [mod](https://code.claude.com/docs/en/plugins/mods/overview) (see [React to events](https://code.claude.com/docs/en/plugins/mods/events)). The hooks on this page keep working alongside mods, but unless the machine has managed settings or the session uses Team or Enterprise `/login` credentials, a mod can approve a call your `PreToolUse` hook blocked. #### Structure Hooks are organized by matchers, where each matcher can have multiple hooks: ```json { "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: ```json { "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "http", "url": "https://hooks.example.com/validate", "timeout": 10 } ] } ] } } ``` HTTP hooks receive the same JSON as a POST body and return the normal JSON output schema. Five handler types are supported: `command`, `http`, `mcp_tool`, `prompt`, and experimental `agent`. All matching handlers run in parallel, though concurrent `prompt` and `agent` handlers are capped per session (see [Hook Execution Details](#hook-execution-details)). The same handler defined in several settings files runs once; a plugin's or skill's copy runs separately. `matcher` filters a field determined by the event. Tool events match tool names; other examples include session source, notification type, subagent type, config source, compaction trigger, target model (`PreModelSwitch`/`PostModelSwitch`, for example `claude-opus-5-5` or `.*opus.*`), and MCP server. Exact alternatives use `Edit|Write`; values containing other characters are JavaScript regular expressions, so `mcp__memory__.*` matches a server's tools. `*`, an empty string, or an omitted matcher matches every occurrence. Events such as `UserPromptSubmit`, `PostToolBatch`, `Stop`, `TaskCreated`, and `TaskCompleted` do not support matchers. On tool events (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied`), a handler-level `if` can further filter the full tool call with one permission rule, for example `"Bash(git *)"` or `"Edit(*.ts)"` (no `&&`/`||`); on any other event, a handler with `if` set never runs. A handler also supports `timeout` and `statusMessage`; command handlers support `command` plus optional exec-form `args` and `shell` (`"bash"` or `"powershell"`). `command` and `http` handlers accept `"onFailure": "block"` to fail closed (see [Hook Output](#hook-output)). Use `/hooks` to inspect the merged configuration and its source; the menu is read-only, but the VS Code extension's Hooks dialog can also edit user, project, and local hooks. For events that do not support matchers, omit the field: ```json { "hooks": { "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "/path/to/prompt-validator.py" } ] } ] } } ``` #### Project-Specific Hook Scripts You can use `${CLAUDE_PROJECT_DIR}` (the project root where the session started) to reference scripts stored in your project, ensuring they work regardless of Claude's current directory. It does not follow Claude into a worktree or after a `cd`; read the input's `cwd` field when a hook needs Claude's current directory: ```json { "hooks": { "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh", "args": [] } ] } ] } } ```Hook Events
The event surface is broader than tool pre/post processing. This is the current lifecycle map; consult the hooks reference for each event's matcher, input, and decision schema. | Lifecycle area | Events | | :------------- | :----- | | Session and setup | `Setup`, `SessionStart`, `SessionEnd`, `InstructionsLoaded` | | User and display | `UserPromptSubmit`, `UserPromptExpansion`, `MessageDisplay`, `Notification` | | Tools and permissions | `PreToolUse`, `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch` | | Agents and tasks | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | | Turn completion | `Stop`, `StopFailure` | | Workspace and config | `ConfigChange`, `CwdChanged`, `DirectoryAdded`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove` | | Context | `PreCompact`, `PostCompact` | | Model | `PreModelSwitch`, `PostModelSwitch` | | MCP interaction | `Elicitation`, `ElicitationResult` | Important behavior: - `PreToolUse` runs after tool arguments are formed but before execution and can allow, deny, ask, or rewrite supported inputs. `PostToolUse` and `PostToolUseFailure` cannot undo an operation that already ran. - `PermissionRequest` runs when Claude Code is about to ask for permission, and also where no prompt can be shown (background subagents, or `-p` runs outside `dontAsk` mode); there, a call no hook decides is denied. Answer with the [`decision` object](#permissionrequest-decision-control), not exit code `2`, from a `command` or `http` handler (`agent` handlers don't run on this event). `PermissionDenied` fires when auto mode denies a call; return `hookSpecificOutput.retry: true` to tell the model it may retry (ignored when the classifier gave no verdict). - `TaskCreated` refers to task-list creation and `TaskCompleted` to marking a task complete; they are not generic background-process completion events. The task tools are on by default only on Opus 4.7, Sonnet 4.6, Haiku 4.5, and earlier models (plus background and cloud sessions), so with current models such as Opus 5.5 `TaskCreated` doesn't fire in a regular session unless you opt in, for example with `CLAUDE_CODE_ENABLE_TODO_TOOLS=1`. - `WorktreeCreate` replaces the default creation behavior when configured, and any non-zero command-hook exit aborts creation. `WorktreeRemove` fires only when Claude Code removes a worktree a `WorktreeCreate` hook made (exiting a worktree session, `ExitWorktree`, deleting a background session, `claude remote-control` cleanup). It does not fire when a subagent or workflow agent finishes: those worktrees are kept, and Claude Code never deletes a hook-created branch, so clean them up yourself. - `UserPromptSubmit` runs before a skill or custom slash command expands, so blocking the prompt also stops that command's embedded `!` shell commands. To target one command, use `UserPromptExpansion`, which matches on the command name. - `PreModelSwitch` runs before a requested model switch (such as `/model`, `/config`, fast mode, or an SDK `set_model`) and can allow, deny, or ask via `hookSpecificOutput.permissionDecision`; exit `2`, `decision: "block"`, or a timeout (default 30 seconds) cancels it, and `ask` counts as a refusal outside an interactive `/model`. `PostModelSwitch` runs after any model change, including automatic fallback; it can't block, but its plain stdout or `additionalContext` reaches Claude with the next request. Both receive `from_model` and `to_model`. - Exit code `2` is the blocking status for most blockable command-hook events; exit code `1` and HTTP error statuses are non-blocking unless `"onFailure": "block"` is set (see [Hook Output](#hook-output)).Hook Input
Command hooks receive JSON on stdin; HTTP hooks receive the same object as the POST body. These are the common fields plus representative optional fields—each event adds its own schema: ```typescript { session_id: string; prompt_id?: string; transcript_path: string; // May lag the in-memory conversation cwd: string; permission_mode?: "default" | "plan" | "acceptEdits" | "auto" | "dontAsk" | "bypassPermissions"; effort?: { level: "low" | "medium" | "high" | "xhigh" | "max" }; hook_event_name: string; agent_id?: string; agent_type?: string; } ``` #### PreToolUse Input The exact schema for `tool_input` depends on the tool. ```json { "session_id": "abc123", "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/Users/...", "permission_mode": "default", "hook_event_name": "PreToolUse", "tool_name": "Write", "tool_input": { "file_path": "/path/to/file.txt", "content": "file content" }, "tool_use_id": "toolu_01ABC123" } ``` #### PostToolUse Input The exact schema for `tool_input` and `tool_response` depends on the tool. ```json { "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 ```json { "session_id": "abc123", "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/Users/...", "hook_event_name": "Notification", "message": "Claude needs your permission", "title": "Permission needed", "notification_type": "permission_prompt" } ``` `title` is optional; matchers filter on `notification_type` (for example `permission_prompt`, `idle_prompt`, or `agent_needs_input`). Notification hooks can't block, and their `systemMessage` and `continue` are discarded, but a returned `terminalSequence` is still emitted. #### UserPromptSubmit Input ```json { "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. As a backstop, Claude Code ends the turn after 8 consecutive stop-hook continuations with no tool call in between (`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` changes the cap; `0` disables it). The input also includes `background_tasks` and `session_crons`, so a hook can tell a finished session from one waiting on background work. ```json { "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` is what the user passes into `/compact`, or `null` when they pass nothing. For `auto` (which includes idle compaction), `custom_instructions` is `null`. ```json { "session_id": "abc123", "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "hook_event_name": "PreCompact", "trigger": "manual", "custom_instructions": null } ``` #### SessionStart Input `source` is `startup`, `resume`, `clear`, `compact`, or `fork`; optional fields include `model`, `agent_type` (with `--agent`), and `session_title`. Resuming or forking a transcript that already has a response adds staleness and cost fields (`seconds_since_last_response`, `context_tokens`, `prompt_cache_likely_expired`, `estimated_cache_write_usd`), so a hook can warn before an expensive re-cache. ```json { "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. If stdout is a JSON object, Claude Code parses it as structured output; malformed `{...}` stdout is reported as a hook error. Plain stdout is normally debug-only; for `UserPromptSubmit`, `UserPromptExpansion`, `SessionStart`, and `PostModelSwitch`, it is added to Claude's context. - **Exit code 2**: blocking status for events that can still be blocked, with stderr as the reason. JSON on stdout is still read but can't override the block. - **Other exit codes**: normally a non-blocking hook error; the action continues. If stdout is valid JSON, the JSON decides instead (unless `onFailure: "block"` is set). `WorktreeCreate` (any non-zero exit aborts creation) and `WorktreeRemove` (non-zero fails removal if the directory remains) are exceptions. > [!WARNING] > By default, a conventional `exit 1`, a missing script, a crash, a timeout, invalid JSON, or an HTTP hook's connection failure or non-2xx status does not enforce policy for most events: the action goes ahead. Use exit `2` or exit `0` with the event's structured JSON decision, and set `"onFailure": "block"` on `command` or `http` policy hooks (v2.1.295+) so any such failure acts like exit `2` (on `PermissionRequest`, it denies). It has no effect on `Stop`, `SubagentStop`, `TaskCompleted`, `TeammateIdle`, or `async`/`asyncRewake` hooks. ##### Exit Code 2 Behavior | Event class | Exit-code-2 behavior | | :---------- | :------------------- | | `PreToolUse` | Blocks the tool call | | `PermissionRequest` | Not honored (stderr is discarded); deny through the `decision` object instead | | `PreModelSwitch` | Cancels the model switch and shows stderr to the user | | `UserPromptSubmit`, `UserPromptExpansion` | Blocks the prompt or expansion | | `Stop`, `SubagentStop`, `TeammateIdle` | Prevents stopping/idle so work can continue | | `TaskCreated`, `TaskCompleted`, `ConfigChange`, `PostToolBatch`, `PreCompact` | Blocks or rolls back the pending transition | | `Elicitation`, `ElicitationResult` | Denies the request or changes the response to decline | | `PostToolUse`, `PostToolUseFailure` | Cannot undo the call; sends stderr to Claude | | Non-blocking lifecycle events | Shows/logs the error but allows the lifecycle event | `StopFailure` ignores hook output. `PermissionDenied` has already happened and reads only `hookSpecificOutput.retry`. Refer to the official per-event table before relying on blocking semantics. #### 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: ```json { "continue": true, "stopReason": "Reason shown when continue is false", "systemMessage": "Visible warning for the user" } ``` `continue` defaults to `true`. `stopReason` is shown to the user when `continue` is false and stays in the conversation, so Claude sees it if work continues. `suppressOutput` is accepted but has no effect. 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. - Wherever an event honors it, `"continue" = false` takes precedence over any `"decision": "block"` output. Some events ignore it, including `TaskCreated`, `ConfigChange`, `PreCompact`, `WorktreeRemove`, and side-effect events such as `Notification`. ##### `PreToolUse` Decision Control `PreToolUse` hooks can control whether a tool call proceeds. - `"allow"` skips the permission prompt, not the permission system: deny and ask rules (including managed ones) still apply, and some calls, such as network-path reads and plan-mode writes, are handled as if no hook ran. `permissionDecisionReason` goes only to the debug log. (_Deprecated `"approve"` maps to `"allow"`._) - `"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. - `"defer"` preserves the pending call for a later `-p --resume` round trip; it is honored only in non-interactive print mode. - When hooks disagree, precedence is `deny` > `defer` > `ask` > `allow`. - `updatedInput` replaces the complete tool input before execution; include every unchanged field. It works with `"allow"` or `"ask"`; permission rules check the rewritten input, unknown keys are dropped, and input the tool rejects denies the call. `additionalContext` adds context alongside the result. ```json { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "My reason here", "additionalContext": "Optional context for Claude" } } ``` The old top-level `decision: "approve"|"block"` and `reason` fields remain compatibility aliases for `PreToolUse` but are deprecated. ##### `PermissionRequest` Decision Control `PermissionRequest` hooks answer the permission prompt through a `decision` object inside `hookSpecificOutput` (exit code `2` is not honored here). - `behavior` is `"allow"` or `"deny"`; `"allow"` doesn't override a matching deny or ask rule. - With `"allow"`, `updatedInput` replaces the whole tool input, and `updatedPermissions` applies updates such as `addRules`, `setMode`, or `addDirectories` to a `destination` (`session`, `localSettings`, `projectSettings`, or `userSettings`). - With `"deny"`, `message` tells Claude why, and `interrupt: true` stops Claude. ```json { "hookSpecificOutput": { "hookEventName": "PermissionRequest", "decision": { "behavior": "allow", "updatedInput": { "command": "npm run lint" } } } } ``` ##### `PostToolUse` Decision Control `PostToolUse` hooks can provide feedback or stop the turn after a successful tool call; they cannot undo the call. - `"block"` automatically prompts Claude with `reason`. - `undefined` does nothing. `reason` is ignored. ```json { "decision": "block", "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. ```json { "decision": "block", "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. ```json { "decision": "block", "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. ```json { "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 ```python #!/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(0) # Validate the command issues = validate_command(command) if issues: for message in issues: print(f"• {message}", file=sys.stderr) # Exit code 2 blocks tool call and shows stderr to Claude sys.exit(2) ``` ##### JSON Output Example: UserPromptSubmit to Add Context and Validation > [!NOTE] > For `UserPromptSubmit` hooks, you can inject context using either method: > > - Exit code 0 with stdout: Claude sees the context (special case for `UserPromptSubmit`) > - JSON output: Provides more control over the behavior ```python #!/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 ```python #!/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 reads of plain-text documentation files if tool_name == "Read": file_path = tool_input.get("file_path", "") if file_path.endswith((".md", ".mdx", ".txt")): # Use the current PreToolUse schema to auto-approve the tool call output = { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "allow", "permissionDecisionReason": "Plain-text documentation file auto-approved", }, } 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](https://code.claude.com/docs/en/mcp). 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__Examples
> [!TIP] > For practical examples including code formatting, notifications, and file protection, see the [hooks guide](https://code.claude.com/docs/en/hooks-guide).Security Considerations
#### Disclaimer Command hooks execute arbitrary processes with the same user privileges as Claude Code; HTTP and MCP-tool hooks can send event data to external services. Review project, plugin, skill, and agent hooks before trusting their source. A hook is not sandboxed merely because the Bash tool is sandboxed. #### Workspace Trust Interactive sessions hold back hooks from every settings file, even `~/.claude/settings.json`, until you accept the folder's workspace trust dialog. `-p` and SDK runs (CI jobs included) never show the dialog, yet a repository's committed `.claude/settings.json` hooks still run (its `permissions.allow` rules don't; see [Security & Permissions](#security--permissions)). Before you script `claude -p` over a repository you didn't write, review its `.claude/` settings, start with `--bare`, or pass `--settings '{"disableAllHooks": true}'`.Hooks Security Considerations
Here are some key practices for writing more secure hooks: 1. **Treat hook input as untrusted data** - Parse JSON and validate by type and intent; a substring check for `..` is not a complete path-boundary check. 2. **Prefer exec-form arguments** - Keep executable and arguments separate; otherwise quote every shell expansion. 3. **Resolve and constrain paths** - Compare canonical paths against an explicit allowed root, and use `${CLAUDE_PROJECT_DIR}` for project scripts. 4. **Keep secrets out of config and output** - Use secret managers and a handler's HTTP `allowedEnvVars`; administrators can narrow the global ceiling with `httpHookAllowedEnvVars`. Hook stdout can enter logs or model context. 5. **Apply managed controls where needed** - Administrators can restrict hook sources with `allowManagedHooksOnly` and allowlist HTTP hook URLs/environment variables. #### Configuration Safety Direct settings edits are normally picked up by the file watcher. `/hooks` is a read-only browser for the merged configuration and its source; edit the originating settings, plugin, skill, or agent file to change it. Project subagent hooks do not run until the workspace that supplied the agent definition has been trusted; a `-p` run doesn't count as accepting trust. To pause every hook without deleting it, set `"disableAllHooks": true`. Normal precedence applies (a project's `false` overrides your user-level `true`; `--settings` wins for one run), and only managed settings can disable managed hooks.Hook Execution Details
- **Timeouts**: default 600 seconds for `command`, `http`, and `mcp_tool` (30 on `UserPromptSubmit` and the model-switch events, 10 on `MessageDisplay`); 30 seconds for `prompt`; 60 seconds for `agent`. `SessionEnd` hooks share a 1.5-second budget unless a per-hook `timeout` raises it (up to 60 seconds). - A timed-out hook is canceled and its output discarded; see the warning under [Hook Output](#hook-output) to make timeouts block. - A handler timeout does not cancel other parallel handlers. - **Parallelization**: Matching hooks run in parallel, but `prompt` and `agent` hooks are throttled per session (24 at once, subagents included, plus up to 12 that have waited past their event's timeout); a queued hook's `timeout` starts when it starts. - **Background hooks**: `"async": true` (command hooks only) runs the hook without blocking Claude; it can't block the action, and its output reaches Claude on the next turn. With `"asyncRewake": true`, exit `2` also wakes Claude with the hook's stderr. - **Environment**: Runs in current directory with Claude Code's environment - `${CLAUDE_PROJECT_DIR}` is the project root where the session started; it doesn't follow Claude into a worktree or after `cd` (read the input's `cwd` for that). - `SessionStart`, `Setup`, `CwdChanged`, and `FileChanged` hooks can append `export` lines to `$CLAUDE_ENV_FILE` to set variables for later Bash commands. - **Input**: JSON via stdin for command hooks or an HTTP POST body for HTTP hooks - **Output**: stdout counts as JSON only when it is a single JSON object with nothing around it; see [Hook Output](#hook-output) for how it combines with exit codes. HTTP hooks need a 2xx response with an empty or JSON-object body. - `additionalContext`, `systemMessage`, and plain stdout are capped at 10,000 characters each; Claude gets longer output as a file path plus a 2,000-character preview.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='hooks'` or `claude --debug-file ./claude-hooks.log` 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 - **JSON silently ignored** - Text printed before the JSON (often a shell-profile `echo`) or a misplaced field (`permissionDecision` outside `hookSpecificOutput`); search the debug log for `Hook output does not start with {` or `Hook JSON output had unrecognized keys` - **Skill hooks missing from `/hooks`** - Frontmatter hooks register only after the skill is invoked - **Windows: `blocking because Git Bash wasn't found`** - Without Git Bash, a failing `PreToolUse` or `PermissionRequest` command hook blocks the call; install Git for Windows (or set `CLAUDE_CODE_GIT_BASH_PATH`), or set `"onFailure": "continue"` to let calls through #### Advanced Debugging For complex hook issues: 1. **Inspect hook execution** - Use `claude --debug='hooks'` 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 `claude --debug` (or `--debug='hooks'`) writes to `~/.claude/debug/Security & Permissions
Use `/permissions` to inspect the merged rules and the settings file each rule came from. Rules are evaluated in fixed order—**deny**, then **ask**, then **allow**—so a narrower allow rule cannot override a broader matching deny or ask rule. Instructions in prompts or `CLAUDE.md` influence model behavior but do not grant permissions. #### Tool Permission Patterns ```bash # Allow specific tools (read/edit files) claude --allowed-tools "Read" "Edit" # Bare "Bash" pre-approves EVERY shell command; prefer the scoped rules below claude --allowed-tools "Read" "Edit" "Bash" # Scoped permissions (all git commands) claude --allowed-tools "Bash(git *)" # Multiple scopes (git + npm) claude --allowed-tools "Bash(git *)" "Bash(npm *)" # Allow rules only skip prompts; --tools limits which built-in tools exist at all claude --tools "Read,Edit,Bash" ``` Persistent settings use `Tool` or `Tool(specifier)` rules: ```json { "permissions": { "allow": ["Bash(npm run *)", "Edit(/src/**)"], "ask": ["Bash(git push *)"], "deny": ["Read(//**/.env)", "Bash(rm *)"] } } ``` - `Edit(path)` covers built-in file-editing tools and `Read(path)` covers built-in readers; path-qualified `Write`, `NotebookEdit`, `Glob`, or `MultiEdit` rules never match. A `Read` deny also blocks Edit and Write (not NotebookEdit) on that path. - A single leading `/` anchors at the settings source: the working directory for project and local settings, `~/.claude/` for user settings. Use `//` for absolute paths. - Bash and PowerShell compound commands are parsed by subcommand, and every subcommand must be allowed. Put `*` after the subcommand: `Bash(git * main)` also matches every subcommand and inserted options such as `-c` (Claude Code warns at startup). - Project `permissions.allow` rules and `additionalDirectories` wait for the interactive workspace trust dialog, so `claude -p` and SDK runs in a never-trusted checkout (such as CI) ignore them with a `this workspace has not been trusted` warning; pass rules with `--allowedTools` or `--settings` there. Deny and ask rules always apply. - Auto mode sets aside allow rules that amount to arbitrary code execution (bare `Bash`/`Bash(*)`, `PowerShell(*)`, interpreter wildcards like `Bash(python*)`, package-manager runs like `Bash(npm run *)`, `Agent`, `Monitor`) until you leave it; narrow rules like `Bash(npm test)` still apply. Permission rules are an application boundary for built-in tools, not an OS boundary for arbitrary scripts—use the sandbox for process-level filesystem/network enforcement. `permissions.blockReadsOutsideWorkingDirectories: true` makes the file tools refuse reads outside the working directories in every mode, bypass included. Permission modes are `manual`/`default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, and `bypassPermissions`. Auto mode classifies tool calls in the background; `dontAsk` denies anything not pre-approved. With no mode configured, interactive terminal and VS Code sessions start in `auto`; `claude -p` and Agent SDK runs start in `default` and deny any call that needs approval unless an allow rule, hook, `canUseTool` callback, or `--permission-prompt-tool` approves it. Set the mode with `--permission-mode` or `permissions.defaultMode` (a repository's `.claude/` settings can't select `auto` or `bypassPermissions`). See the [permissions reference](https://code.claude.com/docs/en/permissions) for current rule matching and mode details.Dangerous Mode
> [!Warning] > Use bypass mode only in an isolated container or VM whose credentials, network, mounts, and data are intentionally disposable. It skips normal permission prompts, including writes to protected paths. > > `claude --dangerously-skip-permissions` Deny rules still apply; allow rules have no effect. Explicit `ask` rules, organization-gated connector tools, `AskUserQuestion`, and MCP tools marked as requiring user interaction still prompt, as does `rm`/`rmdir` on a critical path such as `/`, a top-level directory or drive root, your home directory, or the working directory and its parents. Unanswered, the terminal prompt denies after two minutes with a safer-rewrite hint (launch with `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT=1` to remove the limit); VS Code and the Desktop app deny at once. On Linux and macOS, bypass mode refuses to start as root or under `sudo` outside a recognized sandbox, so run containers as a non-root user. `--allow-dangerously-skip-permissions` adds bypass to the Shift+Tab cycle without starting in it. Administrators can block bypass and auto modes by setting `permissions.disableBypassPermissionsMode` and `permissions.disableAutoMode` to `"disable"` in managed settings.Automation & Integration
Automation & Scripting with Claude Code
> GitHub Actions you can copy/paste :p 1. Run `/install-github-app` for guided setup (github.com only; needs repo admin access and `gh auth login`). To set up manually, install the [Claude GitHub App](https://github.com/apps/claude); the Claude Code Action authenticates as it unless you pass `github_token`, hence `id-token: write`. 2. In your repo, add a secret **`ANTHROPIC_API_KEY`** (a Claude Console API key) under Settings → Secrets and variables → Actions → New repository secret. The Claude Code Action can use a subscription token from `claude setup-token` instead (secret `CLAUDE_CODE_OAUTH_TOKEN`, input `claude_code_oauth_token`); the other two workflows need the API key. 3. Copy the workflows below into **`.github/workflows/`**. 4. Open a **test PR** (or a new issue) to see them run. > [!NOTE] > These workflows are GitHub Actions only. On GitLab, use the GitLab-maintained [Claude Code GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd) integration (beta). > [!TIP] > Tags such as `@v1` and `@main` are convenient but mutable. A reviewed full-length commit SHA is the only immutable Action reference; replace the example tags below with verified SHAs for production or high-assurance workflows.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` ```yaml name: Auto review PRs on: pull_request: types: [opened, synchronize, reopened, ready_for_review] permissions: contents: read pull-requests: write id-token: write jobs: auto-review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 with: fetch-depth: 1 - name: Claude PR review uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} # Claude will fetch the diff and leave inline comments prompt: | REPO: ${{ github.repository }} PR NUMBER: ${{ github.event.pull_request.number }} Review this pull request’s diff for correctness, readability, testing, performance, and DX. Prefer specific, actionable suggestions. Use inline comments where relevant. claude_args: | --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)" ```Security Review on Every PR
> **Runs a focused security scan and comments findings directly on the PR.** > [!WARNING] > The dedicated security-review Action is not hardened against prompt injection. Run it only on trusted PRs and turn on **Require approval for all external contributors**. Public repositories withhold secrets from fork PR runs, so the job reviews only same-repository branches; on private repositories, leave **Send secrets to workflows from pull requests** off. > [!TIP] > No workflow needed: `/security-review` checks the current branch, the `security-guidance` plugin reviews Claude's edits in-session, the `claude-security` plugin runs a multi-agent scan with patches (`/plugin installIssue 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` ```yaml name: Claude Issue Triage on: issues: types: [opened, edited, reopened] permissions: contents: read issues: write jobs: triage: runs-on: ubuntu-latest env: CLAUDE_MODEL: claude-sonnet-5-5 steps: - name: Collect context & similar issues id: gather env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} ISSUE_TITLE: ${{ github.event.issue.title }} ISSUE_BODY: ${{ github.event.issue.body }} run: | # naive similar search by title words Q=$(printf '%s' "$ISSUE_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 printf '%s' "$ISSUE_TITLE" > title.txt printf '%s' "$ISSUE_BODY" > body.txt - name: Ask Claude for triage JSON env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: | jq -n \ --arg model "$CLAUDE_MODEL" \ --arg title "$(cat title.txt)" \ --arg body "$(cat body.txt)" \ --arg sims "$(cat similars.json)" \ '{ model: $model, max_tokens: 16000, system: "You are a pragmatic triage engineer. Be specific and 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 (brief string). Do not include extra keys.\n\nIssue title:\n" + $title + "\n\nIssue body:\n" + $body + "\n\nSimilar issues (JSON):\n" + $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 # Current models can return a thinking block before the text block jq -r '.content[]? | select(.type == "text") | .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@v9 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@v9 with: script: | const fs = require('fs') const triage = JSON.parse(fs.readFileSync('triage.json','utf8')) const md = `### 🤖 Triage - **Suggested labels:** ${triage.labels?.join(', ') || '—'} - **Severity:** ${triage.severity || '—'} ${triage.duplicate_url ? `- **Possible duplicate:** ${triage.duplicate_url}\n` : ''} --- ${triage.comment_markdown || ''}` await github.rest.issues.createComment({ owner: context.repo.owner, repo: context.repo.repo, issue_number: context.issue.number, body: md }) ``` > [!NOTE] > The triage workflow posts a **suggestion comment** by default. Flip the `Apply labels` step to `true` if you want labels applied automatically. > > ### Configuration & Customization > > - **Model selection**: the triage workflow and the security-review Action's `claude-model` need a Claude API model ID such as `claude-sonnet-5-5` (or `claude-haiku-5-5` for cheaper triage), not Claude Code aliases like `sonnet`. Current models think by default and thinking counts toward `max_tokens`, hence the 16000 limit and reading the `text` block. > - **Secrets**: `ANTHROPIC_API_KEY` is required (the Claude Code Action can use `claude_code_oauth_token` instead). The built‑in `GITHUB_TOKEN` is sufficient for posting comments and applying labels. > - **Permissions**: each workflow declares the privileges it needs (`pull-requests: write` and/or `issues: write`, plus `id-token: write` for the Claude Code Action's GitHub App authentication). Adjust only if your org requires stricter policies. > - **Scope**: use `paths:` filters on triggers to limit when workflows run (e.g., only for `/src` or exclude `/docs`). > > ### Troubleshooting > > Check the **Actions logs** first—most issues are missing secrets/permissions or a mis‑indented YAML block. > > - **No comments appear on PRs**: Verify the Claude GitHub App is installed and the workflow has `pull-requests: write` permission. > - **Auto review fails for some PRs**: the Claude Code Action rejects triggering users without write access (set `allowed_non_write_users` and pass your own `github_token`) and bots such as Dependabot unless listed in `allowed_bots`. Fork PRs on public repositories get no secrets, so they always fail. > - **403 when applying labels**: Ensure the job or step has `issues: write`. The default `GITHUB_TOKEN` must have access to this repo. > - **Anthropic API errors**: Confirm `ANTHROPIC_API_KEY` is set at repository (or org) level and not expired. > - **“YAML not well‑formed”**: Validate spacing—two spaces per nesting level; no tabs. ---Help & Troubleshooting
> [!TIP] > **Q: `claude` is installed but the command is not found. What should I check?** > > > **A:** Open a new terminal, locate every installation with `Get-Command claude -All` (PowerShell) or `which -a claude` (Bash/Zsh), and ensure the native launcher directory is on `PATH`. See [`Windows`](#windowspath) or [`macOS/Linux`](#linuxpath). > > **Q:** **Which Node.js version do I need?** > > > **A:** Native, Homebrew, WinGet, apt, dnf, and apk installations do not need Node.js. The npm installation requires **Node.js 22+** as of Claude Code v2.1.198, and npm 12 needs one extra step (see [Installation / Node.js Issues](#installation--nodejs-issues)). > > **Q: Where do I see diagnostics and logs?** > > > **A:** Run `claude doctor` for a read-only health report, `/doctor` inside a session for a checkup that can offer fixes, and `/status` for the active login and settings sources. Debug logging is off by default: launch with `claude --debug` or `claude --debug-file
Debug Quick Commands_`claude doctor` checks the install, auto-updates, settings files, and Remote Control eligibility. Debug logs go to `~/.claude/debug/ |
Path Temp Fix**The native launcher normally lives in `.local/bin`. Add that directory for the current shell, then reinstall if the launcher is absent.** > [!Note] > > #### Windows (CMD): > > ```bash > set PATH=%USERPROFILE%\.local\bin;%PATH% > where.exe claude > claude --version > ``` > > #### Windows (PowerShell): > > ```powershell > $env:Path = "$env:USERPROFILE\.local\bin;$env:Path" > Get-Command claude -All > claude --version > ``` > > #### Linux/MacOS (bash/zsh) > > ```bash > export PATH="$HOME/.local/bin:$PATH" > which -a claude > claude doctor > ``` For an npm installation only, the launcher is under the global npm prefix. Prefer migrating with `claude install` (`claude install stable` also moves auto-updates to the stable channel); otherwise inspect the prefix with `npm prefix -g` and add its executable directory to `PATH`. |
Windows Path Perm Fix**Replace ` |
Installation / Node.js Issues**Native repair (recommended; no Node.js required)** ```bash claude doctor claude install --force stable ``` The channel you pass also becomes your auto-update channel. `latest` is the default; a newly launched model can need a newer version than `stable` serves. **Package-manager installs** ```bash brew upgrade claude-code # or claude-code@latest winget upgrade Anthropic.ClaudeCode sudo apt update && sudo apt upgrade claude-code # Debian/Ubuntu sudo dnf upgrade claude-code # Fedora/RHEL apk update && apk upgrade claude-code # Alpine ``` **npm install (Node.js 22+)** ```bash node --version npm --version npm install -g @anthropic-ai/claude-code@latest ``` > [!Warning] > **npm 12 skips Claude Code's postinstall step by default**, so `claude` stays a placeholder that prints `Error: claude native binary not installed.` (on Windows the shell can't run it). Switch to the native installer and run `npm uninstall -g @anthropic-ai/claude-code`, or allow the step for your user and reinstall (update npm 12.0.x to 12.1+ first): > > ```bash > npm config get allow-scripts # add any packages listed here to the next command's list > npm config set "allow-scripts=@anthropic-ai/claude-code" --location=user > npm install -g @anthropic-ai/claude-code@latest > ``` > > The same error appears when optional dependencies are skipped (`--omit=optional`, or `optional=false` in `.npmrc`), because the native binary ships as one. Do not use `sudo npm install -g`. If two installations conflict, locate both before removing the one you no longer want. |
Authentication Issues> Subscription users should authenticate through the browser flow. API keys and third-party provider credentials are separate deployment paths. ```bash claude auth status claude auth login claude auth login --console # Console/API billing instead of subscription login claude auth logout # Then log in again to reset a broken login ``` If a subscription login unexpectedly behaves like API billing, another credential is outranking it. Claude Code uses the first it finds: a cloud provider (`CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, or `CLAUDE_CODE_USE_FOUNDRY`), `ANTHROPIC_AUTH_TOKEN`, an approved `ANTHROPIC_API_KEY` (always used with `-p`; toggle **Use custom API key** in `/config`), `apiKeyHelper`, `CLAUDE_CODE_OAUTH_TOKEN`, a profile named in `ANTHROPIC_PROFILE` or federation credentials, and only then your `/login`. A signed-in Claude apps gateway session outranks all of them. `/status` (or `authMethod` in `claude auth status`) shows which one is active. Do not print secret values into logs. While API-key or provider auth is active, the subscription-only features listed under [Initial Setup](#initial-setup) stay unavailable. If the browser doesn't open or ends on a failed `localhost` page (WSL2, SSH, containers), press `c` at the login prompt to copy the URL, open it on your local machine, and paste the code it shows at `Paste code here`; if pasting does nothing, use `claude auth login`, which reads the code from standard input. On macOS, if `claude doctor` warns `macOS Keychain is not writable`, run `security unlock-keychain ~/Library/Keychains/login.keychain-db`. Use `claude --debug-file ./claude-auth-debug.log` for a reproducible error report, then remove credentials from that log before sharing it. |
Permission / Allowed Tools Issues**Inspect permissions** ```bash /permissions ``` The UI shows each allow/ask/deny rule and its source, and also opens mid-turn (changes apply from Claude's next tool call). In auto mode, **Recently denied** lists blocked actions (`r` retries one with manual approval), and the **Auto mode** tab edits the classifier rules. To reset a scope, edit the originating `settings.json` and remove the rules or set empty arrays: ```json { "permissions": { "allow": [], "ask": [], "deny": [] } } ``` |
MCP (Model Context Protocol) Issues> **Debug MCP servers** Start with `/mcp`: it shows each server's status, approves `.mcp.json` servers whose approval prompt was dismissed, and offers **Reconnect** for a server that connects but lists no tools. A server that fails to start often has a relative path in `command` or `args`, which resolves against your launch directory; use absolute paths. ```bash claude --debug='mcp' claude --debug-file ./claude-mcp-debug.log ``` > **List & remove MCP servers** ```bash claude mcp list claude mcp get |
Repair or Reinstall (Windows / PowerShell)Start with a non-destructive repair. This preserves settings, MCP configuration, credentials, sessions, and project history: ```powershell claude doctor claude install --force stable # or latest; this also sets your auto-update channel Get-Command claude -All claude --version ``` If `claude` itself won't start, rerun the installer with `irm https://claude.ai/install.ps1 | iex`. For WinGet, use `winget upgrade Anthropic.ClaudeCode` or reinstall that package. For npm, use Node.js 22+ and `npm install -g @anthropic-ai/claude-code@latest`; on npm 12, follow the [npm 12 warning](#installation--nodejs-issues) first. > [!Caution] > Do not delete `~/.claude`, `~/.claude.json`, project `.claude/`, or `.mcp.json` as a routine installation fix. Those paths contain settings, credentials, MCP configuration, trust decisions, session history, and data shared by the CLI, IDE integrations, and Desktop. Follow the [official uninstall instructions](https://code.claude.com/docs/en/setup#uninstall-claude-code) and back up anything you need before intentionally removing user data. |
One‑Shot Health Check (copy/paste)**Windows (PowerShell):** ```powershell Get-Command claude -All claude --version claude doctor claude auth status ``` **macOS/Linux (bash/zsh):** ```bash which -a claude claude --version claude doctor claude auth status ``` |
Appendix: Useful Paths- **Native launcher:** Windows `%USERPROFILE%\.local\bin\claude.exe`; macOS/Linux/WSL `~/.local/bin/claude` - **Native versions:** `%USERPROFILE%\.local\share\claude\` or `~/.local/share/claude/versions/` - **User settings:** `~/.claude/settings.json` - **Claude state, sessions, and caches:** `~/.claude/` (`CLAUDE_CONFIG_DIR` relocates it together with `~/.claude.json`) - **Credentials:** macOS Keychain; Linux and Windows `~/.claude/.credentials.json` (also the macOS fallback when the Keychain rejects writes) - **Debug logs:** `~/.claude/debug/ |