Anthropic - Claude Code Docs Changes

agent-sdk/agent-loop.md +7 −6

Details

51* **`AssistantMessage`:** emitted after each Claude response, including the final text-only one. Contains text content blocks and tool call blocks from that turn.51* **`AssistantMessage`:** emitted after each Claude response, including the final text-only one. Contains text content blocks and tool call blocks from that turn.

52* **`UserMessage`:** emitted after each tool execution with the tool result content sent back to Claude. Also emitted for any user inputs you stream mid-loop.52* **`UserMessage`:** emitted after each tool execution with the tool result content sent back to Claude. Also emitted for any user inputs you stream mid-loop.

53* **`StreamEvent`:** only emitted when partial messages are enabled. Contains raw API streaming events (text deltas, tool input chunks). See [Stream responses](/en/agent-sdk/streaming-output).53* **`StreamEvent`:** only emitted when partial messages are enabled. Contains raw API streaming events (text deltas, tool input chunks). See [Stream responses](/en/agent-sdk/streaming-output).

54* **`ResultMessage`:** the last message, always. Contains the final text result, token usage, cost, and session ID. Check the `subtype` field to determine whether the task succeeded or hit a limit. See [Handle the result](#handle-the-result).54* **`ResultMessage`:** marks the end of the agent loop. Contains the final text result, token usage, cost, and session ID. Check the `subtype` field to determine whether the task succeeded or hit a limit. A small number of trailing system events, such as `prompt_suggestion`, can arrive after it, so iterate the stream to completion rather than breaking on the result. See [Handle the result](#handle-the-result).

55 55

56These five types cover the full agent loop lifecycle in both SDKs. The TypeScript SDK also yields additional observability events (hook events, tool progress, rate limits, task notifications) that provide extra detail but are not required to drive the loop. See the [Python message types reference](/en/agent-sdk/python#message-types) and [TypeScript message types reference](/en/agent-sdk/typescript#message-types) for the complete lists.56These five types cover the full agent loop lifecycle in both SDKs. The TypeScript SDK also yields additional observability events (hook events, tool progress, rate limits, task notifications) that provide extra detail but are not required to drive the loop. See the [Python message types reference](/en/agent-sdk/python#message-types) and [TypeScript message types reference](/en/agent-sdk/typescript#message-types) for the complete lists.

57 57

133* **`disallowed_tools` / `disallowedTools`** blocks listed tools, regardless of other settings. See [Permissions](/en/agent-sdk/permissions) for the order that rules are checked before a tool runs.133* **`disallowed_tools` / `disallowedTools`** blocks listed tools, regardless of other settings. See [Permissions](/en/agent-sdk/permissions) for the order that rules are checked before a tool runs.

134* **`permission_mode` / `permissionMode`** controls what happens to tools that aren't covered by allow or deny rules. See [Permission mode](#permission-mode) for available modes.134* **`permission_mode` / `permissionMode`** controls what happens to tools that aren't covered by allow or deny rules. See [Permission mode](#permission-mode) for available modes.

135 135

136You can also scope individual tools with rules like `"Bash(npm:*)"` to allow only specific commands. See [Permissions](/en/agent-sdk/permissions) for the full rule syntax.136You can also scope individual tools with rules like `"Bash(npm *)"` to allow only specific commands. See [Permissions](/en/agent-sdk/permissions) for the full rule syntax.

137 137

138When a tool is denied, Claude receives a rejection message as the tool result and typically attempts a different approach or reports that it couldn't proceed.138When a tool is denied, Claude receives a rejection message as the tool result and typically attempts a different approach or reports that it couldn't proceed.

139 139

161The `effort` option controls how much reasoning Claude applies. Lower effort levels use fewer tokens per turn and reduce cost. Not all models support the effort parameter. See [Effort](https://platform.claude.com/docs/en/build-with-claude/effort) for which models support it.161The `effort` option controls how much reasoning Claude applies. Lower effort levels use fewer tokens per turn and reduce cost. Not all models support the effort parameter. See [Effort](https://platform.claude.com/docs/en/build-with-claude/effort) for which models support it.

162 162

164| :--------- | :-------------------------------- | :------------------------------------------ |164| :--------- | :-------------------------------- | :------------------------------------------------ |

165| `"low"` | Minimal reasoning, fast responses | File lookups, listing directories |165| `"low"` | Minimal reasoning, fast responses | File lookups, listing directories |

168| `"xhigh"` | Extended reasoning depth | Coding and agentic tasks; recommended on Opus 4.7 |

168| `"max"` | Maximum reasoning depth | Multi-step problems requiring deep analysis |169| `"max"` | Maximum reasoning depth | Multi-step problems requiring deep analysis |

169 170

170If you don't set `effort`, the Python SDK leaves the parameter unset and defers to the model's default behavior. The TypeScript SDK defaults to `"high"`.171If you don't set `effort`, the Python SDK leaves the parameter unset and defers to the model's default behavior. The TypeScript SDK defaults to `"high"`.

203Here's how each component affects context in the SDK:204Here's how each component affects context in the SDK:

204 205

206| :----------------------- | :------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------- |207| :----------------------- | :------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------- |

208| **CLAUDE.md files** | Session start, when [`settingSources`](/en/agent-sdk/claude-code-features) is enabled | Full content in every request (but prompt-cached, so only the first request pays full cost) |209| **CLAUDE.md files** | Session start, via [`settingSources`](/en/agent-sdk/claude-code-features) | Full content in every request (but prompt-cached, so only the first request pays full cost) |

212 213

213Large tool outputs consume significant context. Reading a big file or running a command with verbose output can use thousands of tokens in a single turn. Context accumulates across turns, so longer sessions with many tool calls build up significantly more context than short ones.214Large tool outputs consume significant context. Reading a big file or running a command with verbose output can use thousands of tokens in a single turn. Context accumulates across turns, so longer sessions with many tool calls build up significantly more context than short ones.

214 215

agent-sdk/claude-code-features.md +18 −6

Details

8 8

9The Agent SDK is built on the same foundation as Claude Code, which means your SDK agents have access to the same filesystem-based features: project instructions (`CLAUDE.md` and rules), skills, hooks, and more.9The Agent SDK is built on the same foundation as Claude Code, which means your SDK agents have access to the same filesystem-based features: project instructions (`CLAUDE.md` and rules), skills, hooks, and more.

10 10

11By default, the SDK loads no filesystem settings. Your agent runs in isolation mode with only what you pass programmatically. To load CLAUDE.md, skills, or filesystem hooks, set `settingSources` to tell the SDK where to look.11When you omit `settingSources`, `query()` reads the same filesystem settings as the Claude Code CLI: user, project, and local settings, CLAUDE.md files, and `.claude/` skills, agents, and commands. To run without these, pass `settingSources: []`, which limits the agent to what you configure programmatically. Managed policy settings and the global `~/.claude.json` config are read regardless of this option. See [What settingSources does not control](#what-settingsources-does-not-control).

12 12

13For a conceptual overview of what each feature does and when to use it, see [Extend Claude Code](/en/features-overview).13For a conceptual overview of what each feature does and when to use it, see [Extend Claude Code](/en/features-overview).

14 14

~~15## Enable Claude Code features with settingSources~~15## Control filesystem settings with settingSources

16 16

17The setting sources option ([`setting_sources`](/en/agent-sdk/python#claude-agent-options) in Python, [`settingSources`](/en/agent-sdk/typescript#setting-source) in TypeScript) controls which filesystem-based settings the SDK loads. Without it, your agent won't discover skills, `CLAUDE.md` files, or project-level hooks.17The setting sources option ([`setting_sources`](/en/agent-sdk/python#claude-agent-options) in Python, [`settingSources`](/en/agent-sdk/typescript#setting-source) in TypeScript) controls which filesystem-based settings the SDK loads. Pass an explicit list to opt in to specific sources, or pass an empty array to disable user, project, and local settings.

18 18

19This example loads both user-level and project-level settings by setting `settingSources` to `["user", "project"]`:19This example loads both user-level and project-level settings by setting `settingSources` to `["user", "project"]`:

20 20

73| `"user"` | User CLAUDE.md, `~/.claude/rules/*.md`, user skills, user settings | `~/.claude/` |73| `"user"` | User CLAUDE.md, `~/.claude/rules/*.md`, user skills, user settings | `~/.claude/` |

74| `"local"` | CLAUDE.local.md (gitignored), `.claude/settings.local.json` | `<cwd>/` |74| `"local"` | CLAUDE.local.md (gitignored), `.claude/settings.local.json` | `<cwd>/` |

75 75

~~76To match the full Claude Code CLI behavior, use `["user", "project", "local"]`.~~76Omitting `settingSources` is equivalent to `["user", "project", "local"]`.

78The `cwd` option determines where the SDK looks for project settings. If neither `cwd` nor any of its parent directories contains a `.claude/` folder, project-level features won't load.

80### What settingSources does not control

82`settingSources` covers user, project, and local settings. A few inputs are read regardless of its value:

84| Input | Behavior | To disable |

85| :---------------------------------------------------- | :--------------------------------------- | :------------------------------------------------------------------------------------------ |

86| Managed policy settings | Always loaded when present on the host | Remove the managed settings file |

87| `~/.claude.json` global config | Always read | Relocate with `CLAUDE_CONFIG_DIR` in `env` |

88| Auto memory at `~/.claude/projects/<project>/memory/` | Loaded by default into the system prompt | Set `autoMemoryEnabled: false` in settings, or `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` in `env` |

77 89

78<Warning>90<Warning>

79 The `cwd` option determines where the SDK looks for project settings. If neither `cwd` nor any of its parent directories contains a `.claude/` folder, project-level features won't load. Auto memory (the `~/.claude/projects/<project>/memory/` directory that Claude Code uses to persist notes across interactive sessions) is a CLI-only feature and is never loaded by the SDK.91 Do not rely on default `query()` options for multi-tenant isolation. Because the inputs above are read regardless of `settingSources`, an SDK process can pick up host-level configuration and per-directory memory. For multi-tenant deployments, run each tenant in its own filesystem and set `settingSources: []` plus `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` in `env`. See [Secure deployment](/en/agent-sdk/secure-deployment).

80</Warning>92</Warning>

81 93

82## Project instructions (CLAUDE.md and rules)94## Project instructions (CLAUDE.md and rules)

107 119

108Skills are markdown files that give your agent specialized knowledge and invocable workflows. Unlike `CLAUDE.md` (which loads every session), skills load on demand. The agent receives skill descriptions at startup and loads the full content when relevant.120Skills are markdown files that give your agent specialized knowledge and invocable workflows. Unlike `CLAUDE.md` (which loads every session), skills load on demand. The agent receives skill descriptions at startup and loads the full content when relevant.

109 121

110To use skills in the SDK, set `settingSources` so the agent discovers skill files from the filesystem. The `Skill` tool is enabled by default when you don't specify `allowedTools`. If you are using an `allowedTools` allowlist, include `"Skill"` explicitly.122Skills are discovered from the filesystem through `settingSources`. With default options, user and project skills load automatically. The `Skill` tool is enabled by default when you don't specify `allowedTools`. If you are using an `allowedTools` allowlist, include `"Skill"` explicitly.

111 123

112<CodeGroup>124<CodeGroup>

113 ```python Python theme={null}125 ```python Python theme={null}

agent-sdk/cost-tracking.md +18 −8

Details

4 4

5# Track cost and usage5# Track cost and usage

6 6

~~7> Learn how to track token usage, deduplicate parallel tool calls, and calculate costs with the Claude Agent SDK.~~7> Learn how to track token usage, deduplicate parallel tool calls, and estimate costs with the Claude Agent SDK.

8 8

9The Claude Agent SDK provides detailed token usage information for each interaction with Claude. This guide explains how to properly track costs and understand usage reporting, especially when dealing with parallel tool uses and multi-step conversations.9The Claude Agent SDK provides detailed token usage information for each interaction with Claude. This guide explains how to properly track usage and understand cost reporting, especially when dealing with parallel tool uses and multi-step conversations.

10 10

11For complete API documentation, see the [TypeScript SDK reference](/en/agent-sdk/typescript) and [Python SDK reference](/en/agent-sdk/python).11For complete API documentation, see the [TypeScript SDK reference](/en/agent-sdk/typescript) and [Python SDK reference](/en/agent-sdk/python).

12 12

13<Warning>

14 The `total_cost_usd` and `costUSD` fields are client-side estimates, not authoritative billing data. The SDK computes them locally from a price table bundled at build time, so they can drift from what you are actually billed when:

16 * pricing changes

17 * the installed SDK version does not recognize a model

18 * billing rules apply that the client cannot model

20 Use these fields for development insight and approximate budgeting. For authoritative billing, use the [Usage and Cost API](https://platform.claude.com/docs/en/build-with-claude/usage-cost-api) or the Usage page in the [Claude Console](https://platform.claude.com/usage). Do not bill end users or trigger financial decisions from these fields.

21</Warning>

13## Understand token usage23## Understand token usage

14 24

15The TypeScript and Python SDKs expose the same usage data with different field names:25The TypeScript and Python SDKs expose the same usage data with different field names:

25* **Step:** a single request/response cycle within a `query()` call. Each step produces assistant messages with token usage.35* **Step:** a single request/response cycle within a `query()` call. Each step produces assistant messages with token usage.

26* **Session:** a series of `query()` calls linked by a session ID (using the `resume` option). Each `query()` call within a session reports its own cost independently.36* **Session:** a series of `query()` calls linked by a session ID (using the `resume` option). Each `query()` call within a session reports its own cost independently.

27 37

~~28The following diagram shows the message stream from a single `query()` call, with token usage reported at each step and the authoritative total at the end:~~38The following diagram shows the message stream from a single `query()` call, with token usage reported at each step and the cumulative estimate at the end:

29 39

30<img src="https://mintcdn.com/claude-code/gvy2DIUELtNA8qD3/images/agent-sdk/message-usage-flow.svg?fit=max&auto=format&n=gvy2DIUELtNA8qD3&q=85&s=88cba82134f8f7994d780c3f153b83fc" alt="Diagram showing a query producing two steps of messages. Step 1 has four assistant messages sharing the same ID and usage (count once), Step 2 has one assistant message with a new ID, and the final result message shows total_cost_usd for billing." width="760" height="520" data-path="images/agent-sdk/message-usage-flow.svg" />40<img src="https://mintcdn.com/claude-code/Dujg43sxTkuhSELI/images/agent-sdk/message-usage-flow.svg?fit=max&auto=format&n=Dujg43sxTkuhSELI&q=85&s=c542f51ff58547ef9c0e57b16d03f33c" alt="Diagram showing a query producing two steps of messages. Step 1 has four assistant messages sharing the same ID and usage (count once), Step 2 has one assistant message with a new ID, and the final result message shows the estimated total_cost_usd." width="760" height="520" data-path="images/agent-sdk/message-usage-flow.svg" />

31 41

32<Steps>42<Steps>

33 <Step title="Each step produces assistant messages">43 <Step title="Each step produces assistant messages">

34 When Claude responds, it sends one or more assistant messages. In TypeScript, each assistant message contains a nested `BetaMessage` (accessed via `message.message`) with an `id` and a [`usage`](https://platform.claude.com/docs/en/api/messages) object with token counts (`input_tokens`, `output_tokens`). In Python, the `AssistantMessage` dataclass exposes the same data directly via `message.usage` and `message.message_id`. When Claude uses multiple tools in one turn, all messages in that turn share the same ID, so deduplicate by ID to avoid double-counting.44 When Claude responds, it sends one or more assistant messages. In TypeScript, each assistant message contains a nested `BetaMessage` (accessed via `message.message`) with an `id` and a [`usage`](https://platform.claude.com/docs/en/api/messages) object with token counts (`input_tokens`, `output_tokens`). In Python, the `AssistantMessage` dataclass exposes the same data directly via `message.usage` and `message.message_id`. When Claude uses multiple tools in one turn, all messages in that turn share the same ID, so deduplicate by ID to avoid double-counting.

35 </Step>45 </Step>

36 46

~~37 <Step title="The result message provides the authoritative total">~~47 <Step title="The result message provides the cumulative estimate">

38 When the `query()` call completes, the SDK emits a result message with `total_cost_usd` and cumulative `usage`. This is available in both TypeScript ([`SDKResultMessage`](/en/agent-sdk/typescript#sdk-result-message)) and Python ([`ResultMessage`](/en/agent-sdk/python#result-message)). If you make multiple `query()` calls (for example, in a multi-turn session), each result only reflects the cost of that individual call. If you only need the total cost, you can ignore the per-step usage and read this single value.48 When the `query()` call completes, the SDK emits a result message with `total_cost_usd` and cumulative `usage`. This is available in both TypeScript ([`SDKResultMessage`](/en/agent-sdk/typescript#sdk-result-message)) and Python ([`ResultMessage`](/en/agent-sdk/python#result-message)). If you make multiple `query()` calls (for example, in a multi-turn session), each result only reflects the cost of that individual call. If you only need the estimated total, you can ignore the per-step usage and read this single value.

39 </Step>49 </Step>

40</Steps>50</Steps>

41 51

42## Get the total cost of a query52## Get the total cost of a query

43 53

44The result message ([TypeScript](/en/agent-sdk/typescript#sdk-result-message), [Python](/en/agent-sdk/python#result-message)) is the last message in every `query()` call. It includes `total_cost_usd`, the cumulative cost across all steps in that call. This works for both success and error results. If you use sessions to make multiple `query()` calls, each result only reflects the cost of that individual call.54The result message ([TypeScript](/en/agent-sdk/typescript#sdk-result-message), [Python](/en/agent-sdk/python#result-message)) marks the end of the agent loop for a `query()` call. It includes `total_cost_usd`, the cumulative estimated cost across all steps in that call. This works for both success and error results. If you use sessions to make multiple `query()` calls, each result only reflects the cost of that individual call.

45 55

46The following examples iterate over the message stream from a `query()` call and print the total cost when the `result` message arrives:56The following examples iterate over the message stream from a `query()` call and print the total cost when the `result` message arrives:

47 57

199In rare cases, you might observe different `output_tokens` values for messages with the same ID. When this occurs:209In rare cases, you might observe different `output_tokens` values for messages with the same ID. When this occurs:

200 210

2011. **Use the highest value:** the final message in a group typically contains the accurate total.2111. **Use the highest value:** the final message in a group typically contains the accurate total.

2022. **Verify against total cost:** the `total_cost_usd` in the result message is authoritative.2122. **Prefer the result message:** the `total_cost_usd` in the result message reflects the SDK's accumulated estimate across all steps, so it is more reliable than summing per-step values yourself. It is still an estimate and may differ from your actual bill.

2033. **Report inconsistencies:** file issues at the [Claude Code GitHub repository](https://github.com/anthropics/claude-code/issues).2133. **Report inconsistencies:** file issues at the [Claude Code GitHub repository](https://github.com/anthropics/claude-code/issues).

204 214

205### Track costs on failed conversations215### Track costs on failed conversations

agent-sdk/hooks.md +1 −1

Details

24 </Step>24 </Step>

25 25

26 <Step title="The SDK collects registered hooks">26 <Step title="The SDK collects registered hooks">

27 The SDK checks for hooks registered for that event type. This includes callback hooks you pass in `options.hooks` and shell command hooks from settings files, but only if you explicitly load them with [`settingSources`](/en/agent-sdk/typescript#setting-source) or [`setting_sources`](/en/agent-sdk/python#setting-source).27 The SDK checks for hooks registered for that event type. This includes callback hooks you pass in `options.hooks` and shell command hooks from settings files when the corresponding [`settingSources`](/en/agent-sdk/typescript#setting-source) or [`setting_sources`](/en/agent-sdk/python#setting-source) entry is enabled, which it is for default `query()` options.

28 </Step>28 </Step>

29 29

30 <Step title="Matchers filter which hooks run">30 <Step title="Matchers filter which hooks run">

agent-sdk/hosting.md +2 −2

Details

25Each SDK instance requires:25Each SDK instance requires:

26 26

27* **Runtime dependencies**27* **Runtime dependencies**

~~28 * Python 3.10+ (for Python SDK) or Node.js 18+ (for TypeScript SDK)~~28 * Python 3.10+ for the Python SDK, or Node.js 18+ for the TypeScript SDK

~~29 * Node.js (required by the bundled Claude Code CLI that the SDK spawns; both SDK packages include it, so no separate install is needed)~~29 * Both SDK packages bundle a native Claude Code binary for the host platform, so no separate Claude Code or Node.js install is needed for the spawned CLI

30 30

31* **Resource allocation**31* **Resource allocation**

32 * Recommended: 1GiB RAM, 5GiB of disk, and 1 CPU (vary this based on your task as needed)32 * Recommended: 1GiB RAM, 5GiB of disk, and 1 CPU (vary this based on your task as needed)

agent-sdk/mcp.md +1 −1

Details

127 127

128### From a config file128### From a config file

129 129

130Create a `.mcp.json` file at your project root. The SDK does not load filesystem settings by default, so set `settingSources: ["project"]` (Python: `setting_sources=["project"]`) in your options for the file to be picked up:130Create a `.mcp.json` file at your project root. The file is picked up when the `project` setting source is enabled, which it is for default `query()` options. If you set `settingSources` explicitly, include `"project"` for this file to load:

131 131

132```json theme={null}132```json theme={null}

133{133{

agent-sdk/migration-guide.md +7 −7

Details

110# Before110# Before

111from claude_code_sdk import query, ClaudeCodeOptions111from claude_code_sdk import query, ClaudeCodeOptions

112 112

113options = ClaudeCodeOptions(model="claude-opus-4-6")113options = ClaudeCodeOptions(model="claude-opus-4-7")

114 114

115# After115# After

116from claude_agent_sdk import query, ClaudeAgentOptions116from claude_agent_sdk import query, ClaudeAgentOptions

117 117

118options = ClaudeAgentOptions(model="claude-opus-4-6")118options = ClaudeAgentOptions(model="claude-opus-4-7")

119```119```

120 120

121**5. Review [breaking changes](#breaking-changes)**121**5. Review [breaking changes](#breaking-changes)**

138# BEFORE (claude-code-sdk)138# BEFORE (claude-code-sdk)

139from claude_code_sdk import query, ClaudeCodeOptions139from claude_code_sdk import query, ClaudeCodeOptions

140 140

141options = ClaudeCodeOptions(model="claude-opus-4-6", permission_mode="acceptEdits")141options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

142 142

143# AFTER (claude-agent-sdk)143# AFTER (claude-agent-sdk)

144from claude_agent_sdk import query, ClaudeAgentOptions144from claude_agent_sdk import query, ClaudeAgentOptions

145 145

146options = ClaudeAgentOptions(model="claude-opus-4-6", permission_mode="acceptEdits")146options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

147```147```

148 148

149**Why this changed:** The type name now matches the "Claude Agent SDK" branding and provides consistency across the SDK's naming conventions.149**Why this changed:** The type name now matches the "Claude Agent SDK" branding and provides consistency across the SDK's naming conventions.

279* **Testing** - Isolated test environments279* **Testing** - Isolated test environments

280* **Multi-tenant systems** - Prevent settings leakage between users280* **Multi-tenant systems** - Prevent settings leakage between users

281 281

282<Note>282<Warning>

283 **Backward compatibility:** If your application relied on filesystem settings (custom slash commands, CLAUDE.md instructions, etc.), add `settingSources: ['user', 'project', 'local']` to your options.283 Current SDK releases have reverted this default for `query()`: omitting the option once again loads user, project, and local settings, matching the CLI. Pass `settingSources: []` in TypeScript or `setting_sources=[]` in Python if your application depends on the isolated behavior described above. Python SDK 0.1.59 and earlier treated an empty list the same as omitting the option, so upgrade before relying on `setting_sources=[]`. See [What settingSources does not control](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) for inputs that are read even when `settingSources` is `[]`.

284</Note>284</Warning>

285 285

286## Why the Rename?286## Why the Rename?

287 287

agent-sdk/modifying-system-prompts.md +58 −14

Details

37* **Project-level:** `CLAUDE.md` or `.claude/CLAUDE.md` in your working directory37* **Project-level:** `CLAUDE.md` or `.claude/CLAUDE.md` in your working directory

38* **User-level:** `~/.claude/CLAUDE.md` for global instructions across all projects38* **User-level:** `~/.claude/CLAUDE.md` for global instructions across all projects

39 39

~~40**IMPORTANT:** The SDK only reads CLAUDE.md files when you explicitly configure `settingSources` (TypeScript) or `setting_sources` (Python):~~40CLAUDE.md files are read when the corresponding setting source is enabled: `'project'` for project-level CLAUDE.md and `'user'` for `~/.claude/CLAUDE.md`. With default `query()` options both sources are enabled, so CLAUDE.md loads automatically. If you set `settingSources` (TypeScript) or `setting_sources` (Python) explicitly, include the sources you need. CLAUDE.md loading is controlled by setting sources, not by the `claude_code` preset.

~~42* Include `'project'` to load project-level CLAUDE.md~~

~~43* Include `'user'` to load user-level CLAUDE.md (`~/.claude/CLAUDE.md`)~~

~~45The `claude_code` system prompt preset does NOT automatically load CLAUDE.md - you must also specify setting sources.~~

46 41

47**Content format:**42**Content format:**

48CLAUDE.md files use plain markdown and can contain:43CLAUDE.md files use plain markdown and can contain:

83 ```typescript TypeScript theme={null}78 ```typescript TypeScript theme={null}

84 import { query } from "@anthropic-ai/claude-agent-sdk";79 import { query } from "@anthropic-ai/claude-agent-sdk";

85 80

~~86 // IMPORTANT: You must specify settingSources to load CLAUDE.md~~

~~87 // The claude_code preset alone does NOT load CLAUDE.md files~~

88 const messages = [];81 const messages = [];

89 82

90 for await (const message of query({83 for await (const message of query({

94 type: "preset",87 type: "preset",

95 preset: "claude_code" // Use Claude Code's system prompt88 preset: "claude_code" // Use Claude Code's system prompt

96 },89 },

~~97 settingSources: ["project"] // Required to load CLAUDE.md from project~~90 settingSources: ["project"] // Loads CLAUDE.md from project

98 }91 }

99 })) {92 })) {

100 messages.push(message);93 messages.push(message);

106 ```python Python theme={null}99 ```python Python theme={null}

107 from claude_agent_sdk import query, ClaudeAgentOptions100 from claude_agent_sdk import query, ClaudeAgentOptions

108 101

109 # IMPORTANT: You must specify setting_sources to load CLAUDE.md

110 # The claude_code preset alone does NOT load CLAUDE.md files

111 messages = []102 messages = []

112 103

113 async for message in query(104 async for message in query(

117 "type": "preset",108 "type": "preset",

118 "preset": "claude_code", # Use Claude Code's system prompt109 "preset": "claude_code", # Use Claude Code's system prompt

119 },110 },

120 setting_sources=["project"], # Required to load CLAUDE.md from project111 setting_sources=["project"], # Loads CLAUDE.md from project

121 ),112 ),

122 ):113 ):

123 messages.append(message)114 messages.append(message)

141* ✅ Persistent across all sessions in a project132* ✅ Persistent across all sessions in a project

142* ✅ Shared with team via git133* ✅ Shared with team via git

143* ✅ Automatic discovery (no code changes needed)134* ✅ Automatic discovery (no code changes needed)

144* ⚠️ Requires loading settings via `settingSources`135* ⚠️ Not loaded if you pass `settingSources: []`

145 136

146### Method 2: Output styles (persistent configurations)137### Method 2: Output styles (persistent configurations)

147 138

283 ```274 ```

284</CodeGroup>275</CodeGroup>

285 276

277#### Improve prompt caching across users and machines

278

279By default, two sessions that use the same `claude_code` preset and `append` text still cannot share a prompt cache entry if they run from different working directories. This is because the preset embeds per-session context in the system prompt ahead of your `append` text: the working directory, platform and OS version, current date, git status, and auto-memory paths. Any difference in that context produces a different system prompt and a cache miss.

280

281To make the system prompt identical across sessions, set `excludeDynamicSections: true` in TypeScript or `"exclude_dynamic_sections": True` in Python. The per-session context moves into the first user message, leaving only the static preset and your `append` text in the system prompt so identical configurations share a cache entry across users and machines.

282

283<Note>

284 `excludeDynamicSections` requires `@anthropic-ai/claude-agent-sdk` v0.2.98 or later, or `claude-agent-sdk` v0.1.58 or later for Python. It applies only to the preset object form and has no effect when `systemPrompt` is a string.

285</Note>

286

287The following example pairs a shared `append` block with `excludeDynamicSections` so a fleet of agents running from different directories can reuse the same cached system prompt:

288

289<CodeGroup>

290 ```typescript TypeScript theme={null}

291 import { query } from "@anthropic-ai/claude-agent-sdk";

292

293 for await (const message of query({

294 prompt: "Triage the open issues in this repo",

295 options: {

296 systemPrompt: {

297 type: "preset",

298 preset: "claude_code",

299 append: "You operate Acme's internal triage workflow. Label issues by component and severity.",

300 excludeDynamicSections: true

301 }

302 }

303 })) {

304 // ...

305 }

306 ```

307

308 ```python Python theme={null}

309 from claude_agent_sdk import query, ClaudeAgentOptions

310

311 async for message in query(

312 prompt="Triage the open issues in this repo",

313 options=ClaudeAgentOptions(

314 system_prompt={

315 "type": "preset",

316 "preset": "claude_code",

317 "append": "You operate Acme's internal triage workflow. Label issues by component and severity.",

318 "exclude_dynamic_sections": True,

319 },

320 ),

321 ):

322 ...

323 ```

324</CodeGroup>

325

326**Tradeoffs:** the working directory, git status, and memory location still reach Claude, but as part of the first user message rather than the system prompt. Instructions in the user message carry marginally less weight than the same text in the system prompt, so Claude may rely on them less strongly when reasoning about the current directory or auto-memory paths. Enable this option when cross-session cache reuse matters more than maximally authoritative environment context.

327

328For the equivalent flag in non-interactive CLI mode, see [`--exclude-dynamic-system-prompt-sections`](/en/cli-reference).

329

286### Method 4: Custom system prompts330### Method 4: Custom system prompts

287 331

288You can provide a custom string as `systemPrompt` to replace the default entirely with your own instructions.332You can provide a custom string as `systemPrompt` to replace the default entirely with your own instructions.

371* "Run `npm run lint:fix` before committing"415* "Run `npm run lint:fix` before committing"

372* "Database migrations are in the `migrations/` directory"416* "Database migrations are in the `migrations/` directory"

373 417

374**Important:** To load CLAUDE.md files, you must explicitly set `settingSources: ['project']` (TypeScript) or `setting_sources=["project"]` (Python). The `claude_code` system prompt preset does NOT automatically load CLAUDE.md without this setting.418CLAUDE.md files load when the `project` setting source is enabled, which it is for default `query()` options. If you set `settingSources` (TypeScript) or `setting_sources` (Python) explicitly, include `'project'` to keep loading project-level CLAUDE.md.

375 419

376### When to use output styles420### When to use output styles

377 421

agent-sdk/observability.md +16 −5

Details

113 113

114### Flush telemetry from short-lived calls114### Flush telemetry from short-lived calls

115 115

116The CLI batches telemetry and exports on an interval. It flushes any pending data when the process exits cleanly, so a `query()` call that completes normally does not lose spans. However, if your process is killed before the CLI shuts down, anything still in the batch buffer is lost. Lowering the export intervals reduces that window.116The CLI batches telemetry and exports on an interval. On a clean process exit it attempts to flush pending data, but the flush is bounded by a short timeout, so spans can still be dropped if the collector is slow to respond. If your process is killed before the CLI shuts down, anything still in the batch buffer is lost. Lowering the export intervals reduces both windows.

117 117

118By default, metrics export every 60 seconds and traces and logs export every 5 seconds. The following example shortens all three intervals so that data reaches the collector while a short task is still running:118By default, metrics export every 60 seconds and traces and logs export every 5 seconds. The following example shortens all three intervals so that data reaches the collector while a short task is still running:

119 119

144* **`claude_code.interaction`:** wraps a single turn of the agent loop, from receiving a prompt to producing a response.144* **`claude_code.interaction`:** wraps a single turn of the agent loop, from receiving a prompt to producing a response.

145* **`claude_code.llm_request`:** wraps each call to the Claude API, with model name, latency, and token counts as attributes.145* **`claude_code.llm_request`:** wraps each call to the Claude API, with model name, latency, and token counts as attributes.

146* **`claude_code.tool`:** wraps each tool invocation, with child spans for the permission wait (`claude_code.tool.blocked_on_user`) and the execution itself (`claude_code.tool.execution`).146* **`claude_code.tool`:** wraps each tool invocation, with child spans for the permission wait (`claude_code.tool.blocked_on_user`) and the execution itself (`claude_code.tool.execution`).

147* **`claude_code.hook`:** wraps each [hook](/en/agent-sdk/hooks) execution.147* **`claude_code.hook`:** wraps each [hook](/en/agent-sdk/hooks) execution. Requires detailed beta tracing (`ENABLE_BETA_TRACING_DETAILED=1` and `BETA_TRACING_ENDPOINT`) in addition to the variables above.

148 148

149Every span carries a `session.id` attribute. When you make several `query()` calls against the same [session](/en/agent-sdk/sessions), filter on `session.id` in your backend to see them as one timeline.149The `llm_request`, `tool`, and `hook` spans are children of the enclosing `claude_code.interaction` span. When the agent spawns a subagent through the Task tool, the subagent's `llm_request` and `tool` spans nest under the parent agent's `claude_code.tool` span, so the full delegation chain appears as one trace.

150

151Spans carry a `session.id` attribute by default. When you make several `query()` calls against the same [session](/en/agent-sdk/sessions), filter on `session.id` in your backend to see them as one timeline. The attribute is omitted if `OTEL_METRICS_INCLUDE_SESSION_ID` is set to a falsy value.

150 152

151<Note>153<Note>

152 Tracing is in beta. Span names and attributes may change between releases. See154 Tracing is in beta. Span names and attributes may change between releases. See

154 for the trace exporter configuration variables.156 for the trace exporter configuration variables.

155</Note>157</Note>

156 158

159## Link traces to your application

160

161The SDK automatically propagates W3C trace context into the CLI subprocess. When you call `query()` while an OpenTelemetry span is active in your application, the SDK injects `TRACEPARENT` and `TRACESTATE` into the child process environment, and the CLI reads them so its `claude_code.interaction` span becomes a child of your span. The agent run then appears inside your application's trace instead of as a disconnected root.

162

163The CLI also forwards `TRACEPARENT` to every Bash and PowerShell command it runs. If a command launched through the Bash tool emits its own OpenTelemetry spans, those spans nest under the `claude_code.tool.execution` span that wraps the command.

164

165Auto-injection is skipped when you set `TRACEPARENT` explicitly in `options.env`, so you can pin a specific parent context if needed. Interactive CLI sessions ignore inbound `TRACEPARENT` entirely; only Agent SDK and `claude -p` runs honor it. See [Traces (beta)](/en/monitoring-usage#traces-beta) in the Monitoring reference for the full span and attribute reference.

166

157## Tag telemetry from your agent167## Tag telemetry from your agent

158 168

159By default, the CLI reports `service.name` as `claude-code`. If you run several agents, or run the SDK alongside other services that export to the same collector, override the service name and add resource attributes so you can filter by agent in your backend.169By default, the CLI reports `service.name` as `claude-code`. If you run several agents, or run the SDK alongside other services that export to the same collector, override the service name and add resource attributes so you can filter by agent in your backend.

186 196

187## Control sensitive data in exports197## Control sensitive data in exports

188 198

189Telemetry is structural by default. Token counts, durations, model names, and tool names are always recorded, but the content your agent reads and writes is not. Three opt-in variables add content to the exported data:199Telemetry is structural by default. Durations, model names, and tool names are recorded on every span; token counts are recorded when the underlying API request returns usage data, so spans for failed or aborted requests may omit them. The content your agent reads and writes is not recorded by default. These opt-in variables add content to the exported data:

190 200

191| Variable | Adds |201| Variable | Adds |

192| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |202| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

194| `OTEL_LOG_TOOL_DETAILS=1` | Tool input arguments (file paths, shell commands, search patterns) on `claude_code.tool_result` events |204| `OTEL_LOG_TOOL_DETAILS=1` | Tool input arguments (file paths, shell commands, search patterns) on `claude_code.tool_result` events |

195| `OTEL_LOG_TOOL_CONTENT=1` | Full tool input and output bodies as span events on `claude_code.tool`, truncated at 60 KB. Requires [tracing](#read-agent-traces) to be enabled |205| `OTEL_LOG_TOOL_CONTENT=1` | Full tool input and output bodies as span events on `claude_code.tool`, truncated at 60 KB. Requires [tracing](#read-agent-traces) to be enabled |

206| `OTEL_LOG_RAW_API_BODIES` | Full Anthropic Messages API request and response JSON as `claude_code.api_request_body` and `claude_code.api_response_body` log events. Set to `1` for inline bodies truncated at 60 KB, or `file:<dir>` for untruncated bodies on disk with a `body_ref` path in the event. Bodies include the entire conversation history and have extended-thinking content redacted. Enabling this implies consent to everything the three variables above would reveal |

196 207

197Leave these unset unless your observability pipeline is approved to store the data your agent handles. See [Security and privacy](/en/monitoring-usage#security-and-privacy) in the Monitoring reference for the full list of attributes and redaction behavior.208Leave these unset unless your observability pipeline is approved to store the data your agent handles. See [Security and privacy](/en/monitoring-usage#security-and-privacy) in the Monitoring reference for the full list of attributes and redaction behavior.

198 209

agent-sdk/overview.md +9 −1

Details

12 12

13Build AI agents that autonomously read files, run commands, search the web, edit code, and more. The Agent SDK gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript.13Build AI agents that autonomously read files, run commands, search the web, edit code, and more. The Agent SDK gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript.

14 14

15<Note>

16 Opus 4.7 (`claude-opus-4-7`) requires Agent SDK v0.2.111 or later. If you see a `thinking.type.enabled` API error, see [Troubleshooting](/en/agent-sdk/quickstart#troubleshooting).

17</Note>

15<CodeGroup>19<CodeGroup>

16 ```python Python theme={null}20 ```python Python theme={null}

17 import asyncio21 import asyncio

70 ```74 ```

71 </Tab>75 </Tab>

72 </Tabs>76 </Tabs>

78 <Note>

79 The TypeScript SDK bundles a native Claude Code binary for your platform as an optional dependency, so you don't need to install Claude Code separately.

80 </Note>

73 </Step>81 </Step>

74 82

75 <Step title="Set your API key">83 <Step title="Set your API key">

465 473

466### Claude Code features474### Claude Code features

467 475

468The SDK also supports Claude Code's filesystem-based configuration. To use these features, set `setting_sources=["project"]` (Python) or `settingSources: ['project']` (TypeScript) in your options.476The SDK also supports Claude Code's filesystem-based configuration. With default options the SDK loads these from `.claude/` in your working directory and `~/.claude/`. To restrict which sources load, set `setting_sources` (Python) or `settingSources` (TypeScript) in your options.

469 477

471| ------------------------------------------------ | ---------------------------------------------------- | ---------------------------------- |479| ------------------------------------------------ | ---------------------------------------------------- | ---------------------------------- |

agent-sdk/permissions.md +2 −2

Details

67 **`allowed_tools` does not constrain `bypassPermissions`.** `allowed_tools` only pre-approves the tools you list. Unlisted tools are not matched by any allow rule and fall through to the permission mode, where `bypassPermissions` approves them. Setting `allowed_tools=["Read"]` alongside `permission_mode="bypassPermissions"` still approves every tool, including `Bash`, `Write`, and `Edit`. If you need `bypassPermissions` but want specific tools blocked, use `disallowed_tools`.67 **`allowed_tools` does not constrain `bypassPermissions`.** `allowed_tools` only pre-approves the tools you list. Unlisted tools are not matched by any allow rule and fall through to the permission mode, where `bypassPermissions` approves them. Setting `allowed_tools=["Read"]` alongside `permission_mode="bypassPermissions"` still approves every tool, including `Bash`, `Write`, and `Edit`. If you need `bypassPermissions` but want specific tools blocked, use `disallowed_tools`.

68</Warning>68</Warning>

69 69

70You can also configure allow, deny, and ask rules declaratively in `.claude/settings.json`. The SDK does not load filesystem settings by default, so you must set `setting_sources=["project"]` (TypeScript: `settingSources: ["project"]`) in your options for these rules to apply. See [Permission settings](/en/settings#permission-settings) for the rule syntax.70You can also configure allow, deny, and ask rules declaratively in `.claude/settings.json`. These rules are read when the `project` setting source is enabled, which it is for default `query()` options. If you set `setting_sources` (TypeScript: `settingSources`) explicitly, include `"project"` for them to apply. See [Permission settings](/en/settings#permission-settings) for the rule syntax.

71 71

72## Permission modes72## Permission modes

73 73

87| `auto` (TypeScript only) | Model-classified approvals | A model classifier approves or denies each tool call. See [Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) for availability |87| `auto` (TypeScript only) | Model-classified approvals | A model classifier approves or denies each tool call. See [Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) for availability |

88 88

89<Warning>89<Warning>

90 **Subagent inheritance:** When using `bypassPermissions`, all subagents inherit this mode and it cannot be overridden. Subagents may have different system prompts and less constrained behavior than your main agent. Enabling `bypassPermissions` grants them full, autonomous system access without any approval prompts.90 **Subagent inheritance:** When the parent uses `bypassPermissions`, `acceptEdits`, or `auto`, all subagents inherit that mode and it cannot be overridden per subagent. Subagents may have different system prompts and less constrained behavior than your main agent, so inheriting `bypassPermissions` grants them full, autonomous system access without any approval prompts.

91</Warning>91</Warning>

92 92

93### Set permission mode93### Set permission mode

agent-sdk/python.md +58 −20

Details

790 thinking: ThinkingConfig | None = None790 thinking: ThinkingConfig | None = None

791 effort: Literal["low", "medium", "high", "max"] | None = None791 effort: Literal["low", "medium", "high", "max"] | None = None

792 enable_file_checkpointing: bool = False792 enable_file_checkpointing: bool = False

793 session_store: SessionStore | None = None

793```794```

794 795

796| :---------------------------- | :------------------------------------------------ | :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |797| :---------------------------- | :------------------------------------------------------------------------------------- | :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

797| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Tools configuration. Use `{"type": "preset", "preset": "claude_code"}` for Claude Code's default tools |798| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Tools configuration. Use `{"type": "preset", "preset": "claude_code"}` for Claude Code's default tools |

798| `allowed_tools` | `list[str]` | `[]` | Tools to auto-approve without prompting. This does not restrict Claude to only these tools; unlisted tools fall through to `permission_mode` and `can_use_tool`. Use `disallowed_tools` to block tools. See [Permissions](/en/agent-sdk/permissions#allow-and-deny-rules) |799| `allowed_tools` | `list[str]` | `[]` | Tools to auto-approve without prompting. This does not restrict Claude to only these tools; unlisted tools fall through to `permission_mode` and `can_use_tool`. Use `disallowed_tools` to block tools. See [Permissions](/en/agent-sdk/permissions#allow-and-deny-rules) |

799| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | System prompt configuration. Pass a string for custom prompt, or use `{"type": "preset", "preset": "claude_code"}` for Claude Code's system prompt. Add `"append"` to extend the preset |800| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | System prompt configuration. Pass a string for custom prompt, or use `{"type": "preset", "preset": "claude_code"}` for Claude Code's system prompt. Add `"append"` to extend the preset |

830| `setting_sources` | `list[SettingSource] \| None` | `None` (no settings) | Control which filesystem settings to load. When omitted, no settings are loaded. **Note:** Must include `"project"` to load CLAUDE.md files |831| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI defaults: all sources) | Control which filesystem settings to load. Pass `[]` to disable user, project, and local settings. Managed policy settings load regardless. See [Use Claude Code features](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

835| `session_store` | [`SessionStore`](/en/agent-sdk/session-storage#the-session-store-interface) ` \| None` | `None` | Mirror session transcripts to an external backend so any host can resume them. See [Persist sessions to external storage](/en/agent-sdk/session-storage) |

834 836

835### `OutputFormat`837### `OutputFormat`

836 838

858 type: Literal["preset"]860 type: Literal["preset"]

859 preset: Literal["claude_code"]861 preset: Literal["claude_code"]

860 append: NotRequired[str]862 append: NotRequired[str]

863 exclude_dynamic_sections: NotRequired[bool]

861```864```

862 865

864| :------- | :------- | :------------------------------------------------------------ |867| :------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

865| `type` | Yes | Must be `"preset"` to use a preset system prompt |868| `type` | Yes | Must be `"preset"` to use a preset system prompt |

866| `preset` | Yes | Must be `"claude_code"` to use Claude Code's system prompt |869| `preset` | Yes | Must be `"claude_code"` to use Claude Code's system prompt |

867| `append` | No | Additional instructions to append to the preset system prompt |870| `append` | No | Additional instructions to append to the preset system prompt |

871| `exclude_dynamic_sections` | No | Move per-session context such as working directory, git status, and memory paths from the system prompt into the first user message. Improves prompt-cache reuse across users and machines. See [Modify system prompts](/en/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

868 872

869### `SettingSource`873### `SettingSource`

870 874

882 886

883#### Default behavior887#### Default behavior

884 888

885When `setting_sources` is **omitted** or **`None`**, the SDK does **not** load any filesystem settings. This provides isolation for SDK applications.889When `setting_sources` is omitted or `None`, `query()` loads the same filesystem settings as the Claude Code CLI: user, project, and local. Managed policy settings are loaded in all cases. See [What settingSources does not control](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) for inputs that are read regardless of this option, and how to disable them.

886 890

887#### Why use setting\_sources891#### Why use setting\_sources

888 892

889**Load all filesystem settings (legacy behavior):**893**Disable filesystem settings:**

890 894

891```python theme={null}895```python theme={null}

892# Load all settings like SDK v0.0.x did896# Do not load user, project, or local settings from disk

893from claude_agent_sdk import query, ClaudeAgentOptions897from claude_agent_sdk import query, ClaudeAgentOptions

894 898

895async for message in query(899async for message in query(

896 prompt="Analyze this code",900 prompt="Analyze this code",

897 options=ClaudeAgentOptions(901 options=ClaudeAgentOptions(

898 setting_sources=["user", "project", "local"] # Load all settings902 setting_sources=[]

903 ),

904):

905 print(message)

906```

907

908<Note>

909 In Python SDK 0.1.59 and earlier, an empty list was treated the same as omitting the option, so `setting_sources=[]` did not disable filesystem settings. Upgrade to a newer release if you need an empty list to take effect. The TypeScript SDK is not affected.

910</Note>

911

912**Load all filesystem settings explicitly:**

913

914```python theme={null}

915from claude_agent_sdk import query, ClaudeAgentOptions

916

917async for message in query(

918 prompt="Analyze this code",

919 options=ClaudeAgentOptions(

920 setting_sources=["user", "project", "local"]

899 ),921 ),

900):922):

901 print(message)923 print(message)

931**SDK-only applications:**953**SDK-only applications:**

932 954

933```python theme={null}955```python theme={null}

934# Define everything programmatically (default behavior)956# Define everything programmatically.

935# No filesystem dependencies - setting_sources defaults to None957# Pass [] to opt out of filesystem setting sources.

936async for message in query(958async for message in query(

937 prompt="Review this PR",959 prompt="Review this PR",

938 options=ClaudeAgentOptions(960 options=ClaudeAgentOptions(

939 # setting_sources=None is the default, no need to specify961 setting_sources=[],

940 agents={...},962 agents={...},

941 mcp_servers={...},963 mcp_servers={...},

942 allowed_tools=["Read", "Grep", "Glob"],964 allowed_tools=["Read", "Grep", "Glob"],

956 "type": "preset",978 "type": "preset",

957 "preset": "claude_code", # Use Claude Code's system prompt979 "preset": "claude_code", # Use Claude Code's system prompt

958 },980 },

959 setting_sources=["project"], # Required to load CLAUDE.md from project981 setting_sources=["project"], # Loads CLAUDE.md from project

960 allowed_tools=["Read", "Write", "Edit"],982 allowed_tools=["Read", "Write", "Edit"],

961 ),983 ),

962):984):

9712. Project settings (`.claude/settings.json`)9932. Project settings (`.claude/settings.json`)

9723. User settings (`~/.claude/settings.json`)9943. User settings (`~/.claude/settings.json`)

973 995

974Programmatic options (like `agents`, `allowed_tools`) always override filesystem settings.996Programmatic options such as `agents` and `allowed_tools` override user, project, and local filesystem settings. Managed policy settings take precedence over programmatic options.

975 997

976### `AgentDefinition`998### `AgentDefinition`

977 999

983 description: str1005 description: str

984 prompt: str1006 prompt: str

985 tools: list[str] | None = None1007 tools: list[str] | None = None

986 model: Literal["sonnet", "opus", "haiku", "inherit"] | None = None1008 disallowedTools: list[str] | None = None

1009 model: str | None = None

987 skills: list[str] | None = None1010 skills: list[str] | None = None

988 memory: Literal["user", "project", "local"] | None = None1011 memory: Literal["user", "project", "local"] | None = None

989 mcpServers: list[str | dict[str, Any]] | None = None1012 mcpServers: list[str | dict[str, Any]] | None = None

1013 initialPrompt: str | None = None

1014 maxTurns: int | None = None

1015 background: bool | None = None

1016 effort: Literal["low", "medium", "high", "max"] | int | None = None

1017 permissionMode: PermissionMode | None = None

990```1018```

991 1019

993| :------------ | :------- | :-------------------------------------------------------------------------------------------------- |1021| :---------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |

994| `description` | Yes | Natural language description of when to use this agent |1022| `description` | Yes | Natural language description of when to use this agent |

995| `prompt` | Yes | The agent's system prompt |1023| `prompt` | Yes | The agent's system prompt |

996| `tools` | No | Array of allowed tool names. If omitted, inherits all tools |1024| `tools` | No | Array of allowed tool names. If omitted, inherits all tools |

997| `model` | No | Model override for this agent. If omitted, uses the main model |1025| `disallowedTools` | No | Array of tool names to remove from the agent's tool set |

1026| `model` | No | Model override for this agent. Accepts an alias such as `"sonnet"`, `"opus"`, `"haiku"`, or `"inherit"`, or a full model ID. If omitted, uses the main model |

998| `skills` | No | List of skill names available to this agent |1027| `skills` | No | List of skill names available to this agent |

999| `memory` | No | Memory source for this agent: `"user"`, `"project"`, or `"local"` |1028| `memory` | No | Memory source for this agent: `"user"`, `"project"`, or `"local"` |

1000| `mcpServers` | No | MCP servers available to this agent. Each entry is a server name or an inline `{name: config}` dict |1029| `mcpServers` | No | MCP servers available to this agent. Each entry is a server name or an inline `{name: config}` dict |

1030| `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main thread agent |

1031| `maxTurns` | No | Maximum number of agentic turns before the agent stops |

1032| `background` | No | Run this agent as a non-blocking background task when invoked |

1033| `effort` | No | Reasoning effort level for this agent. Accepts a named level or an integer |

1034| `permissionMode` | No | Permission mode for tool execution within this agent. See [`PermissionMode`](#permission-mode) |

1035

1036<Note>

1037 `AgentDefinition` field names use camelCase, such as `disallowedTools`, `permissionMode`, and `maxTurns`. These names map directly to the wire format shared with the TypeScript SDK. This differs from `ClaudeAgentOptions`, which uses Python snake\_case for the equivalent top-level fields such as `disallowed_tools` and `permission_mode`. Because `AgentDefinition` is a dataclass, passing a snake\_case keyword raises a `TypeError` at construction time.

1038</Note>

1001 1039

1002### `PermissionMode`1040### `PermissionMode`

1003 1041

1197Use with the `betas` field in `ClaudeAgentOptions` to enable beta features.1235Use with the `betas` field in `ClaudeAgentOptions` to enable beta features.

1198 1236

1199<Warning>1237<Warning>

1200 The `context-1m-2025-08-07` beta is retired as of April 30, 2026. Passing this header with Claude Sonnet 4.5 or Sonnet 4 has no effect, and requests that exceed the standard 200k-token context window return an error. To use a 1M-token context window, migrate to [Claude Sonnet 4.6 or Claude Opus 4.6](https://platform.claude.com/docs/en/about-claude/models/overview), which include 1M context at standard pricing with no beta header required.1238 The `context-1m-2025-08-07` beta is retired as of April 30, 2026. Passing this header with Claude Sonnet 4.5 or Sonnet 4 has no effect, and requests that exceed the standard 200k-token context window return an error. To use a 1M-token context window, migrate to [Claude Sonnet 4.6, Claude Opus 4.6, or Claude Opus 4.7](https://platform.claude.com/docs/en/about-claude/models/overview), which include 1M context at standard pricing with no beta header required.

1201</Warning>1239</Warning>

1202 1240

1203### `McpSdkServerConfig`1241### `McpSdkServerConfig`

1446The `model_usage` dict maps model names to per-model usage. The inner dict keys use camelCase because the value is passed through unmodified from the underlying CLI process, matching the TypeScript [`ModelUsage`](/en/agent-sdk/typescript#model-usage) type:1484The `model_usage` dict maps model names to per-model usage. The inner dict keys use camelCase because the value is passed through unmodified from the underlying CLI process, matching the TypeScript [`ModelUsage`](/en/agent-sdk/typescript#model-usage) type:

1447 1485

1448| Key | Type | Description |1486| Key | Type | Description |

1449| -------------------------- | ------- | ------------------------------------------ |1487| -------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |

1450| `inputTokens` | `int` | Input tokens for this model. |1488| `inputTokens` | `int` | Input tokens for this model. |

1451| `outputTokens` | `int` | Output tokens for this model. |1489| `outputTokens` | `int` | Output tokens for this model. |

1452| `cacheReadInputTokens` | `int` | Cache read tokens for this model. |1490| `cacheReadInputTokens` | `int` | Cache read tokens for this model. |

1453| `cacheCreationInputTokens` | `int` | Cache creation tokens for this model. |1491| `cacheCreationInputTokens` | `int` | Cache creation tokens for this model. |

1454| `webSearchRequests` | `int` | Web search requests made by this model. |1492| `webSearchRequests` | `int` | Web search requests made by this model. |

1456| `contextWindow` | `int` | Context window size for this model. |1494| `contextWindow` | `int` | Context window size for this model. |

1457| `maxOutputTokens` | `int` | Maximum output token limit for this model. |1495| `maxOutputTokens` | `int` | Maximum output token limit for this model. |

1458 1496

2226{2264{

2227 "result": str, # Final result from the subagent2265 "result": str, # Final result from the subagent

2228 "usage": dict | None, # Token usage statistics2266 "usage": dict | None, # Token usage statistics

2229 "total_cost_usd": float | None, # Total cost in USD2267 "total_cost_usd": float | None, # Estimated total cost in USD

2230 "duration_ms": int | None, # Execution duration in milliseconds2268 "duration_ms": int | None, # Execution duration in milliseconds

2231}2269}

2232```2270```

agent-sdk/quickstart.md +16 −0

Details

59 ```59 ```

60 </Tab>60 </Tab>

61 </Tabs>61 </Tabs>

63 <Note>

64 The TypeScript SDK bundles a native Claude Code binary for your platform as an optional dependency, so you don't need to install Claude Code separately.

65 </Note>

62 </Step>66 </Step>

63 67

64 <Step title="Set your API key">68 <Step title="Set your API key">

305 309

306The example above uses `acceptEdits` mode, which auto-approves file operations so the agent can run without interactive prompts. If you want to prompt users for approval, use `default` mode and provide a [`canUseTool` callback](/en/agent-sdk/user-input) that collects user input. For more control, see [Permissions](/en/agent-sdk/permissions).310The example above uses `acceptEdits` mode, which auto-approves file operations so the agent can run without interactive prompts. If you want to prompt users for approval, use `default` mode and provide a [`canUseTool` callback](/en/agent-sdk/user-input) that collects user input. For more control, see [Permissions](/en/agent-sdk/permissions).

307 311

312## Troubleshooting

313

314### API error `thinking.type.enabled` is not supported for this model

315

316Claude Opus 4.7 replaces `thinking.type.enabled` with `thinking.type.adaptive`. Older Agent SDK versions fail with the following API error when you select `claude-opus-4-7`:

317

318```text theme={null}

319API Error: 400 {"type":"invalid_request_error","message":"\"thinking.type.enabled\" is not supported for this model. Use \"thinking.type.adaptive\" and \"output_config.effort\" to control thinking behavior."}

320```

321

322Upgrade to Agent SDK v0.2.111 or later to use Opus 4.7.

323

308## Next steps324## Next steps

309 325

310Now that you've created your first agent, learn how to extend its capabilities and tailor it to your use case:326Now that you've created your first agent, learn how to extend its capabilities and tailor it to your use case:

agent-sdk/secure-deployment.md +2 −2

Details

16 16

17## Threat model17## Threat model

18 18

19Agents can take unintended actions due to prompt injection (instructions embedded in content they process) or model error. Claude models are designed to resist this, and as analyzed in the [model card](https://www.anthropic.com/claude-opus-4-6-system-card), Claude Opus 4.6 is the most robust frontier model available.19Agents can take unintended actions due to prompt injection (instructions embedded in content they process) or model error. Claude models are designed to resist this; see the [model overview](https://platform.claude.com/docs/en/about-claude/models/overview) and the system card for the model you deploy for evaluation details.

20 20

21Defense in depth is still good practice though. For example, if an agent processes a malicious file that instructs it to send customer data to an external server, network controls can block that request entirely.21Defense in depth is still good practice though. For example, if an agent processes a malicious file that instructs it to send customer data to an external server, network controls can block that request entirely.

22 22

25Claude Code includes several security features that address common concerns. See the [security documentation](/en/security) for full details.25Claude Code includes several security features that address common concerns. See the [security documentation](/en/security) for full details.

26 26

27* **Permissions system**: Every tool and bash command can be configured to allow, block, or prompt the user for approval. Use glob patterns to create rules like "allow all npm commands" or "block any command with sudo". Organizations can set policies that apply across all users. See [permissions](/en/permissions).27* **Permissions system**: Every tool and bash command can be configured to allow, block, or prompt the user for approval. Use glob patterns to create rules like "allow all npm commands" or "block any command with sudo". Organizations can set policies that apply across all users. See [permissions](/en/permissions).

28* **Static analysis**: Before executing bash commands, Claude Code runs static analysis to identify potentially risky operations. Commands that modify system files or access sensitive directories are flagged and require explicit user approval.28* **Command parsing for permissions**: Before executing bash commands, Claude Code parses them into an AST and matches the result against your permission rules. Commands that cannot be parsed cleanly, or that do not match an allow rule, require explicit approval. A small set of constructs such as `eval` always require approval regardless of allow rules. This is a permission gate, not a sandbox; it does not infer whether a command is dangerous from its target path or effects.

29* **Web search summarization**: Search results are summarized rather than passing raw content directly into the context, reducing the risk of prompt injection from malicious web content.29* **Web search summarization**: Search results are summarized rather than passing raw content directly into the context, reducing the risk of prompt injection from malicious web content.

30* **Sandbox mode**: Bash commands can run in a sandboxed environment that restricts filesystem and network access. See the [sandboxing documentation](/en/sandboxing) for details.30* **Sandbox mode**: Bash commands can run in a sandboxed environment that restricts filesystem and network access. See the [sandboxing documentation](/en/sandboxing) for details.

31 31

agent-sdk/sessions.md +2 −0

Details

233 If a `resume` call returns a fresh session instead of the expected history, the most common cause is a mismatched `cwd`. Sessions are stored under `~/.claude/projects/<encoded-cwd>/*.jsonl`, where `<encoded-cwd>` is the absolute working directory with every non-alphanumeric character replaced by `-` (so `/Users/me/proj` becomes `-Users-me-proj`). If your resume call runs from a different directory, the SDK looks in the wrong place. The session file also needs to exist on the current machine.233 If a `resume` call returns a fresh session instead of the expected history, the most common cause is a mismatched `cwd`. Sessions are stored under `~/.claude/projects/<encoded-cwd>/*.jsonl`, where `<encoded-cwd>` is the absolute working directory with every non-alphanumeric character replaced by `-` (so `/Users/me/proj` becomes `-Users-me-proj`). If your resume call runs from a different directory, the SDK looks in the wrong place. The session file also needs to exist on the current machine.

234</Tip>234</Tip>

235 235

236To resume sessions across machines or in serverless environments, mirror transcripts to shared storage with a [`SessionStore` adapter](/en/agent-sdk/session-storage).

237

236### Fork to explore alternatives238### Fork to explore alternatives

237 239

238Forking creates a new session that starts with a copy of the original's history but diverges from that point. The fork gets its own session ID; the original's ID and history stay unchanged. You end up with two independent sessions you can resume separately.240Forking creates a new session that starts with a copy of the original's history but diverges from that point. The fork gets its own session ID; the original's ID and history stay unchanged. You end up with two independent sessions you can resume separately.

agent-sdk/skills.md +13 −12

Details

17When using the Claude Agent SDK, Skills are:17When using the Claude Agent SDK, Skills are:

18 18

191. **Defined as filesystem artifacts**: Created as `SKILL.md` files in specific directories (`.claude/skills/`)191. **Defined as filesystem artifacts**: Created as `SKILL.md` files in specific directories (`.claude/skills/`)

~~202. **Loaded from filesystem**: Skills are loaded from configured filesystem locations. You must specify `settingSources` (TypeScript) or `setting_sources` (Python) to load Skills from the filesystem~~202. **Loaded from filesystem**: Skills are loaded from filesystem locations governed by `settingSources` (TypeScript) or `setting_sources` (Python)

213. **Automatically discovered**: Once filesystem settings are loaded, Skill metadata is discovered at startup from user and project directories; full content loaded when triggered213. **Automatically discovered**: Once filesystem settings are loaded, Skill metadata is discovered at startup from user and project directories; full content loaded when triggered

224. **Model-invoked**: Claude autonomously chooses when to use them based on context224. **Model-invoked**: Claude autonomously chooses when to use them based on context

235. **Enabled via allowed\_tools**: Add `"Skill"` to your `allowed_tools` to enable Skills235. **Enabled via allowed\_tools**: Add `"Skill"` to your `allowed_tools` to enable Skills

25Unlike subagents (which can be defined programmatically), Skills must be created as filesystem artifacts. The SDK does not provide a programmatic API for registering Skills.25Unlike subagents (which can be defined programmatically), Skills must be created as filesystem artifacts. The SDK does not provide a programmatic API for registering Skills.

26 26

27<Note>27<Note>

28 **Default behavior**: By default, the SDK does not load any filesystem settings. To use Skills, you must explicitly configure `settingSources: ['user', 'project']` (TypeScript) or `setting_sources=["user", "project"]` (Python) in your options.28 Skills are discovered through the filesystem setting sources. With default `query()` options, the SDK loads user and project sources, so skills in `~/.claude/skills/` and `<cwd>/.claude/skills/` are available. If you set `settingSources` explicitly, include `'user'` or `'project'` to keep skill discovery, or use the [`plugins` option](/en/agent-sdk/plugins) to load skills from a specific path.

29</Note>29</Note>

30 30

31## Using Skills with the SDK31## Using Skills with the SDK

204 204

205### Skills Not Found205### Skills Not Found

206 206

207**Check settingSources configuration**: Skills are only loaded when you explicitly configure `settingSources`/`setting_sources`. This is the most common issue:207**Check settingSources configuration**: Skills are discovered through the `user` and `project` setting sources. If you set `settingSources`/`setting_sources` explicitly and omit those sources, skills are not loaded:

208 208

209<CodeGroup>209<CodeGroup>

210 ```python Python theme={null}210 ```python Python theme={null}

211 # Wrong - Skills won't be loaded211 # Skills not loaded: setting_sources excludes user and project

212 options = ClaudeAgentOptions(allowed_tools=["Skill"])212 options = ClaudeAgentOptions(setting_sources=[], allowed_tools=["Skill"])

213 213

214 # Correct - Skills will be loaded214 # Skills loaded: user and project sources included

215 options = ClaudeAgentOptions(215 options = ClaudeAgentOptions(

216 setting_sources=["user", "project"], # Required to load Skills216 setting_sources=["user", "project"],

217 allowed_tools=["Skill"],217 allowed_tools=["Skill"],

218 )218 )

219 ```219 ```

220 220

221 ```typescript TypeScript theme={null}221 ```typescript TypeScript theme={null}

222 // Wrong - Skills won't be loaded222 // Skills not loaded: settingSources excludes user and project

223 const options = {223 const options = {

224 settingSources: [],

224 allowedTools: ["Skill"]225 allowedTools: ["Skill"]

225 };226 };

226 227

227 // Correct - Skills will be loaded228 // Skills loaded: user and project sources included

228 const options = {229 const options = {

229 settingSources: ["user", "project"], // Required to load Skills230 settingSources: ["user", "project"],

230 allowedTools: ["Skill"]231 allowedTools: ["Skill"]

231 };232 };

232 ```233 ```

241 # Ensure your cwd points to the directory containing .claude/skills/242 # Ensure your cwd points to the directory containing .claude/skills/

242 options = ClaudeAgentOptions(243 options = ClaudeAgentOptions(

243 cwd="/path/to/project", # Must contain .claude/skills/244 cwd="/path/to/project", # Must contain .claude/skills/

244 setting_sources=["user", "project"], # Required to load Skills245 setting_sources=["user", "project"], # Loads skills from these sources

245 allowed_tools=["Skill"],246 allowed_tools=["Skill"],

246 )247 )

247 ```248 ```

250 // Ensure your cwd points to the directory containing .claude/skills/251 // Ensure your cwd points to the directory containing .claude/skills/

251 const options = {252 const options = {

252 cwd: "/path/to/project", // Must contain .claude/skills/253 cwd: "/path/to/project", // Must contain .claude/skills/

253 settingSources: ["user", "project"], // Required to load Skills254 settingSources: ["user", "project"], // Loads skills from these sources

254 allowedTools: ["Skill"]255 allowedTools: ["Skill"]

255 };256 };

256 ```257 ```

agent-sdk/slash-commands.md +10 −43

Details

6 6

7> Learn how to use slash commands to control Claude Code sessions through the SDK7> Learn how to use slash commands to control Claude Code sessions through the SDK

8 8

9Slash commands provide a way to control Claude Code sessions with special commands that start with `/`. These commands can be sent through the SDK to perform actions like clearing conversation history, compacting messages, or getting help.9Slash commands provide a way to control Claude Code sessions with special commands that start with `/`. These commands can be sent through the SDK to perform actions like compacting context, listing context usage, or invoking custom commands. Only commands that work without an interactive terminal are dispatchable through the SDK; the `system/init` message lists the ones available in your session.

10 10

11## Discovering Available Slash Commands11## Discovering Available Slash Commands

12 12

22 })) {22 })) {

23 if (message.type === "system" && message.subtype === "init") {23 if (message.type === "system" && message.subtype === "init") {

24 console.log("Available slash commands:", message.slash_commands);24 console.log("Available slash commands:", message.slash_commands);

~~25 // Example output: ["/compact", "/clear", "/help"]~~25 // Example output: ["/compact", "/context", "/cost"]

26 }26 }

27 }27 }

28 ```28 ```

36 async for message in query(prompt="Hello Claude", options=ClaudeAgentOptions(max_turns=1)):36 async for message in query(prompt="Hello Claude", options=ClaudeAgentOptions(max_turns=1)):

37 if isinstance(message, SystemMessage) and message.subtype == "init":37 if isinstance(message, SystemMessage) and message.subtype == "init":

38 print("Available slash commands:", message.data["slash_commands"])38 print("Available slash commands:", message.data["slash_commands"])

~~39 # Example output: ["/compact", "/clear", "/help"]~~39 # Example output: ["/compact", "/context", "/cost"]

40 40

41 41

42 asyncio.run(main())42 asyncio.run(main())

117 ```117 ```

118</CodeGroup>118</CodeGroup>

119 119

120### `/clear` - Clear Conversation120### Clearing the conversation

121 121

122The `/clear` command starts a fresh conversation by clearing all previous history:122The interactive `/clear` command is not available in the SDK. Each `query()` call already starts a fresh conversation, so to clear context, end the current `query()` and start a new one. The previous conversation stays on disk and can be returned to by passing its session ID to the [`resume` option](/en/agent-sdk/sessions#resume-by-id).

~~123~~

124<CodeGroup>

125 ```typescript TypeScript theme={null}

126 import { query } from "@anthropic-ai/claude-agent-sdk";

~~127~~

128 // Clear conversation and start fresh

129 for await (const message of query({

130 prompt: "/clear",

131 options: { maxTurns: 1 }

132 })) {

133 if (message.type === "system" && message.subtype === "init") {

134 console.log("Conversation cleared, new session started");

135 console.log("Session ID:", message.session_id);

136 }

137 }

138 ```

~~139~~

140 ```python Python theme={null}

141 import asyncio

142 from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage

~~143~~

~~144~~

145 async def main():

146 # Clear conversation and start fresh

147 async for message in query(prompt="/clear", options=ClaudeAgentOptions(max_turns=1)):

148 if isinstance(message, SystemMessage) and message.subtype == "init":

149 print("Conversation cleared, new session started")

150 print("Session ID:", message.data["session_id"])

~~151~~

~~152~~

153 asyncio.run(main())

154 ```

155</CodeGroup>

156 123

157## Creating Custom Slash Commands124## Creating Custom Slash Commands

158 125

196---163---

197allowed-tools: Read, Grep, Glob164allowed-tools: Read, Grep, Glob

198description: Run security vulnerability scan165description: Run security vulnerability scan

199model: claude-opus-4-6166model: claude-opus-4-7

200---167---

201 168

202Analyze the codebase for security vulnerabilities including:169Analyze the codebase for security vulnerabilities including:

232 if (message.type === "system" && message.subtype === "init") {199 if (message.type === "system" && message.subtype === "init") {

233 // Will include both built-in and custom commands200 // Will include both built-in and custom commands

234 console.log("Available commands:", message.slash_commands);201 console.log("Available commands:", message.slash_commands);

235 // Example: ["/compact", "/clear", "/help", "/refactor", "/security-check"]202 // Example: ["/compact", "/context", "/cost", "/refactor", "/security-check"]

236 }203 }

237 }204 }

238 ```205 ```

257 if isinstance(message, SystemMessage) and message.subtype == "init":224 if isinstance(message, SystemMessage) and message.subtype == "init":

258 # Will include both built-in and custom commands225 # Will include both built-in and custom commands

259 print("Available commands:", message.data["slash_commands"])226 print("Available commands:", message.data["slash_commands"])

260 # Example: ["/compact", "/clear", "/help", "/refactor", "/security-check"]227 # Example: ["/compact", "/context", "/cost", "/refactor", "/security-check"]

261 228

262 229

263 asyncio.run(main())230 asyncio.run(main())

325 292

326```markdown theme={null}293```markdown theme={null}

327---294---

328allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)295allowed-tools: Bash(git add *), Bash(git status *), Bash(git commit *)

329description: Create a git commit296description: Create a git commit

330---297---

331 298

383 350

384```markdown theme={null}351```markdown theme={null}

385---352---

386allowed-tools: Read, Grep, Glob, Bash(git diff:*)353allowed-tools: Read, Grep, Glob, Bash(git diff *)

387description: Comprehensive code review354description: Comprehensive code review

388---355---

389 356

agent-sdk/structured-outputs.md +1 −1

Details

6 6

7> Return validated JSON from agent workflows using JSON Schema, Zod, or Pydantic. Get type-safe, structured data after multi-turn tool use.7> Return validated JSON from agent workflows using JSON Schema, Zod, or Pydantic. Get type-safe, structured data after multi-turn tool use.

8 8

9Structured outputs let you define the exact shape of data you want back from an agent. The agent can use any tools it needs to complete the task, and you still get validated JSON matching your schema at the end. Define a [JSON Schema](https://json-schema.org/understanding-json-schema/about) for the structure you need, and the SDK guarantees the output matches it.9Structured outputs let you define the exact shape of data you want back from an agent. The agent can use any tools it needs to complete the task, and you still get validated JSON matching your schema at the end. Define a [JSON Schema](https://json-schema.org/understanding-json-schema/about) for the structure you need, and the SDK validates the output against it, re-prompting on mismatch. If validation does not succeed within the retry limit, the result is an error instead of structured data; see [Error handling](#error-handling).

10 10

11For full type safety, use [Zod](#type-safe-schemas-with-zod-and-pydantic) (TypeScript) or [Pydantic](#type-safe-schemas-with-zod-and-pydantic) (Python) to define your schema and get strongly-typed objects back.11For full type safety, use [Zod](#type-safe-schemas-with-zod-and-pydantic) (TypeScript) or [Pydantic](#type-safe-schemas-with-zod-and-pydantic) (Python) to define your schema and get strongly-typed objects back.

12 12

agent-sdk/subagents.md +10 −3

Details

160### AgentDefinition configuration160### AgentDefinition configuration

161 161

163| :------------ | :------------------------------------------- | :------- | :--------------------------------------------------------------- |163| :---------------- | :---------------------------------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |

176

177In the Python SDK, these field names use camelCase to match the wire format. See the [`AgentDefinition` reference](/en/agent-sdk/python#agent-definition) for details.

171 178

172<Note>179<Note>

173 Subagents cannot spawn their own subagents. Don't include `Agent` in a subagent's `tools` array.180 Subagents cannot spawn their own subagents. Don't include `Agent` in a subagent's `tools` array.

agent-sdk/typescript.md +148 −21

Details

18npm install @anthropic-ai/claude-agent-sdk18npm install @anthropic-ai/claude-agent-sdk

19```19```

20 20

21<Note>

22 The SDK bundles a native Claude Code binary for your platform as an optional dependency such as `@anthropic-ai/claude-agent-sdk-darwin-arm64`. You don't need to install Claude Code separately. If your package manager skips optional dependencies, the SDK throws `Native CLI binary for <platform> not found`; set [`pathToClaudeCodeExecutable`](#options) to a separately installed `claude` binary instead.

23</Note>

21## Functions25## Functions

22 26

23### `query()`27### `query()`

45 49

46Returns a [`Query`](#query-object) object that extends `AsyncGenerator<`[`SDKMessage`](#sdk-message)`, void>` with additional methods.50Returns a [`Query`](#query-object) object that extends `AsyncGenerator<`[`SDKMessage`](#sdk-message)`, void>` with additional methods.

47 51

52### `startup()`

54Pre-warms the CLI subprocess by spawning it and completing the initialize handshake before a prompt is available. The returned [`WarmQuery`](#warm-query) handle accepts a prompt later and writes it to an already-ready process, so the first `query()` call resolves without paying subprocess spawn and initialization cost inline.

56```typescript theme={null}

57function startup(params?: {

58 options?: Options;

59 initializeTimeoutMs?: number;

60}): Promise<WarmQuery>;

61```

63#### Parameters

65| Parameter | Type | Description |

66| :-------------------- | :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

67| `options` | [`Options`](#options) | Optional configuration object. Same as the `options` parameter to `query()` |

68| `initializeTimeoutMs` | `number` | Maximum time in milliseconds to wait for subprocess initialization. Defaults to `60000`. If initialization does not complete in time, the promise rejects with a timeout error |

70#### Returns

72Returns a `Promise<`[`WarmQuery`](#warm-query)`>` that resolves once the subprocess has spawned and completed its initialize handshake.

74#### Example

76Call `startup()` early, for example on application boot, then call `.query()` on the returned handle once a prompt is ready. This moves subprocess spawn and initialization out of the critical path.

78```typescript theme={null}

79import { startup } from "@anthropic-ai/claude-agent-sdk";

81// Pay startup cost upfront

82const warm = await startup({ options: { maxTurns: 3 } });

84// Later, when a prompt is ready, this is immediate

85for await (const message of warm.query("What files are here?")) {

86 console.log(message);

87}

88```

48### `tool()`90### `tool()`

49 91

50Creates a type-safe MCP tool definition for use with SDK MCP servers.92Creates a type-safe MCP tool definition for use with SDK MCP servers.

277Configuration object for the `query()` function.319Configuration object for the `query()` function.

278 320

280| :-------------------------------- | :--------------------------------------------------------------------------------------------------- | :------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |322| :-------------------------------- | :------------------------------------------------------------------------------------------------------- | :------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

302| `hooks` | `Partial<Record<`[`HookEvent`](#hook-event)`, `[`HookCallbackMatcher`](#hook-callback-matcher)`[]>>` | `{}` | Hook callbacks for events |344| `hooks` | `Partial<Record<`[`HookEvent`](#hook-event)`, `[`HookCallbackMatcher`](#hook-callback-matcher)`[]>>` | `{}` | Hook callbacks for events |

307| `mcpServers` | `Record<string, [`McpServerConfig`](#mcp-server-config)>` | `{}` | MCP server configurations |349| `mcpServers` | `Record<string, [`McpServerConfig`](#mcp-server-config)>` | `{}` | MCP server configurations |

309| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Define output format for agent results. See [Structured outputs](/en/agent-sdk/structured-outputs) for details |351| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Define output format for agent results. See [Structured outputs](/en/agent-sdk/structured-outputs) for details |

320| `settingSources` | [`SettingSource`](#setting-source)`[]` | `[]` (no settings) | Control which filesystem settings to load. When omitted, no settings are loaded. **Note:** Must include `'project'` to load CLAUDE.md files |362| `sessionStore` | [`SessionStore`](/en/agent-sdk/session-storage#the-session-store-interface) | `undefined` | Mirror session transcripts to an external backend so any host can resume them. See [Persist sessions to external storage](/en/agent-sdk/session-storage) |

363| `settingSources` | [`SettingSource`](#setting-source)`[]` | CLI defaults (all sources) | Control which filesystem settings to load. Pass `[]` to disable user, project, and local settings. Managed policy settings load regardless. See [Use Claude Code features](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

324| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string }` | `undefined` (minimal prompt) | System prompt configuration. Pass a string for custom prompt, or `{ type: 'preset', preset: 'claude_code' }` to use Claude Code's system prompt. When using the preset object form, add `append` to extend the system prompt with additional instructions |367| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (minimal prompt) | System prompt configuration. Pass a string for custom prompt, or `{ type: 'preset', preset: 'claude_code' }` to use Claude Code's system prompt. When using the preset object form, add `append` to extend it with additional instructions, and set `excludeDynamicSections: true` to move per-session context into the first user message for [better prompt-cache reuse across machines](/en/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

325| `thinking` | [`ThinkingConfig`](#thinking-config) | `{ type: 'adaptive' }` for supported models | Controls Claude's thinking/reasoning behavior. See [`ThinkingConfig`](#thinking-config) for options |368| `thinking` | [`ThinkingConfig`](#thinking-config) | `{ type: 'adaptive' }` for supported models | Controls Claude's thinking/reasoning behavior. See [`ThinkingConfig`](#thinking-config) for options |

327| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Tool configuration. Pass an array of tool names or use the preset to get Claude Code's default tools |370| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Tool configuration. Pass an array of tool names or use the preset to get Claude Code's default tools |

378| `close()` | Close the query and terminate the underlying process. Forcefully ends the query and cleans up all resources |421| `close()` | Close the query and terminate the underlying process. Forcefully ends the query and cleans up all resources |

379 422

423### `WarmQuery`

424

425Handle returned by [`startup()`](#startup). The subprocess is already spawned and initialized, so calling `query()` on this handle writes the prompt directly to a ready process with no startup latency.

426

427```typescript theme={null}

428interface WarmQuery extends AsyncDisposable {

429 query(prompt: string | AsyncIterable<SDKUserMessage>): Query;

430 close(): void;

431}

432```

433

434#### Methods

435

436| Method | Description |

437| :-------------- | :------------------------------------------------------------------------------------------------------------------------ |

438| `query(prompt)` | Send a prompt to the pre-warmed subprocess and return a [`Query`](#query-object). Can only be called once per `WarmQuery` |

439| `close()` | Close the subprocess without sending a prompt. Use this to discard a warm query that is no longer needed |

440

441`WarmQuery` implements `AsyncDisposable`, so it can be used with `await using` for automatic cleanup.

442

380### `SDKControlInitializeResponse`443### `SDKControlInitializeResponse`

381 444

382Return type of `initializationResult()`. Contains session initialization data.445Return type of `initializationResult()`. Contains session initialization data.

403 tools?: string[];466 tools?: string[];

404 disallowedTools?: string[];467 disallowedTools?: string[];

405 prompt: string;468 prompt: string;

406 model?: "sonnet" | "opus" | "haiku" | "inherit";469 model?: string;

407 mcpServers?: AgentMcpServerSpec[];470 mcpServers?: AgentMcpServerSpec[];

408 skills?: string[];471 skills?: string[];

472 initialPrompt?: string;

409 maxTurns?: number;473 maxTurns?: number;

474 background?: boolean;

475 memory?: "user" | "project" | "local";

477 permissionMode?: PermissionMode;

410 criticalSystemReminder_EXPERIMENTAL?: string;478 criticalSystemReminder_EXPERIMENTAL?: string;

411};479};

412```480```

413 481

415| :------------------------------------ | :------- | :---------------------------------------------------------------------------- |483| :------------------------------------ | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

416| `description` | Yes | Natural language description of when to use this agent |484| `description` | Yes | Natural language description of when to use this agent |

417| `tools` | No | Array of allowed tool names. If omitted, inherits all tools from parent |485| `tools` | No | Array of allowed tool names. If omitted, inherits all tools from parent |

418| `disallowedTools` | No | Array of tool names to explicitly disallow for this agent |486| `disallowedTools` | No | Array of tool names to explicitly disallow for this agent |

419| `prompt` | Yes | The agent's system prompt |487| `prompt` | Yes | The agent's system prompt |

420| `model` | No | Model override for this agent. If omitted or `'inherit'`, uses the main model |488| `model` | No | Model override for this agent. Accepts an alias such as `'sonnet'`, `'opus'`, `'haiku'`, `'inherit'`, or a full model ID. If omitted or `'inherit'`, uses the main model |

421| `mcpServers` | No | MCP server specifications for this agent |489| `mcpServers` | No | MCP server specifications for this agent |

422| `skills` | No | Array of skill names to preload into the agent context |490| `skills` | No | Array of skill names to preload into the agent context |

491| `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main thread agent |

423| `maxTurns` | No | Maximum number of agentic turns (API round-trips) before stopping |492| `maxTurns` | No | Maximum number of agentic turns (API round-trips) before stopping |

493| `background` | No | Run this agent as a non-blocking background task when invoked |

494| `memory` | No | Memory source for this agent: `'user'`, `'project'`, or `'local'` |

495| `effort` | No | Reasoning effort level for this agent. Accepts a named level or an integer |

496| `permissionMode` | No | Permission mode for tool execution within this agent. See [`PermissionMode`](#permission-mode) |

424| `criticalSystemReminder_EXPERIMENTAL` | No | Experimental: Critical reminder added to the system prompt |497| `criticalSystemReminder_EXPERIMENTAL` | No | Experimental: Critical reminder added to the system prompt |

425 498

426### `AgentMcpServerSpec`499### `AgentMcpServerSpec`

449 522

450#### Default behavior523#### Default behavior

451 524

452When `settingSources` is **omitted** or **undefined**, the SDK does **not** load any filesystem settings. This provides isolation for SDK applications.525When `settingSources` is omitted or `undefined`, `query()` loads the same filesystem settings as the Claude Code CLI: user, project, and local. Managed policy settings are loaded in all cases. See [What settingSources does not control](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) for inputs that are read regardless of this option, and how to disable them.

453 526

454#### Why use settingSources527#### Why use settingSources

455 528

456**Load all filesystem settings (legacy behavior):**529**Disable filesystem settings:**

530

531```typescript theme={null}

532// Do not load user, project, or local settings from disk

533const result = query({

534 prompt: "Analyze this code",

535 options: { settingSources: [] }

536});

537```

538

539**Load all filesystem settings explicitly:**

457 540

458```typescript theme={null}541```typescript theme={null}

459// Load all settings like SDK v0.0.x did

460const result = query({542const result = query({

461 prompt: "Analyze this code",543 prompt: "Analyze this code",

462 options: {544 options: {

493**SDK-only applications:**575**SDK-only applications:**

494 576

495```typescript theme={null}577```typescript theme={null}

496// Define everything programmatically (default behavior)578// Define everything programmatically.

497// No filesystem dependencies - settingSources defaults to []579// Pass [] to opt out of filesystem setting sources.

498const result = query({580const result = query({

499 prompt: "Review this PR",581 prompt: "Review this PR",

500 options: {582 options: {

501 // settingSources: [] is the default, no need to specify583 settingSources: [],

502 agents: {584 agents: {

503 /* ... */585 /* ... */

504 },586 },

519 options: {601 options: {

520 systemPrompt: {602 systemPrompt: {

521 type: "preset",603 type: "preset",

522 preset: "claude_code" // Required to use CLAUDE.md604 preset: "claude_code" // Use Claude Code's system prompt

523 },605 },

524 settingSources: ["project"], // Loads CLAUDE.md from project directory606 settingSources: ["project"], // Loads CLAUDE.md from project directory

525 allowedTools: ["Read", "Write", "Edit"]607 allowedTools: ["Read", "Write", "Edit"]

5352. Project settings (`.claude/settings.json`)6172. Project settings (`.claude/settings.json`)

5363. User settings (`~/.claude/settings.json`)6183. User settings (`~/.claude/settings.json`)

537 619

538Programmatic options (like `agents`, `allowedTools`) always override filesystem settings.620Programmatic options such as `agents` and `allowedTools` override user, project, and local filesystem settings. Managed policy settings take precedence over programmatic options.

539 621

540### `PermissionMode`622### `PermissionMode`

541 623

723 | SDKHookStartedMessage805 | SDKHookStartedMessage

724 | SDKHookProgressMessage806 | SDKHookProgressMessage

725 | SDKHookResponseMessage807 | SDKHookResponseMessage

808 | SDKPluginInstallMessage

726 | SDKToolProgressMessage809 | SDKToolProgressMessage

727 | SDKAuthStatusMessage810 | SDKAuthStatusMessage

728 | SDKTaskNotificationMessage811 | SDKTaskNotificationMessage

729 | SDKTaskStartedMessage812 | SDKTaskStartedMessage

730 | SDKTaskProgressMessage813 | SDKTaskProgressMessage

814 | SDKTaskUpdatedMessage

731 | SDKFilesPersistedEvent815 | SDKFilesPersistedEvent

732 | SDKToolUseSummaryMessage816 | SDKToolUseSummaryMessage

733 | SDKRateLimitEvent817 | SDKRateLimitEvent

765 message: MessageParam; // From Anthropic SDK849 message: MessageParam; // From Anthropic SDK

766 parent_tool_use_id: string | null;850 parent_tool_use_id: string | null;

767 isSynthetic?: boolean;851 isSynthetic?: boolean;

852 shouldQuery?: boolean;

768 tool_use_result?: unknown;853 tool_use_result?: unknown;

769};854};

770```855```

771 856

857Set `shouldQuery` to `false` to append the message to the transcript without triggering an assistant turn. The message is held and merged into the next user message that does trigger a turn. Use this to inject context, such as the output of a command you ran out of band, without spending a model call on it.

858

772### `SDKUserMessageReplay`859### `SDKUserMessageReplay`

773 860

774Replayed user message with required UUID.861Replayed user message with required UUID.

891};978};

892```979```

893 980

981### `SDKPluginInstallMessage`

982

983Plugin installation progress event. Emitted when [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/en/env-vars) is set, so your Agent SDK application can track marketplace plugin installation before the first turn. The `started` and `completed` statuses bracket the overall install. The `installed` and `failed` statuses report individual marketplaces and include `name`.

984

985```typescript theme={null}

986type SDKPluginInstallMessage = {

987 type: "system";

988 subtype: "plugin_install";

989 status: "started" | "installed" | "failed" | "completed";

990 name?: string;

991 error?: string;

992 uuid: UUID;

993 session_id: string;

994};

995```

996

894### `SDKPermissionDenial`997### `SDKPermissionDenial`

895 998

896Information about a denied tool use.999Information about a denied tool use.

2161```2264```

2162 2265

2163<Warning>2266<Warning>

2164 The `context-1m-2025-08-07` beta is retired as of April 30, 2026. Passing this value with Claude Sonnet 4.5 or Sonnet 4 has no effect, and requests that exceed the standard 200k-token context window return an error. To use a 1M-token context window, migrate to [Claude Sonnet 4.6 or Claude Opus 4.6](https://platform.claude.com/docs/en/about-claude/models/overview), which include 1M context at standard pricing with no beta header required.2267 The `context-1m-2025-08-07` beta is retired as of April 30, 2026. Passing this value with Claude Sonnet 4.5 or Sonnet 4 has no effect, and requests that exceed the standard 200k-token context window return an error. To use a 1M-token context window, migrate to [Claude Sonnet 4.6, Claude Opus 4.6, or Claude Opus 4.7](https://platform.claude.com/docs/en/about-claude/models/overview), which include 1M context at standard pricing with no beta header required.

2165</Warning>2268</Warning>

2166 2269

2167### `SlashCommand`2270### `SlashCommand`

2186 displayName: string;2289 displayName: string;

2187 description: string;2290 description: string;

2188 supportsEffort?: boolean;2291 supportsEffort?: boolean;

2190 supportsAdaptiveThinking?: boolean;2293 supportsAdaptiveThinking?: boolean;

2191 supportsFastMode?: boolean;2294 supportsFastMode?: boolean;

2192};2295};

2268 2371

2269### `ModelUsage`2372### `ModelUsage`

2270 2373

2271Per-model usage statistics returned in result messages.2374Per-model usage statistics returned in result messages. The `costUSD` value is a client-side estimate. See [Track cost and usage](/en/agent-sdk/cost-tracking) for billing caveats.

2272 2375

2273```typescript theme={null}2376```typescript theme={null}

2274type ModelUsage = {2377type ModelUsage = {

2585};2688};

2586```2689```

2587 2690

2691### `SDKTaskUpdatedMessage`

2692

2693Emitted when a background task's state changes, such as when it transitions from `running` to `completed`. Merge `patch` into your local task map keyed by `task_id`. The `end_time` field is a Unix epoch timestamp in milliseconds, comparable with `Date.now()`.

2694

2695```typescript theme={null}

2696type SDKTaskUpdatedMessage = {

2697 type: "system";

2698 subtype: "task_updated";

2699 task_id: string;

2700 patch: {

2701 status?: "pending" | "running" | "completed" | "failed" | "killed";

2702 description?: string;

2703 end_time?: number;

2704 total_paused_ms?: number;

2705 error?: string;

2706 is_backgrounded?: boolean;

2707 };

2708 uuid: UUID;

2709 session_id: string;

2710};

2711```

2712

2588### `SDKFilesPersistedEvent`2713### `SDKFilesPersistedEvent`

2589 2714

2590Emitted when file checkpoints are persisted to disk.2715Emitted when file checkpoints are persisted to disk.

2717```typescript theme={null}2842```typescript theme={null}

2718type SandboxNetworkConfig = {2843type SandboxNetworkConfig = {

2719 allowedDomains?: string[];2844 allowedDomains?: string[];

2845 deniedDomains?: string[];

2720 allowManagedDomainsOnly?: boolean;2846 allowManagedDomainsOnly?: boolean;

2721 allowLocalBinding?: boolean;2847 allowLocalBinding?: boolean;

2722 allowUnixSockets?: string[];2848 allowUnixSockets?: string[];

2727```2853```

2728 2854

2730| :------------------------ | :--------- | :---------- | :---------------------------------------------------------------- |2856| :------------------------ | :--------- | :---------- | :------------------------------------------------------------------------------------------ |

agent-sdk/typescript-v2-preview.md +16 −12

Details

24npm install @anthropic-ai/claude-agent-sdk24npm install @anthropic-ai/claude-agent-sdk

25```25```

26 26

27<Note>

28 The SDK bundles a native Claude Code binary for your platform as an optional dependency, so you don't need to install Claude Code separately.

29</Note>

27## Quick start31## Quick start

28 32

29### One-shot prompt33### One-shot prompt

34import { unstable_v2_prompt } from "@anthropic-ai/claude-agent-sdk";38import { unstable_v2_prompt } from "@anthropic-ai/claude-agent-sdk";

35 39

36const result = await unstable_v2_prompt("What is 2 + 2?", {40const result = await unstable_v2_prompt("What is 2 + 2?", {

~~37 model: "claude-opus-4-6"~~41 model: "claude-opus-4-7"

38});42});

39if (result.subtype === "success") {43if (result.subtype === "success") {

40 console.log(result.result);44 console.log(result.result);

49 53

50 const q = query({54 const q = query({

51 prompt: "What is 2 + 2?",55 prompt: "What is 2 + 2?",

~~52 options: { model: "claude-opus-4-6" }~~56 options: { model: "claude-opus-4-7" }

53 });57 });

54 58

55 for await (const msg of q) {59 for await (const msg of q) {

75import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk";79import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk";

76 80

77await using session = unstable_v2_createSession({81await using session = unstable_v2_createSession({

~~78 model: "claude-opus-4-6"~~82 model: "claude-opus-4-7"

79});83});

80 84

81await session.send("Hello!");85await session.send("Hello!");

101 105

102 const q = query({106 const q = query({

103 prompt: "Hello!",107 prompt: "Hello!",

104 options: { model: "claude-opus-4-6" }108 options: { model: "claude-opus-4-7" }

105 });109 });

106 110

107 for await (const msg of q) {111 for await (const msg of q) {

126import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk";130import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk";

127 131

128await using session = unstable_v2_createSession({132await using session = unstable_v2_createSession({

129 model: "claude-opus-4-6"133 model: "claude-opus-4-7"

130});134});

131 135

132// Turn 1136// Turn 1

180 184

181 const q = query({185 const q = query({

182 prompt: createInputStream(),186 prompt: createInputStream(),

183 options: { model: "claude-opus-4-6" }187 options: { model: "claude-opus-4-7" }

184 });188 });

185 189

186 for await (const msg of q) {190 for await (const msg of q) {

219 223

220// Create initial session and have a conversation224// Create initial session and have a conversation

221const session = unstable_v2_createSession({225const session = unstable_v2_createSession({

222 model: "claude-opus-4-6"226 model: "claude-opus-4-7"

223});227});

224 228

225await session.send("Remember this number: 42");229await session.send("Remember this number: 42");

237 241

238// Later: resume the session using the stored ID242// Later: resume the session using the stored ID

239await using resumedSession = unstable_v2_resumeSession(sessionId!, {243await using resumedSession = unstable_v2_resumeSession(sessionId!, {

240 model: "claude-opus-4-6"244 model: "claude-opus-4-7"

241});245});

242 246

243await resumedSession.send("What number did I ask you to remember?");247await resumedSession.send("What number did I ask you to remember?");

256 // Create initial session260 // Create initial session

257 const initialQuery = query({261 const initialQuery = query({

258 prompt: "Remember this number: 42",262 prompt: "Remember this number: 42",

259 options: { model: "claude-opus-4-6" }263 options: { model: "claude-opus-4-7" }

260 });264 });

261 265

262 // Get session ID from any message266 // Get session ID from any message

278 const resumedQuery = query({282 const resumedQuery = query({

279 prompt: "What number did I ask you to remember?",283 prompt: "What number did I ask you to remember?",

280 options: {284 options: {

281 model: "claude-opus-4-6",285 model: "claude-opus-4-7",

282 resume: sessionId286 resume: sessionId

283 }287 }

284 });288 });

305import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk";309import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk";

306 310

307await using session = unstable_v2_createSession({311await using session = unstable_v2_createSession({

308 model: "claude-opus-4-6"312 model: "claude-opus-4-7"

309});313});

310// Session closes automatically when the block exits314// Session closes automatically when the block exits

311```315```

316import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk";320import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk";

317 321

318const session = unstable_v2_createSession({322const session = unstable_v2_createSession({

319 model: "claude-opus-4-6"323 model: "claude-opus-4-7"

320});324});

321// ... use the session ...325// ... use the session ...

322session.close();326session.close();

amazon-bedrock.md +8 −5

Details

160 Pin specific model versions when deploying to multiple users. Without pinning, model aliases such as `sonnet` and `opus` resolve to the latest version, which may not yet be available in your Bedrock account when Anthropic releases an update. Claude Code [falls back](#startup-model-checks) to the previous version at startup when the latest is unavailable, but pinning lets you control when your users move to a new model.160 Pin specific model versions when deploying to multiple users. Without pinning, model aliases such as `sonnet` and `opus` resolve to the latest version, which may not yet be available in your Bedrock account when Anthropic releases an update. Claude Code [falls back](#startup-model-checks) to the previous version at startup when the latest is unavailable, but pinning lets you control when your users move to a new model.

161</Warning>161</Warning>

162 162

163Set these environment variables to specific Bedrock model IDs:163Set these environment variables to specific Bedrock model IDs.

164

165Without `ANTHROPIC_DEFAULT_OPUS_MODEL`, the `opus` alias on Bedrock resolves to Opus 4.6. Set it to the Opus 4.7 ID to use the latest model:

164 166

165```bash theme={null}167```bash theme={null}

166export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-6-v1'168export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-7'

167export ANTHROPIC_DEFAULT_SONNET_MODEL='us.anthropic.claude-sonnet-4-6'169export ANTHROPIC_DEFAULT_SONNET_MODEL='us.anthropic.claude-sonnet-4-6'

168export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'170export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

169```171```

197 199

198The `ANTHROPIC_DEFAULT_*_MODEL` environment variables configure one inference profile per model family. If your organization needs to expose several versions of the same family in the `/model` picker, each routed to its own application inference profile ARN, use the `modelOverrides` setting in your [settings file](/en/settings#settings-files) instead.200The `ANTHROPIC_DEFAULT_*_MODEL` environment variables configure one inference profile per model family. If your organization needs to expose several versions of the same family in the `/model` picker, each routed to its own application inference profile ARN, use the `modelOverrides` setting in your [settings file](/en/settings#settings-files) instead.

199 201

200This example maps three Opus versions to distinct ARNs so users can switch between them without bypassing your organization's inference profiles:202This example maps four Opus versions to distinct ARNs so users can switch between them without bypassing your organization's inference profiles:

201 203

202```json theme={null}204```json theme={null}

203{205{

204 "modelOverrides": {206 "modelOverrides": {

207 "claude-opus-4-7": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-47-prod",

205 "claude-opus-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-46-prod",208 "claude-opus-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-46-prod",

206 "claude-opus-4-5-20251101": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-45-prod",209 "claude-opus-4-5-20251101": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-45-prod",

207 "claude-opus-4-1-20250805": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-41-prod"210 "claude-opus-4-1-20250805": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-41-prod"

269 272

270## 1M token context window273## 1M token context window

271 274

272Claude Opus 4.6 and Sonnet 4.6 support the [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) on Amazon Bedrock. Claude Code automatically enables the extended context window when you select a 1M model variant.275Claude Opus 4.7, Opus 4.6, and Sonnet 4.6 support the [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) on Amazon Bedrock. Claude Code automatically enables the extended context window when you select a 1M model variant.

273 276

274To enable the 1M context window for your pinned model, append `[1m]` to the model ID. See [Pin models for third-party deployments](/en/model-config#pin-models-for-third-party-deployments) for details.277The [setup wizard](#sign-in-with-bedrock) offers a 1M context option when it pins models. To enable it for a manually pinned model instead, append `[1m]` to the model ID. See [Pin models for third-party deployments](/en/model-config#pin-models-for-third-party-deployments) for details.

275 278

276## AWS Guardrails279## AWS Guardrails

277 280

best-practices.md +1 −1

Details

398* For more control, run `/compact <instructions>`, like `/compact Focus on the API changes`398* For more control, run `/compact <instructions>`, like `/compact Focus on the API changes`

399* To compact only part of the conversation, use `Esc + Esc` or `/rewind`, select a message checkpoint, and choose **Summarize from here**. This condenses messages from that point forward while keeping earlier context intact.399* To compact only part of the conversation, use `Esc + Esc` or `/rewind`, select a message checkpoint, and choose **Summarize from here**. This condenses messages from that point forward while keeping earlier context intact.

400* Customize compaction behavior in CLAUDE.md with instructions like `"When compacting, always preserve the full list of modified files and any test commands"` to ensure critical context survives summarization400* Customize compaction behavior in CLAUDE.md with instructions like `"When compacting, always preserve the full list of modified files and any test commands"` to ensure critical context survives summarization

401* For quick questions that don't need to stay in context, use [`/btw`](/en/interactive-mode#side-questions-with-btw). The answer appears in a dismissible overlay and never enters conversation history, so you can check a detail without growing context.401* For quick questions that don't need to stay in context, use [`/btw`](/en/interactive-mode#side-questions-with-%2Fbtw). The answer appears in a dismissible overlay and never enters conversation history, so you can check a detail without growing context.

402 402

403### Use subagents for investigation403### Use subagents for investigation

404 404

claude-code-on-the-web.md +57 −9

Details

109 </Step>109 </Step>

110</Steps>110</Steps>

111 111

112### Link artifacts back to the session

113

114Each cloud session has a transcript URL on claude.ai, and the session can read its own ID from the `CLAUDE_CODE_REMOTE_SESSION_ID` environment variable. Use this to put a traceable link in PR bodies, commit messages, Slack posts, or generated reports so a reviewer can open the run that produced them.

115

116Ask Claude to construct the link from the environment variable. The following command prints the URL:

117

118```bash theme={null}

119echo "https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}"

120```

121

112### Run tests, start services, and add packages122### Run tests, start services, and add packages

113 123

114Claude runs tests as part of working on a task. Ask for it in your prompt, like "fix the failing tests in `tests/`" or "run pytest after each change." Test runners like pytest, jest, and cargo test work out of the box since they're pre-installed.124Claude runs tests as part of working on a task. Ask for it in your prompt, like "fix the failing tests in `tests/`" or "run pytest after each change." Test runners like pytest, jest, and cargo test work out of the box since they're pre-installed.

115 125

116PostgreSQL and Redis are pre-installed but not running by default. Start each one in a [setup script](#setup-scripts) or ask Claude to start it during the session:126PostgreSQL and Redis are pre-installed but not running by default. Ask Claude to start each one during the session:

117 127

118```bash theme={null}128```bash theme={null}

119service postgresql start129service postgresql start

123service redis-server start133service redis-server start

124```134```

125 135

126Docker is available for running containerized services. Network access to pull images follows your environment's [access level](#access-levels).136Docker is available for running containerized services. Ask Claude to run `docker compose up` to start your project's services. Network access to pull images follows your environment's [access level](#access-levels), and the [Trusted defaults](#default-allowed-domains) include Docker Hub and other common registries.

127 137

128To add packages that aren't pre-installed, use a [setup script](#setup-scripts) so they're available at session start. You can also ask Claude to install packages during the session, but those installs don't persist across sessions.138If your images are large or slow to pull, add `docker compose pull` or `docker compose build` to your [setup script](#setup-scripts). The pulled images are saved in the [cached environment](#environment-caching), so each new session has them on disk. The cache stores files only, not running processes, so Claude still starts the containers each session.

139

140To add packages that aren't pre-installed, use a [setup script](#setup-scripts). The script's output is [cached](#environment-caching), so packages you install there are available at the start of every session without reinstalling each time. You can also ask Claude to install packages mid-session, but those installs don't carry over to other sessions.

129 141

130### Resource limits142### Resource limits

131 143

171apt update && apt install -y gh183apt update && apt install -y gh

172```184```

173 185

174Setup scripts run only when creating a new session. They are skipped when resuming an existing session.

~~175~~

176If the script exits non-zero, the session fails to start. Append `|| true` to non-critical commands to avoid blocking the session on an intermittent install failure.186If the script exits non-zero, the session fails to start. Append `|| true` to non-critical commands to avoid blocking the session on an intermittent install failure.

177 187

178<Note>188<Note>

179 Setup scripts that install packages need network access to reach registries. The default **Trusted** network access allows connections to [common package registries](#default-allowed-domains) including npm, PyPI, RubyGems, and crates.io. Scripts will fail to install packages if your environment uses **None** network access.189 Setup scripts that install packages need network access to reach registries. The default **Trusted** network access allows connections to [common package registries](#default-allowed-domains) including npm, PyPI, RubyGems, and crates.io. Scripts will fail to install packages if your environment uses **None** network access.

180</Note>190</Note>

181 191

192### Environment caching

193

194The setup script runs the first time you start a session in an environment. After it completes, Anthropic snapshots the filesystem and reuses that snapshot as the starting point for later sessions. New sessions start with your dependencies, tools, and Docker images already on disk, and the setup script step is skipped. This keeps startup fast even when the script installs large toolchains or pulls container images.

195

196The cache captures files, not running processes. Anything the setup script writes to disk carries over. Services or containers it starts do not, so start those per session by asking Claude or with a [SessionStart hook](#setup-scripts-vs-sessionstart-hooks).

197

198The setup script runs again to rebuild the cache when you change the environment's setup script or allowed network hosts, and when the cache reaches its expiry after roughly seven days. Resuming an existing session never re-runs the setup script.

199

200You don't need to enable caching or manage snapshots yourself.

201

182### Setup scripts vs. SessionStart hooks202### Setup scripts vs. SessionStart hooks

183 203

184Use a setup script to install things the cloud needs but your laptop already has, like a language runtime or CLI tool. Use a [SessionStart hook](/en/hooks#sessionstart) for project setup that should run everywhere, cloud and local, like `npm install`.204Use a setup script to install things the cloud needs but your laptop already has, like a language runtime or CLI tool. Use a [SessionStart hook](/en/hooks#sessionstart) for project setup that should run everywhere, cloud and local, like `npm install`.

186Both run at the start of a session, but they belong to different places:206Both run at the start of a session, but they belong to different places:

187 207

188| | Setup scripts | SessionStart hooks |208| | Setup scripts | SessionStart hooks |

189| ------------- | ------------------------------------------------- | -------------------------------------------------------------- |209| ------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |

194 214

195SessionStart hooks can also be defined in your user-level `~/.claude/settings.json` locally, but user-level settings don't carry over to cloud sessions. In the cloud, only hooks committed to the repo run.215SessionStart hooks can also be defined in your user-level `~/.claude/settings.json` locally, but user-level settings don't carry over to cloud sessions. In the cloud, only hooks committed to the repo run.

235* **No cloud-only scoping**: hooks run in both local and cloud sessions. To skip local execution, check the `CLAUDE_CODE_REMOTE` environment variable as shown above.255* **No cloud-only scoping**: hooks run in both local and cloud sessions. To skip local execution, check the `CLAUDE_CODE_REMOTE` environment variable as shown above.

236* **Requires network access**: install commands need to reach package registries. If your environment uses **None** network access, these hooks fail. The [default allowlist](#default-allowed-domains) under **Trusted** covers npm, PyPI, RubyGems, and crates.io.256* **Requires network access**: install commands need to reach package registries. If your environment uses **None** network access, these hooks fail. The [default allowlist](#default-allowed-domains) under **Trusted** covers npm, PyPI, RubyGems, and crates.io.

237* **Proxy compatibility**: all outbound traffic passes through a [security proxy](#security-proxy). Some package managers don't work correctly with this proxy. Bun is a known example.257* **Proxy compatibility**: all outbound traffic passes through a [security proxy](#security-proxy). Some package managers don't work correctly with this proxy. Bun is a known example.

238* **Adds startup latency**: hooks run each time a session starts or resumes. Keep install scripts fast by checking whether dependencies are already present before reinstalling.258* **Adds startup latency**: hooks run each time a session starts or resumes, unlike setup scripts which benefit from [environment caching](#environment-caching). Keep install scripts fast by checking whether dependencies are already present before reinstalling.

239 259

240To persist environment variables for subsequent Bash commands, write to the file at `$CLAUDE_ENV_FILE`. See [SessionStart hooks](/en/hooks#sessionstart) for details.260To persist environment variables for subsequent Bash commands, write to the file at `$CLAUDE_ENV_FILE`. See [SessionStart hooks](/en/hooks#sessionstart) for details.

241 261

242Custom environment images and snapshots are not yet supported.262Replacing the base image with your own Docker image is not yet supported. Use a setup script to install what you need on top of the [provided image](#installed-tools), or run your image as a container alongside Claude with `docker compose`.

243 263

244## Network access264## Network access

245 265

734* **Credential protection**: sensitive credentials such as git credentials or signing keys are never inside the sandbox with Claude Code. Authentication is handled through a secure proxy using scoped credentials.754* **Credential protection**: sensitive credentials such as git credentials or signing keys are never inside the sandbox with Claude Code. Authentication is handled through a secure proxy using scoped credentials.

735* **Secure analysis**: code is analyzed and modified within isolated VMs before creating PRs755* **Secure analysis**: code is analyzed and modified within isolated VMs before creating PRs

736 756

757## Troubleshooting

758

759For runtime API errors that appear in the conversation such as `API Error: 500`, `529 Overloaded`, `429`, or `Prompt is too long`, see the [Error reference](/en/errors). Those errors and their fixes are shared with the CLI and Desktop app. The sections below cover issues specific to cloud sessions.

760

761### Session creation failed

762

763If a new session fails to start with `Session creation failed` or stalls at provisioning, Claude Code could not allocate a cloud environment.

764

765* Check [status.claude.com](https://status.claude.com) for cloud session incidents

766* Retry after a minute, as capacity is provisioned on demand

767* Confirm your repository is reachable. Private repositories require either the GitHub App installed with access to that repository, or a `gh` token synced via `/web-setup`. See [GitHub authentication options](#github-authentication-options).

768

769### Remote Control session expired or access denied

770

771`--teleport` connects through the same Remote Control session infrastructure that cloud sessions use, so authentication and session-expiry errors surface with Remote Control wording. You may see `Remote Control session has expired` or `Access denied`. The connection token is short-lived and scoped to your account.

772

773* Run `/login` locally to refresh your credentials, then reconnect

774* Confirm you are signed in to the same account that owns the session

775* If you see `Remote Control may not be available for this organization`, your admin has not enabled remote sessions for your plan

776

777### Environment expired

778

779Cloud sessions stop after a period of inactivity and the underlying environment is reclaimed. From a local terminal, this surfaces as `Could not resume session ... its environment has expired. Creating a fresh session instead.` On the web, the session is marked expired in the session list.

780

781Reopen the session from [claude.ai/code](https://claude.ai/code) to provision a fresh environment with your conversation history restored.

782

737## Limitations783## Limitations

738 784

739Before relying on cloud sessions for a workflow, account for these constraints:785Before relying on cloud sessions for a workflow, account for these constraints:

744 790

745## Related resources791## Related resources

746 792

793* [Ultraplan](/en/ultraplan): draft a plan in a cloud session and review it in your browser

794* [Ultrareview](/en/ultrareview): run a deep multi-agent code review in a cloud sandbox

747* [Routines](/en/routines): automate work on a schedule, via API call, or in response to GitHub events795* [Routines](/en/routines): automate work on a schedule, via API call, or in response to GitHub events

748* [Hooks configuration](/en/hooks): run scripts at session lifecycle events796* [Hooks configuration](/en/hooks): run scripts at session lifecycle events

749* [Settings reference](/en/settings): all configuration options797* [Settings reference](/en/settings): all configuration options

claude-directory.md +23 −18

Details

9 9

10Claude Code reads instructions, settings, skills, subagents, and memory from your project directory and from `~/.claude` in your home directory. Commit project files to git to share them with your team; files in `~/.claude` are personal configuration that applies across all your projects.10Claude Code reads instructions, settings, skills, subagents, and memory from your project directory and from `~/.claude` in your home directory. Commit project files to git to share them with your team; files in `~/.claude` are personal configuration that applies across all your projects.

11 11

~~12If you set [`CLAUDE_CONFIG_DIR`](/en/env-vars), every `~/.claude` path on this page lives under that directory instead.~~12On Windows, `~/.claude` resolves to `%USERPROFILE%\.claude`. If you set [`CLAUDE_CONFIG_DIR`](/en/env-vars), every `~/.claude` path on this page lives under that directory instead.

13 13

14Most users only edit `CLAUDE.md` and `settings.json`. The rest of the directory is optional: add skills, rules, or subagents as you need them.14Most users only edit `CLAUDE.md` and `settings.json`. The rest of the directory is optional: add skills, rules, or subagents as you need them.

15 15

16This page is an interactive explorer: click files in the tree to see what each one does, when it loads, and an example. For a quick reference, see the [file reference table](#file-reference) below.16## Explore the directory

18Click files in the tree to see what each one does, when it loads, and an example.

17 19

18<ClaudeExplorer />20<ClaudeExplorer />

19 21

25| ----------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |27| ----------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

26| `managed-settings.json` | System-level, varies by OS | Enterprise-enforced settings that you can't override. See [server-managed settings](/en/server-managed-settings). |28| `managed-settings.json` | System-level, varies by OS | Enterprise-enforced settings that you can't override. See [server-managed settings](/en/server-managed-settings). |

28| Installed plugins | `~/.claude/plugins/` | Cloned marketplaces, installed plugin versions, and per-plugin data, managed by `claude plugin` commands. Orphaned versions are deleted 7 days after a plugin update or uninstall. See [plugin caching](/en/plugins-reference#plugin-caching-and-file-resolution). |30| Installed plugins | `~/.claude/plugins` | Cloned marketplaces, installed plugin versions, and per-plugin data, managed by `claude plugin` commands. Orphaned versions are deleted 7 days after a plugin update or uninstall. See [plugin caching](/en/plugins-reference#plugin-caching-and-file-resolution). |

29 31

30`~/.claude` also holds data Claude Code writes as you work: transcripts, prompt history, file snapshots, caches, and logs. See [application data](#application-data) below.32`~/.claude` also holds data Claude Code writes as you work: transcripts, prompt history, file snapshots, caches, and logs. See [application data](#application-data) below.

31 33

34## Choose the right file

36Different kinds of customization live in different files. Use this table to find where a change belongs.

39| :------------------------------------------------- | :--------------------------------------- | :---------------- | :------------------------------------------------- |

46| Define a specialized subagent with its own tools | `agents/*.md` | project or global | [Subagents](/en/sub-agents) |

48| Change how Claude formats responses | `output-styles/*.md` | project or global | [Output styles](/en/output-styles) |

32## File reference50## File reference

33 51

34This table lists every file the explorer covers. Project-scope files live in your repo under `.claude/` (or at the root for `CLAUDE.md`, `.mcp.json`, and `.worktreeinclude`). Global-scope files live in `~/.claude/` and apply across all projects.52This table lists every file the explorer covers. Project-scope files live in your repo under `.claude/` (or at the root for `CLAUDE.md`, `.mcp.json`, and `.worktreeinclude`). Global-scope files live in `~/.claude/` and apply across all projects.

64 82

~~65## Check what loaded~~83## Troubleshoot configuration

~~67The explorer shows what files can exist. To see what actually loaded in your current session, use these commands:~~

~~69| Command | Shows |~~

~~70| -------------- | ------------------------------------------------------------------------------------- |~~

~~71| `/context` | Token usage by category: system prompt, memory files, skills, MCP tools, and messages |~~

~~72| `/memory` | Which CLAUDE.md and rules files loaded, plus auto-memory entries |~~

~~73| `/agents` | Configured subagents and their settings |~~

~~74| `/hooks` | Active hook configurations |~~

~~75| `/mcp` | Connected MCP servers and their status |~~

~~76| `/skills` | Available skills from project, user, and plugin sources |~~

~~77| `/permissions` | Current allow and deny rules |~~

~~78| `/doctor` | Installation and configuration diagnostics |~~

79 84

~~80Run `/context` first for the overview, then the specific command for the area you want to investigate.~~85If a setting, hook, or file isn't taking effect, see [Debug your configuration](/en/debug-your-config) for the inspection commands and a symptom-first lookup table.

81 86

82## Application data87## Application data

83 88

cli-reference.md +4 −2

Details

30| `claude remote-control` | Start a [Remote Control](/en/remote-control) server to control Claude Code from Claude.ai or the Claude app. Runs in server mode (no local interactive session). See [Server mode flags](/en/remote-control#start-a-remote-control-session) | `claude remote-control --name "My Project"` |30| `claude remote-control` | Start a [Remote Control](/en/remote-control) server to control Claude Code from Claude.ai or the Claude app. Runs in server mode (no local interactive session). See [Server mode flags](/en/remote-control#start-a-remote-control-session) | `claude remote-control --name "My Project"` |

31| `claude setup-token` | Generate a long-lived OAuth token for CI and scripts. Prints the token to the terminal without saving it. Requires a Claude subscription. See [Generate a long-lived token](/en/authentication#generate-a-long-lived-token) | `claude setup-token` |31| `claude setup-token` | Generate a long-lived OAuth token for CI and scripts. Prints the token to the terminal without saving it. Requires a Claude subscription. See [Generate a long-lived token](/en/authentication#generate-a-long-lived-token) | `claude setup-token` |

32 32

33If you mistype a subcommand, Claude Code suggests the closest match and exits without starting a session. For example, `claude udpate` prints `Did you mean claude update?`.

33## CLI flags35## CLI flags

34 36

35Customize Claude Code's behavior with these command-line flags. `claude --help` does not list every flag, so a flag's absence from `--help` does not mean it is unavailable.37Customize Claude Code's behavior with these command-line flags. `claude --help` does not list every flag, so a flag's absence from `--help` does not mean it is unavailable.

54| `--debug-file <path>` | Write debug logs to a specific file path. Implicitly enables debug mode. Takes precedence over `CLAUDE_CODE_DEBUG_LOGS_DIR` | `claude --debug-file /tmp/claude-debug.log` |56| `--debug-file <path>` | Write debug logs to a specific file path. Implicitly enables debug mode. Takes precedence over `CLAUDE_CODE_DEBUG_LOGS_DIR` | `claude --debug-file /tmp/claude-debug.log` |

57| `--effort` | Set the [effort level](/en/model-config#adjust-effort-level) for the current session. Options: `low`, `medium`, `high`, `max` (Opus 4.6 only). Session-scoped and does not persist to settings | `claude --effort high` |59| `--effort` | Set the [effort level](/en/model-config#adjust-effort-level) for the current session. Options: `low`, `medium`, `high`, `xhigh`, `max`; available levels depend on the model. Session-scoped and does not persist to settings | `claude --effort high` |

60| `--enable-auto-mode` | {/* max-version: 2.1.110 */}Removed in v2.1.111. Auto mode is now in the `Shift+Tab` cycle by default; use `--permission-mode auto` to start in it | `claude --permission-mode auto` |

58| `--exclude-dynamic-system-prompt-sections` | Move per-machine sections from the system prompt (working directory, environment info, memory paths, git status) into the first user message. Improves prompt-cache reuse across different users and machines running the same task. Only applies with the default system prompt; ignored when `--system-prompt` or `--system-prompt-file` is set. Use with `-p` for scripted, multi-user workloads | `claude -p --exclude-dynamic-system-prompt-sections "query"` |61| `--exclude-dynamic-system-prompt-sections` | Move per-machine sections from the system prompt (working directory, environment info, memory paths, git status) into the first user message. Improves prompt-cache reuse across different users and machines running the same task. Only applies with the default system prompt; ignored when `--system-prompt` or `--system-prompt-file` is set. Use with `-p` for scripted, multi-user workloads | `claude -p --exclude-dynamic-system-prompt-sections "query"` |

60| `--fork-session` | When resuming, create a new session ID instead of reusing the original (use with `--resume` or `--continue`) | `claude --resume abc123 --fork-session` |63| `--fork-session` | When resuming, create a new session ID instead of reusing the original (use with `--resume` or `--continue`) | `claude --resume abc123 --fork-session` |

76| `--no-session-persistence` | Disable session persistence so sessions are not saved to disk and cannot be resumed (print mode only) | `claude -p --no-session-persistence "query"` |79| `--no-session-persistence` | Disable session persistence so sessions are not saved to disk and cannot be resumed (print mode only) | `claude -p --no-session-persistence "query"` |

78| `--enable-auto-mode` | Unlock [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) in the `Shift+Tab` cycle. Requires a Team, Enterprise, or API plan and Claude Sonnet 4.6 or Opus 4.6 | `claude --enable-auto-mode` |

79| `--permission-mode` | Begin in a specified [permission mode](/en/permission-modes). Accepts `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, or `bypassPermissions`. Overrides `defaultMode` from settings files | `claude --permission-mode plan` |81| `--permission-mode` | Begin in a specified [permission mode](/en/permission-modes). Accepts `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, or `bypassPermissions`. Overrides `defaultMode` from settings files | `claude --permission-mode plan` |

81| `--plugin-dir` | Load plugins from a directory for this session only. Each flag takes one path. Repeat the flag for multiple directories: `--plugin-dir A --plugin-dir B` | `claude --plugin-dir ./my-plugins` |83| `--plugin-dir` | Load plugins from a directory for this session only. Each flag takes one path. Repeat the flag for multiple directories: `--plugin-dir A --plugin-dir B` | `claude --plugin-dir ./my-plugins` |

code-review.md +61 −24

Details

29 29

30Once an admin [enables Code Review](#set-up-code-review) for your organization, reviews trigger when a PR opens, on every push, or when manually requested, depending on the repository's configured behavior. Commenting `@claude review` [starts reviews on a PR](#manually-trigger-reviews) in any mode.30Once an admin [enables Code Review](#set-up-code-review) for your organization, reviews trigger when a PR opens, on every push, or when manually requested, depending on the repository's configured behavior. Commenting `@claude review` [starts reviews on a PR](#manually-trigger-reviews) in any mode.

31 31

32When a review runs, multiple agents analyze the diff and surrounding code in parallel on Anthropic infrastructure. Each agent looks for a different class of issue, then a verification step checks candidates against actual code behavior to filter out false positives. The results are deduplicated, ranked by severity, and posted as inline comments on the specific lines where issues were found. If no issues are found, Claude posts a short confirmation comment on the PR.32When a review runs, multiple agents analyze the diff and surrounding code in parallel on Anthropic infrastructure. Each agent looks for a different class of issue, then a verification step checks candidates against actual code behavior to filter out false positives. The results are deduplicated, ranked by severity, and posted as inline comments on the specific lines where issues were found, with a summary in the review body. If no issues are found, Claude posts a short confirmation comment on the PR.

33 33

34Reviews scale in cost with PR size and complexity, completing in 20 minutes on average. Admins can monitor review activity and spend via the [analytics dashboard](#view-usage).34Reviews scale in cost with PR size and complexity, completing in 20 minutes on average. Admins can monitor review activity and spend via the [analytics dashboard](#view-usage).

35 35

141 141

142## Customize reviews142## Customize reviews

143 143

144Code Review reads two files from your repository to guide what it flags. Both are additive on top of the default correctness checks:144Code Review reads two files from your repository to guide what it flags. They differ in how strongly they influence the review:

145 145

146* **`CLAUDE.md`**: shared project instructions that Claude Code uses for all tasks, not just reviews. Use it when guidance also applies to interactive Claude Code sessions.146* **`CLAUDE.md`**: shared project instructions that Claude Code uses for all tasks, not just reviews. Code Review reads it as project context and flags newly introduced violations as nits.

147* **`REVIEW.md`**: review-only guidance, read exclusively during code reviews. Use it for rules that are strictly about what to flag or skip during review and would clutter your general `CLAUDE.md`.147* **`REVIEW.md`**: review-only instructions, injected directly into every agent in the review pipeline as highest priority. Use it to change what gets flagged, at what severity, and how findings are reported.

148 148

149### CLAUDE.md149### CLAUDE.md

150 150

151Code Review reads your repository's `CLAUDE.md` files and treats newly-introduced violations as nit-level findings. This works bidirectionally: if your PR changes code in a way that makes a `CLAUDE.md` statement outdated, Claude flags that the docs need updating too.151Code Review reads your repository's `CLAUDE.md` files and treats newly introduced violations as [nit-level](#severity-levels) findings. This works bidirectionally: if your PR changes code in a way that makes a `CLAUDE.md` statement outdated, Claude flags that the docs need updating too.

152 152

153Claude reads `CLAUDE.md` files at every level of your directory hierarchy, so rules in a subdirectory's `CLAUDE.md` apply only to files under that path. See the [memory documentation](/en/memory) for more on how `CLAUDE.md` works.153Claude reads `CLAUDE.md` files at every level of your directory hierarchy, so rules in a subdirectory's `CLAUDE.md` apply only to files under that path. See the [memory documentation](/en/memory) for more on how `CLAUDE.md` works.

154 154

156 156

157### REVIEW\.md157### REVIEW\.md

158 158

159Add a `REVIEW.md` file to your repository root for review-specific rules. Use it to encode:159`REVIEW.md` is a file at your repository root that overrides how Code Review behaves on your repo. Its contents are injected into the system prompt of every agent in the review pipeline as the highest-priority instruction block, taking precedence over the default review guidance.

160 160

161* Company or team style guidelines: "prefer early returns over nested conditionals"161Because it's pasted verbatim, `REVIEW.md` is plain instructions: [`@` import syntax](/en/memory#import-additional-files) is not expanded, and referenced files are not read into the prompt. Put the rules you want enforced directly in the file.

162* Language- or framework-specific conventions not covered by linters

163* Things Claude should always flag: "any new API route must have an integration test"

164* Things Claude should skip: "don't comment on formatting in generated code under `/gen/`"

165 162

166Example `REVIEW.md`:163#### What you can tune

164

165`REVIEW.md` is freeform markdown, so anything you can express as a review instruction is in scope. The patterns below have the most impact in practice.

166

167**Severity**: redefine what 🔴 Important means for your repo. The default calibration targets production code; a docs repo, a config repo, or a prototype might want a much narrower definition. State explicitly which classes of finding are Important and which are Nit at most. You can also escalate in the other direction, for example treating any `CLAUDE.md` violation as Important rather than the default nit.

168

169**Nit volume**: cap how many 🟡 Nit comments a single review posts. Prose and config files can be polished forever. A cap like "report at most five nits, mention the rest as a count in the summary" keeps reviews actionable.

170

171**Skip rules**: list paths, branch patterns, and finding categories where Claude should post no findings. Common candidates are generated code, lockfiles, vendored dependencies, and machine-authored branches, along with anything your CI already enforces like linting or spellcheck. For paths that warrant some review but not full scrutiny, set a higher bar instead of skipping entirely: "in `scripts/`, only report if near-certain and severe."

172

173**Repo-specific checks**: add rules you want flagged on every PR, like "new API routes must have an integration test." Because `REVIEW.md` is injected as highest priority, these land more reliably than the same rules in a long `CLAUDE.md`.

174

175**Verification bar**: require evidence before a class of finding is posted. For example, "behavior claims need a `file:line` citation in the source, not an inference from naming" cuts false positives that would otherwise cost the author a round trip.

176

177**Re-review convergence**: tell Claude how to behave when a PR has already been reviewed. A rule like "after the first review, suppress new nits and post Important findings only" stops a one-line fix from reaching round seven on style alone.

178

179**Summary shape**: ask for the review body to open with a one-line tally such as `2 factual, 4 style`, and to lead with "no factual issues" when that's the case. The author wants to know the shape of the work before the details.

180

181#### Example

182

183This `REVIEW.md` recalibrates severity for a backend service, caps nits, skips generated files, and adds repo-specific checks.

167 184

168```markdown theme={null}185```markdown theme={null}

169# Code Review Guidelines186# Review instructions

170 187

171## Always check188## What Important means here

172- New API endpoints have corresponding integration tests189

173- Database migrations are backward-compatible190Reserve Important for findings that would break behavior, leak data,

174- Error messages don't leak internal details to users191or block a rollback: incorrect logic, unscoped database queries, PII

192in logs or error messages, and migrations that aren't backward

193compatible. Style, naming, and refactoring suggestions are Nit at

194most.

195

196## Cap the nits

197

198Report at most five Nits per review. If you found more, say "plus N

199similar items" in the summary instead of posting them inline. If

200everything you found is a Nit, lead the summary with "No blocking

201issues."

202

203## Do not report

175 204

176## Style205- Anything CI already enforces: lint, formatting, type errors

177- Prefer `match` statements over chained `isinstance` checks206- Generated files under `src/gen/` and any `*.lock` file

178- Use structured logging, not f-string interpolation in log calls207- Test-only code that intentionally violates production rules

179 208

180## Skip209## Always check

181- Generated files under `src/gen/`210

182- Formatting-only changes in `*.lock` files211- New API routes have an integration test

212- Log lines don't include email addresses, user IDs, or request bodies

213- Database queries are scoped to the caller's tenant

183```214```

184 215

185Claude auto-discovers `REVIEW.md` at the repository root. No configuration needed.216#### Keep it focused

217

218Length has a cost: a long `REVIEW.md` dilutes the rules that matter most. Keep it to instructions that change review behavior, and leave general project context in `CLAUDE.md`.

186 219

187## View usage220## View usage

188 221

195| Feedback | Count of review comments that were auto-resolved because a developer addressed the issue |228| Feedback | Count of review comments that were auto-resolved because a developer addressed the issue |

196| Repository breakdown | Per-repo counts of PRs reviewed and comments resolved |229| Repository breakdown | Per-repo counts of PRs reviewed and comments resolved |

197 230

198The repositories table in admin settings also shows average cost per review for each repo.231The repositories table in admin settings also shows average cost per review for each repo. Dashboard cost figures are estimates for monitoring activity; for invoice-accurate spend, refer to your Anthropic bill.

199 232

200## Pricing233## Pricing

201 234

225 258

226The **Re-run** button in GitHub's Checks tab does not retrigger Code Review. Use the comment command or a new push instead.259The **Re-run** button in GitHub's Checks tab does not retrigger Code Review. Use the comment command or a new push instead.

227 260

261### Review didn't run and the PR shows a spend-cap message

262

263When your organization's monthly spend cap is reached, Code Review posts a single comment on the PR explaining that the review was skipped. Reviews resume automatically at the start of the next billing period, or immediately when an admin raises the cap at [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage).

264

228### Find issues that aren't showing as inline comments265### Find issues that aren't showing as inline comments

229 266

230If the check run title says issues were found but you don't see inline review comments on the diff, look in these other locations where findings are surfaced:267If the check run title says issues were found but you don't see inline review comments on the diff, look in these other locations where findings are surfaced:

commands.md +18 −12

Details

17In the table below, `<arg>` indicates a required argument and `[arg]` indicates an optional one.17In the table below, `<arg>` indicates a required argument and `[arg]` indicates an optional one.

18 18

20| :--------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |20| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

21| `/add-dir <path>` | Add a working directory for file access during the current session. Most `.claude/` configuration is [not discovered](/en/permissions#additional-directories-grant-file-access-not-configuration) from the added directory |21| `/add-dir <path>` | Add a working directory for file access during the current session. Most `.claude/` configuration is [not discovered](/en/permissions#additional-directories-grant-file-access-not-configuration) from the added directory |

23| `/autofix-pr [prompt]` | Spawn a [Claude Code on the web](/en/claude-code-on-the-web#auto-fix-pull-requests) session that watches the current branch's PR and pushes fixes when CI fails or reviewers leave comments. Detects the open PR from your checked-out branch with `gh pr view`; to watch a different PR, check out its branch first. By default the remote session is told to fix every CI failure and review comment; pass a prompt to give it different instructions, for example `/autofix-pr only fix lint and type errors`. Requires the `gh` CLI and access to [Claude Code on the web](/en/claude-code-on-the-web#who-can-use-claude-code-on-the-web) |23| `/autofix-pr [prompt]` | Spawn a [Claude Code on the web](/en/claude-code-on-the-web#auto-fix-pull-requests) session that watches the current branch's PR and pushes fixes when CI fails or reviewers leave comments. Detects the open PR from your checked-out branch with `gh pr view`; to watch a different PR, check out its branch first. By default the remote session is told to fix every CI failure and review comment; pass a prompt to give it different instructions, for example `/autofix-pr only fix lint and type errors`. Requires the `gh` CLI and access to [Claude Code on the web](/en/claude-code-on-the-web#who-can-use-claude-code-on-the-web) |

24| `/batch <instruction>` | **[Skill](/en/skills#bundled-skills).** Orchestrate large-scale changes across a codebase in parallel. Researches the codebase, decomposes the work into 5 to 30 independent units, and presents a plan. Once approved, spawns one background agent per unit in an isolated [git worktree](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees). Each agent implements its unit, runs tests, and opens a pull request. Requires a git repository. Example: `/batch migrate src/ from Solid to React` |24| `/batch <instruction>` | **[Skill](/en/skills#bundled-skills).** Orchestrate large-scale changes across a codebase in parallel. Researches the codebase, decomposes the work into 5 to 30 independent units, and presents a plan. Once approved, spawns one background agent per unit in an isolated [git worktree](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees). Each agent implements its unit, runs tests, and opens a pull request. Requires a git repository. Example: `/batch migrate src/ from Solid to React` |

25| `/branch [name]` | Create a branch of the current conversation at this point. Switches you into the branch and preserves the original, which you can return to with `/resume`. Alias: `/fork` |25| `/branch [name]` | Create a branch of the current conversation at this point. Switches you into the branch and preserves the original, which you can return to with `/resume`. Alias: `/fork` |

26| `/btw <question>` | Ask a quick [side question](/en/interactive-mode#side-questions-with-btw) without adding to the conversation |26| `/btw <question>` | Ask a quick [side question](/en/interactive-mode#side-questions-with-%2Fbtw) without adding to the conversation |

28| `/claude-api` | **[Skill](/en/skills#bundled-skills).** Load Claude API reference material for your project's language (Python, TypeScript, Java, Go, Ruby, C#, PHP, or cURL) and Managed Agents reference. Covers tool use, streaming, batches, structured outputs, and common pitfalls. Also activates automatically when your code imports `anthropic` or `@anthropic-ai/sdk` |28| `/claude-api` | **[Skill](/en/skills#bundled-skills).** Load Claude API reference material for your project's language (Python, TypeScript, Java, Go, Ruby, C#, PHP, or cURL) and Managed Agents reference. Covers tool use, streaming, batches, structured outputs, and common pitfalls. Also activates automatically when your code imports `anthropic` or `@anthropic-ai/sdk` |

29| `/clear` | Clear conversation history and free up context. Aliases: `/reset`, `/new` |29| `/clear` | Start a new conversation with empty context. The previous conversation stays available in `/resume`. To free up context while continuing the same conversation, use `/compact` instead. Aliases: `/reset`, `/new` |

30| `/color [color\|default]` | Set the prompt bar color for the current session. Available colors: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. Use `default` to reset |30| `/color [color\|default]` | Set the prompt bar color for the current session. Available colors: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. Use `default` to reset |

31| `/compact [instructions]` | Compact conversation with optional focus instructions |31| `/compact [instructions]` | Free up context by summarizing the conversation so far. Optionally pass focus instructions for the summary. See [how compaction handles rules, skills, and memory files](/en/context-window#what-survives-compaction) |

32| `/config` | Open the [Settings](/en/settings) interface to adjust theme, model, [output style](/en/output-styles), and other preferences. Alias: `/settings` |32| `/config` | Open the [Settings](/en/settings) interface to adjust theme, model, [output style](/en/output-styles), and other preferences. Alias: `/settings` |

33| `/context` | Visualize current context usage as a colored grid. Shows optimization suggestions for context-heavy tools, memory bloat, and capacity warnings |33| `/context` | Visualize current context usage as a colored grid. Shows optimization suggestions for context-heavy tools, memory bloat, and capacity warnings |

34| `/copy [N]` | Copy the last assistant response to clipboard. Pass a number `N` to copy the Nth-latest response: `/copy 2` copies the second-to-last. When code blocks are present, shows an interactive picker to select individual blocks or the full response. Press `w` in the picker to write the selection to a file instead of the clipboard, which is useful over SSH |34| `/copy [N]` | Copy the last assistant response to clipboard. Pass a number `N` to copy the Nth-latest response: `/copy 2` copies the second-to-last. When code blocks are present, shows an interactive picker to select individual blocks or the full response. Press `w` in the picker to write the selection to a file instead of the clipboard, which is useful over SSH |

38| `/diff` | Open an interactive diff viewer showing uncommitted changes and per-turn diffs. Use left/right arrows to switch between the current git diff and individual Claude turns, and up/down to browse files |38| `/diff` | Open an interactive diff viewer showing uncommitted changes and per-turn diffs. Use left/right arrows to switch between the current git diff and individual Claude turns, and up/down to browse files |

39| `/doctor` | Diagnose and verify your Claude Code installation and settings. Results show with status icons. Press `f` to have Claude fix any reported issues |39| `/doctor` | Diagnose and verify your Claude Code installation and settings. Results show with status icons. Press `f` to have Claude fix any reported issues |

40| `/effort [low\|medium\|high\|max\|auto]` | Set the model [effort level](/en/model-config#adjust-effort-level). `low`, `medium`, and `high` persist across sessions. `max` applies to the current session only and requires Opus 4.6. `auto` resets to the model default. Without an argument, shows the current level. Takes effect immediately without waiting for the current response to finish |40| `/effort [level\|auto]` | Set the model [effort level](/en/model-config#adjust-effort-level). Accepts `low`, `medium`, `high`, `xhigh`, or `max`; available levels depend on the model and `max` is session-only. `auto` resets to the model default. Without an argument, opens an interactive slider; use left and right arrows to pick a level and `Enter` to apply. Takes effect immediately without waiting for the current response to finish |

42| `/export [filename]` | Export the current conversation as plain text. With a filename, writes directly to that file. Without, opens a dialog to copy to clipboard or save to a file |42| `/export [filename]` | Export the current conversation as plain text. With a filename, writes directly to that file. Without, opens a dialog to copy to clipboard or save to a file |

44| `/fast [on\|off]` | Toggle [fast mode](/en/fast-mode) on or off |44| `/fast [on\|off]` | Toggle [fast mode](/en/fast-mode) on or off |

46| `/fewer-permission-prompts` | **[Skill](/en/skills#bundled-skills).** Scan your transcripts for common read-only Bash and MCP tool calls, then add a prioritized allowlist to project `.claude/settings.json` to reduce permission prompts |

47| `/focus` | Toggle the focus view, which shows only your last prompt, a one-line tool-call summary with edit diffstats, and the final response. The selection persists across sessions. Only available in [fullscreen rendering](/en/fullscreen) |

48| `/heapdump` | Write a JavaScript heap snapshot and a memory breakdown to `~/Desktop` for diagnosing high memory usage. See [troubleshooting](/en/troubleshooting#high-cpu-or-memory-usage) |

48| `/ide` | Manage IDE integrations and show status |51| `/ide` | Manage IDE integrations and show status |

57| `/mcp` | Manage MCP server connections and OAuth authentication |60| `/mcp` | Manage MCP server connections and OAuth authentication |

58| `/memory` | Edit `CLAUDE.md` memory files, enable or disable [auto-memory](/en/memory#auto-memory), and view auto-memory entries |61| `/memory` | Edit `CLAUDE.md` memory files, enable or disable [auto-memory](/en/memory#auto-memory), and view auto-memory entries |

60| `/model [model]` | Select or change the AI model. For models that support it, use left/right arrows to [adjust effort level](/en/model-config#adjust-effort-level). The change takes effect immediately without waiting for the current response to finish |63| `/model [model]` | Select or change the AI model. For models that support it, use left/right arrows to [adjust effort level](/en/model-config#adjust-effort-level). With no argument, opens a picker that asks for confirmation when the conversation has prior output, since the next response re-reads the full history without cached context. Once confirmed, the change applies without waiting for the current response to finish |

62| `/permissions` | Manage allow, ask, and deny rules for tool permissions. Opens an interactive dialog where you can view rules by scope, add or remove rules, manage working directories, and review [recent auto mode denials](/en/permissions#review-auto-mode-denials). Alias: `/allowed-tools` |65| `/permissions` | Manage allow, ask, and deny rules for tool permissions. Opens an interactive dialog where you can view rules by scope, add or remove rules, manage working directories, and review [recent auto mode denials](/en/permissions#review-auto-mode-denials). Alias: `/allowed-tools` |

63| `/plan [description]` | Enter plan mode directly from the prompt. Pass an optional description to enter plan mode and immediately start with that task, for example `/plan fix the auth bug` |66| `/plan [description]` | Enter plan mode directly from the prompt. Pass an optional description to enter plan mode and immediately start with that task, for example `/plan fix the auth bug` |

66| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}Removed in v2.1.91. Ask Claude directly to view pull request comments instead. On earlier versions, fetches and displays comments from a GitHub pull request; automatically detects the PR for the current branch, or pass a PR URL or number. Requires the `gh` CLI |69| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}Removed in v2.1.91. Ask Claude directly to view pull request comments instead. On earlier versions, fetches and displays comments from a GitHub pull request; automatically detects the PR for the current branch, or pass a PR URL or number. Requires the `gh` CLI |

71| `/recap` | Generate a one-line summary of the current session on demand. See [Session recap](/en/interactive-mode#session-recap) for the automatic recap that appears after you've been away |

68| `/release-notes` | View the changelog in an interactive version picker. Select a specific version to see its release notes, or choose to show all versions |72| `/release-notes` | View the changelog in an interactive version picker. Select a specific version to see its release notes, or choose to show all versions |

69| `/reload-plugins` | Reload all active [plugins](/en/plugins) to apply pending changes without restarting. Reports counts for each reloaded component and flags any load errors |73| `/reload-plugins` | Reload all active [plugins](/en/plugins) to apply pending changes without restarting. Reports counts for each reloaded component and flags any load errors |

71| `/remote-env` | Configure the default remote environment for [web sessions started with `--remote`](/en/claude-code-on-the-web#configure-your-environment) |75| `/remote-env` | Configure the default remote environment for [web sessions started with `--remote`](/en/claude-code-on-the-web#configure-your-environment) |

72| `/rename [name]` | Rename the current session and show the name on the prompt bar. Without a name, auto-generates one from conversation history |76| `/rename [name]` | Rename the current session and show the name on the prompt bar. Without a name, auto-generates one from conversation history |

74| `/review` | Deprecated. Install the [`code-review` plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/code-review) instead: `claude plugin install code-review@claude-plugins-official` |78| `/review [PR]` | Review a pull request locally in your current session. For a deeper cloud-based review, see [`/ultrareview`](/en/ultrareview) |

75| `/rewind` | Rewind the conversation and/or code to a previous point, or summarize from a selected message. See [checkpointing](/en/checkpointing). Alias: `/checkpoint` |79| `/rewind` | Rewind the conversation and/or code to a previous point, or summarize from a selected message. See [checkpointing](/en/checkpointing). Aliases: `/checkpoint`, `/undo` |

77| `/schedule [description]` | Create, update, list, or run [routines](/en/routines). Claude walks you through the setup conversationally |81| `/schedule [description]` | Create, update, list, or run [routines](/en/routines). Claude walks you through the setup conversationally. Alias: `/routines` |

78| `/security-review` | Analyze pending changes on the current branch for security vulnerabilities. Reviews the git diff and identifies risks like injection, auth issues, and data exposure |82| `/security-review` | Analyze pending changes on the current branch for security vulnerabilities. Reviews the git diff and identifies risks like injection, auth issues, and data exposure |

79| `/setup-bedrock` | Configure [Amazon Bedrock](/en/amazon-bedrock) authentication, region, and model pins through an interactive wizard. Only visible when `CLAUDE_CODE_USE_BEDROCK=1` is set. First-time Bedrock users can also access this wizard from the login screen |83| `/setup-bedrock` | Configure [Amazon Bedrock](/en/amazon-bedrock) authentication, region, and model pins through an interactive wizard. Only visible when `CLAUDE_CODE_USE_BEDROCK=1` is set. First-time Bedrock users can also access this wizard from the login screen |

80| `/setup-vertex` | Configure [Google Vertex AI](/en/google-vertex-ai) authentication, project, region, and model pins through an interactive wizard. Only visible when `CLAUDE_CODE_USE_VERTEX=1` is set. First-time Vertex AI users can also access this wizard from the login screen |84| `/setup-vertex` | Configure [Google Vertex AI](/en/google-vertex-ai) authentication, project, region, and model pins through an interactive wizard. Only visible when `CLAUDE_CODE_USE_VERTEX=1` is set. First-time Vertex AI users can also access this wizard from the login screen |

81| `/simplify [focus]` | **[Skill](/en/skills#bundled-skills).** Review your recently changed files for code reuse, quality, and efficiency issues, then fix them. Spawns three review agents in parallel, aggregates their findings, and applies fixes. Pass text to focus on specific concerns: `/simplify focus on memory efficiency` |85| `/simplify [focus]` | **[Skill](/en/skills#bundled-skills).** Review your recently changed files for code reuse, quality, and efficiency issues, then fix them. Spawns three review agents in parallel, aggregates their findings, and applies fixes. Pass text to focus on specific concerns: `/simplify focus on memory efficiency` |

84| `/status` | Open the Settings interface (Status tab) showing version, model, account, and connectivity. Works while Claude is responding, without waiting for the current response to finish |88| `/status` | Open the Settings interface (Status tab) showing version, model, account, and connectivity. Works while Claude is responding, without waiting for the current response to finish |

85| `/statusline` | Configure Claude Code's [status line](/en/statusline). Describe what you want, or run without arguments to auto-configure from your shell prompt |89| `/statusline` | Configure Claude Code's [status line](/en/statusline). Describe what you want, or run without arguments to auto-configure from your shell prompt |

88| `/team-onboarding` | Generate a team onboarding guide from your Claude Code usage history. Claude analyzes your sessions, commands, and MCP server usage from the past 30 days and produces a markdown guide a teammate can paste as a first message to get set up quickly |92| `/team-onboarding` | Generate a team onboarding guide from your Claude Code usage history. Claude analyzes your sessions, commands, and MCP server usage from the past 30 days and produces a markdown guide a teammate can paste as a first message to get set up quickly |

89| `/teleport` | Pull a [Claude Code on the web](/en/claude-code-on-the-web#from-web-to-terminal) session into this terminal: opens a picker, then fetches the branch and conversation. Also available as `/tp`. Requires a claude.ai subscription |93| `/teleport` | Pull a [Claude Code on the web](/en/claude-code-on-the-web#from-web-to-terminal) session into this terminal: opens a picker, then fetches the branch and conversation. Also available as `/tp`. Requires a claude.ai subscription |

90| `/terminal-setup` | Configure terminal keybindings for Shift+Enter and other shortcuts. Only visible in terminals that need it, like VS Code, Alacritty, or Warp |94| `/terminal-setup` | Configure terminal keybindings for Shift+Enter and other shortcuts. Only visible in terminals that need it, like VS Code, Cursor, Windsurf, Alacritty, or Zed |

91| `/theme` | Change the color theme. Includes light and dark variants, colorblind-accessible (daltonized) themes, and ANSI themes that use your terminal's color palette |95| `/theme` | Change the color theme. Includes an `auto` option that matches your terminal's light or dark background, light and dark variants, colorblind-accessible (daltonized) themes, and ANSI themes that use your terminal's color palette |

96| `/tui [default\|fullscreen]` | Set the terminal UI renderer and relaunch into it with your conversation intact. `fullscreen` enables the [flicker-free alt-screen renderer](/en/fullscreen). With no argument, prints the active renderer |

92| `/ultraplan <prompt>` | Draft a plan in an [ultraplan](/en/ultraplan) session, review it in your browser, then execute remotely or send it back to your terminal |97| `/ultraplan <prompt>` | Draft a plan in an [ultraplan](/en/ultraplan) session, review it in your browser, then execute remotely or send it back to your terminal |

98| `/ultrareview [PR]` | Run a deep, multi-agent code review in a cloud sandbox with [ultrareview](/en/ultrareview). Includes 3 free runs on Pro and Max through May 5, 2026, then requires [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

95| `/vim` | {/* max-version: 2.1.91 */}Removed in v2.1.92. To toggle between Vim and Normal editing modes, use `/config` → Editor mode |101| `/vim` | {/* max-version: 2.1.91 */}Removed in v2.1.92. To toggle between Vim and Normal editing modes, use `/config` → Editor mode |

common-workflows.md +38 −20

Details

403 403

404***404***

405 405

406## Work in notes and non-code folders

407

408Claude Code works in any directory. Run it inside a notes vault, a documentation folder, or any collection of markdown files to search, edit, and reorganize content the same way you would code.

409

410The `.claude/` directory and `CLAUDE.md` sit alongside other tools' config directories without conflict. Claude reads files fresh on each tool call, so it sees edits you make in another application the next time it reads that file.

411

412***

413

406## Work with images414## Work with images

407 415

408Suppose you need to work with images in your codebase, and you want Claude's help analyzing image content.416Suppose you need to work with images in your codebase, and you want Claude's help analyzing image content.

506 514

507## Use extended thinking (thinking mode)515## Use extended thinking (thinking mode)

508 516

509[Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) is enabled by default, giving Claude space to reason through complex problems step-by-step before responding. This reasoning is visible in verbose mode, which you can toggle on with `Ctrl+O`.517[Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) is enabled by default, giving Claude space to reason through complex problems step-by-step before responding. This reasoning is visible in verbose mode, which you can toggle on with `Ctrl+O`. During extended thinking, the spinner shows inline progress hints such as "still thinking" and "almost done thinking" to indicate Claude is actively working.

510 518

511Additionally, Opus 4.6 and Sonnet 4.6 support adaptive reasoning: instead of a fixed thinking token budget, the model dynamically allocates thinking based on your [effort level](/en/model-config#adjust-effort-level) setting. Extended thinking and adaptive reasoning work together to give you control over how deeply Claude reasons before responding.519Additionally, [models that support effort](/en/model-config#adjust-effort-level) use adaptive reasoning: instead of a fixed thinking token budget, the model dynamically decides whether and how much to think based on your effort level setting and the task at hand. Adaptive reasoning lets Claude respond faster to routine prompts and reserve deeper thinking for steps that benefit from it.

512 520

513Extended thinking is particularly valuable for complex architectural decisions, challenging bugs, multi-step implementation planning, and evaluating tradeoffs between different approaches.521Extended thinking is particularly valuable for complex architectural decisions, challenging bugs, multi-step implementation planning, and evaluating tradeoffs between different approaches.

514 522

521Thinking is enabled by default, but you can adjust or disable it.529Thinking is enabled by default, but you can adjust or disable it.

522 530

524| ------------------------ | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |532| ------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

525| **Effort level** | Run `/effort`, adjust in `/model`, or set [`CLAUDE_CODE_EFFORT_LEVEL`](/en/env-vars) | Control thinking depth for Opus 4.6 and Sonnet 4.6. See [Adjust effort level](/en/model-config#adjust-effort-level) |533| **Effort level** | Run `/effort`, adjust in `/model`, or set [`CLAUDE_CODE_EFFORT_LEVEL`](/en/env-vars) | Control thinking depth on [supported models](/en/model-config#adjust-effort-level) |

526| **`ultrathink` keyword** | Include "ultrathink" anywhere in your prompt | Sets effort to high for that turn on Opus 4.6 and Sonnet 4.6. Useful for one-off tasks requiring deep reasoning without permanently changing your effort setting |534| **`ultrathink` keyword** | Include "ultrathink" anywhere in your prompt | Adds an in-context instruction telling the model to reason more on that turn. Does not change the effort level itself; see [Adjust effort level](/en/model-config#adjust-effort-level) for that |

527| **Toggle shortcut** | Press `Option+T` (macOS) or `Alt+T` (Windows/Linux) | Toggle thinking on/off for the current session (all models). May require [terminal configuration](/en/terminal-config) to enable Option key shortcuts |535| **Toggle shortcut** | Press `Option+T` (macOS) or `Alt+T` (Windows/Linux) | Toggle thinking on/off for the current session (all models). May require [terminal configuration](/en/terminal-config) to enable Option key shortcuts |

528| **Global default** | Use `/config` to toggle thinking mode | Sets your default across all projects (all models).<br />Saved as `alwaysThinkingEnabled` in `~/.claude/settings.json` |536| **Global default** | Use `/config` to toggle thinking mode | Sets your default across all projects (all models).<br />Saved as `alwaysThinkingEnabled` in `~/.claude/settings.json` |

529| **Limit token budget** | Set [`MAX_THINKING_TOKENS`](/en/env-vars) environment variable | Limit the thinking budget to a specific number of tokens. On Opus 4.6 and Sonnet 4.6, only `0` applies unless adaptive reasoning is disabled. Example: `export MAX_THINKING_TOKENS=10000` |537| **Limit token budget** | Set [`MAX_THINKING_TOKENS`](/en/env-vars) environment variable | Limit the thinking budget to a specific number of tokens. On models with adaptive reasoning, only `0` applies unless adaptive reasoning is disabled. Example: `export MAX_THINKING_TOKENS=10000` |

530 538

531To view Claude's thinking process, press `Ctrl+O` to toggle verbose mode and see the internal reasoning displayed as gray italic text.539To view Claude's thinking process, press `Ctrl+O` to toggle verbose mode and see the internal reasoning displayed as gray italic text.

532 540

534 542

535Extended thinking controls how much internal reasoning Claude performs before responding. More thinking provides more space to explore solutions, analyze edge cases, and self-correct mistakes.543Extended thinking controls how much internal reasoning Claude performs before responding. More thinking provides more space to explore solutions, analyze edge cases, and self-correct mistakes.

536 544

537**With Opus 4.6 and Sonnet 4.6**, thinking uses adaptive reasoning: the model dynamically allocates thinking tokens based on the [effort level](/en/model-config#adjust-effort-level) you select. This is the recommended way to tune the tradeoff between speed and reasoning depth.545On [models that support effort](/en/model-config#adjust-effort-level), thinking uses adaptive reasoning: the model dynamically allocates thinking tokens based on the effort level you select. This is the recommended way to tune the tradeoff between speed and reasoning depth. If you want Claude to think more or less often than your effort level would otherwise produce, you can also say so directly in your prompt or in `CLAUDE.md`.

538 546

539**With older models**, thinking uses a fixed token budget drawn from your output allocation. The budget varies by model; see [`MAX_THINKING_TOKENS`](/en/env-vars) for per-model ceilings. You can limit the budget with that environment variable, or disable thinking entirely via `/config` or the `Option+T`/`Alt+T` toggle.547With older models, thinking uses a fixed token budget drawn from your output allocation. The budget varies by model; see [`MAX_THINKING_TOKENS`](/en/env-vars) for per-model ceilings. You can limit the budget with that environment variable, or disable thinking entirely via `/config` or the `Option+T`/`Alt+T` toggle.

540 548

541On Opus 4.6 and Sonnet 4.6, [adaptive reasoning](/en/model-config#adjust-effort-level) controls thinking depth, so `MAX_THINKING_TOKENS` only applies when set to `0` to disable thinking, or when `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` reverts these models to the fixed budget. See [environment variables](/en/env-vars).549On models with adaptive reasoning, `MAX_THINKING_TOKENS` only applies when set to `0` to disable thinking, or when `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` reverts the model to the fixed budget. `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` applies to Opus 4.6 and Sonnet 4.6 only. Opus 4.7 always uses adaptive reasoning and does not support a fixed thinking budget. See [environment variables](/en/env-vars).

542 550

543<Warning>551<Warning>

544 You're charged for all thinking tokens used even when thinking summaries are redacted. In interactive mode, thinking appears as a collapsed stub by default. Set `showThinkingSummaries: true` in `settings.json` to show full summaries.552 You're charged for all thinking tokens used even when thinking summaries are redacted. In interactive mode, thinking appears as a collapsed stub by default. Set `showThinkingSummaries: true` in `settings.json` to show full summaries.

556 564

557From inside an active session, use `/resume` to switch to a different conversation.565From inside an active session, use `/resume` to switch to a different conversation.

558 566

559Sessions are stored per project directory. The `/resume` picker shows interactive sessions from the same git repository, including worktrees. When you select a session from another worktree of the same repository, Claude Code resumes it directly without requiring you to switch directories first. Sessions created by `claude -p` or SDK invocations do not appear in the picker, but you can still resume one by passing its session ID or custom name to `claude --resume <session-id-or-name>`. Custom names set with `--name` or `/rename` are accepted in addition to session IDs.567Sessions are stored per project directory. By default, the `/resume` picker shows interactive sessions from the current worktree, with keyboard shortcuts to widen the list to other worktrees or projects, search, preview, and rename. See [Use the session picker](#use-the-session-picker) below for the full shortcut reference.

568

569When you select a session from another worktree of the same repository, Claude Code resumes it directly without requiring you to switch directories first. Selecting a session from an unrelated project copies a `cd` and resume command to your clipboard instead.

570

571Resuming by name resolves across the current repository and its worktrees. Both `claude --resume <name>` and `/resume <name>` look for an exact match and resume it directly, even if the session lives in a different worktree.

572

573When the name is ambiguous, `claude --resume <name>` opens the picker with the name pre-filled as a search term. `/resume <name>` from inside a session reports an error instead, so run `/resume` with no argument to open the picker and choose.

574

575Sessions created by `claude -p` or SDK invocations do not appear in the picker, but you can still resume one by passing its session ID directly to `claude --resume <session-id>`.

560 576

561### Name your sessions577### Name your sessions

562 578

576 /rename auth-refactor592 /rename auth-refactor

577 ```593 ```

578 594

579 You can also rename any session from the picker: run `/resume`, navigate to a session, and press `R`.595 You can also rename any session from the picker: run `/resume`, navigate to a session, and press `Ctrl+R`.

580 </Step>596 </Step>

581 597

582 <Step title="Resume by name later">598 <Step title="Resume by name later">

601**Keyboard shortcuts in the picker:**617**Keyboard shortcuts in the picker:**

602 618

603| Shortcut | Action |619| Shortcut | Action |

604| :-------- | :------------------------------------------------ |620| :------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------- |

605| `↑` / `↓` | Navigate between sessions |621| `↑` / `↓` | Navigate between sessions |

606| `→` / `←` | Expand or collapse grouped sessions |622| `→` / `←` | Expand or collapse grouped sessions |

608| `P` | Preview the session content |624| `Space` | Preview the session content. `Ctrl+V` also works on terminals that do not capture it as paste |

609| `R` | Rename the highlighted session |625| `Ctrl+R` | Rename the highlighted session |

610| `/` | Search to filter sessions |626| `/` or any printable character other than `Space` | Enter search mode and filter sessions |

611| `A` | Toggle between current directory and all projects |627| `Ctrl+A` | Show sessions from all projects on this machine. Press again to restore the current repository |

612| `B` | Filter to sessions from your current git branch |628| `Ctrl+W` | Show sessions from all worktrees of the current repository. Press again to restore the current worktree. Only shown in multi-worktree repositories |

629| `Ctrl+B` | Filter to sessions from your current git branch. Press again to show sessions from all branches |

613| `Esc` | Exit the picker or search mode |630| `Esc` | Exit the picker or search mode |

614 631

615**Session organization:**632**Session organization:**

616 633

617The picker displays sessions with helpful metadata:634The picker displays sessions with helpful metadata:

618 635

619* Session name or initial prompt636* Session name if set, otherwise the conversation summary or first user prompt

620* Time elapsed since last activity637* Time elapsed since last activity

621* Message count638* Message count

622* Git branch (if applicable)639* Git branch (if applicable)

640* Project path, shown after widening to all projects with `Ctrl+A`

623 641

624Forked sessions (created with `/branch`, `/rewind`, or `--fork-session`) are grouped together under their root session, making it easier to find related conversations.642Forked sessions (created with `/branch`, `/rewind`, or `--fork-session`) are grouped together under their root session, making it easier to find related conversations.

625 643

631 * Use `--resume session-name` when you know which session you need649 * Use `--resume session-name` when you know which session you need

632 * Use `--resume` (without a name) when you need to browse and select650 * Use `--resume` (without a name) when you need to browse and select

633 * For scripts, use `claude --continue --print "prompt"` to resume in non-interactive mode651 * For scripts, use `claude --continue --print "prompt"` to resume in non-interactive mode

634 * Press `P` in the picker to preview a session before resuming it652 * Press `Space` in the picker to preview a session before resuming it

635 * The resumed conversation starts with the same model and configuration as the original653 * The resumed conversation starts with the same model and configuration as the original

636 654

637 How it works:655 How it works:

935| [Routines](/en/routines) | Anthropic-managed infrastructure | Tasks that should run even when your computer is off. Can also trigger on API calls or GitHub events in addition to a schedule. Configure at [claude.ai/code/routines](https://claude.ai/code/routines). |953| [Routines](/en/routines) | Anthropic-managed infrastructure | Tasks that should run even when your computer is off. Can also trigger on API calls or GitHub events in addition to a schedule. Configure at [claude.ai/code/routines](https://claude.ai/code/routines). |

938| [`/loop`](/en/scheduled-tasks) | The current CLI session | Quick polling while a session is open. Tasks are cancelled when you exit. |956| [`/loop`](/en/scheduled-tasks) | The current CLI session | Quick polling while a session is open. Tasks stop when you start a new conversation; `--resume` and `--continue` restore unexpired ones. |

939 957

940<Tip>958<Tip>

941 When writing prompts for scheduled tasks, be explicit about what success looks like and what to do with results. The task runs autonomously, so it can't ask clarifying questions. For example: "Review open PRs labeled `needs-review`, leave inline comments on any issues, and post a summary in the `#eng-reviews` Slack channel."959 When writing prompts for scheduled tasks, be explicit about what success looks like and what to do with results. The task runs autonomously, so it can't ask clarifying questions. For example: "Review open PRs labeled `needs-review`, leave inline comments on any issues, and post a summary in the `#eng-reviews` Slack channel."

costs.md +1 −1

Details

20 The `/cost` command shows API token usage and is intended for API users. Claude Max and Pro subscribers have usage included in their subscription, so `/cost` data isn't relevant for billing purposes. Subscribers can use `/stats` to view usage patterns.20 The `/cost` command shows API token usage and is intended for API users. Claude Max and Pro subscribers have usage included in their subscription, so `/cost` data isn't relevant for billing purposes. Subscribers can use `/stats` to view usage patterns.

21</Note>21</Note>

22 22

~~23The `/cost` command provides detailed token usage statistics for your current session:~~23The `/cost` command provides detailed token usage statistics for your current session. The dollar figure is an estimate computed locally from token counts and may differ from your actual bill. For authoritative billing, see the Usage page in the [Claude Console](https://platform.claude.com/usage).

24 24

25```text theme={null}25```text theme={null}

26Total cost: $0.5526Total cost: $0.55

data-usage.md +9 −2

Details

86 86

87## Default behaviors by API provider87## Default behaviors by API provider

88 88

89By default, error reporting, telemetry, and bug reporting are disabled when using Bedrock, Vertex, or Foundry. Session quality surveys are the exception and appear regardless of provider. You can opt out of all non-essential traffic, including surveys, at once by setting `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`. Here are the full default behaviors:89By default, error reporting, telemetry, and bug reporting are disabled when using Bedrock, Vertex, or Foundry. Session quality surveys and the WebFetch domain safety check are exceptions and run regardless of provider. You can opt out of all non-essential traffic, including surveys, at once by setting `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`. This variable does not affect the WebFetch check, which has its own opt-out. Here are the full default behaviors:

90 90

92| ------------------------------------ | -------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- |92| ------------------------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |

95| **Claude API (`/feedback` reports)** | Default on.<br />`DISABLE_FEEDBACK_COMMAND=1` to disable. | Default off.<br />`CLAUDE_CODE_USE_VERTEX` must be 1. | Default off.<br />`CLAUDE_CODE_USE_BEDROCK` must be 1. | Default off.<br />`CLAUDE_CODE_USE_FOUNDRY` must be 1. |95| **Claude API (`/feedback` reports)** | Default on.<br />`DISABLE_FEEDBACK_COMMAND=1` to disable. | Default off.<br />`CLAUDE_CODE_USE_VERTEX` must be 1. | Default off.<br />`CLAUDE_CODE_USE_BEDROCK` must be 1. | Default off.<br />`CLAUDE_CODE_USE_FOUNDRY` must be 1. |

96| **Session quality surveys** | Default on.<br />`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on.<br />`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on.<br />`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on.<br />`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. |96| **Session quality surveys** | Default on.<br />`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on.<br />`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on.<br />`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on.<br />`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. |

97| **WebFetch domain safety check** | Default on.<br />`skipWebFetchPreflight: true` in [settings](/en/settings) to disable. | Default on.<br />`skipWebFetchPreflight: true` in [settings](/en/settings) to disable. | Default on.<br />`skipWebFetchPreflight: true` in [settings](/en/settings) to disable. | Default on.<br />`skipWebFetchPreflight: true` in [settings](/en/settings) to disable. |

97 98

98All environment variables can be checked into `settings.json` (see [settings reference](/en/settings)).99All environment variables can be checked into `settings.json` (see [settings reference](/en/settings)).

100

101### WebFetch domain safety check

102

103Before fetching a URL, the WebFetch tool sends the requested hostname to `api.anthropic.com` to check it against a safety blocklist maintained by Anthropic. Only the hostname is sent, not the full URL, path, or page contents. Results are cached per hostname for five minutes.

104

105This check runs regardless of which model provider you use and is not affected by `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`. If your network blocks `api.anthropic.com`, WebFetch requests fail until you either allowlist the domain or set `skipWebFetchPreflight: true` in [settings](/en/settings). Disabling the check means WebFetch attempts to retrieve any URL without consulting the blocklist, so combine it with [`WebFetch` permission rules](/en/permissions#webfetch) if you need to restrict which domains Claude can reach.

debug-your-config.md +96 −0 added

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Debug your configuration

7> Diagnose why CLAUDE.md, settings, hooks, MCP servers, or skills aren't taking effect. Use /context, /doctor, /hooks, and /mcp to see what actually loaded.

9When Claude ignores an instruction or a feature you configured doesn't appear, the cause is usually that the file didn't load, it loaded from a different location than you expected, or another file overrode it. This guide shows how to inspect what Claude Code actually loaded so you can narrow down which applies.

11For installation, authentication, and connectivity problems, see [Troubleshooting](/en/troubleshooting) instead.

13## See what loaded into context

15The `/context` command shows everything occupying the context window for the current session, broken down by category: system prompt, memory files, skills, MCP tools, and conversation messages. Run it first to confirm whether your `CLAUDE.md`, rules, or skill descriptions are present at all.

17For detail on a specific category, follow up with the dedicated command:

19| Command | Shows |

20| :------------- | :-------------------------------------------------------------------------- |

21| `/memory` | Which `CLAUDE.md` and rules files loaded, plus auto-memory entries |

22| `/skills` | Available skills from project, user, and plugin sources |

23| `/agents` | Configured subagents and their settings |

24| `/hooks` | Active hook configurations |

25| `/mcp` | Connected MCP servers and their status |

26| `/permissions` | Resolved allow and deny rules currently in effect |

27| `/doctor` | Configuration diagnostics: invalid keys, schema errors, installation health |

28| `/status` | Active settings sources, including whether managed settings are in effect |

30If a memory file is missing from `/memory`, check its location against [how CLAUDE.md files load](/en/memory#how-claude-md-files-load). Subdirectory `CLAUDE.md` files load on demand when Claude reads a file in that directory with the Read tool, not at session start.

32If `/memory` confirms the file loaded but Claude still isn't following a particular instruction, the issue is likely how the instruction is written rather than whether it loaded. CLAUDE.md works well for the kinds of guidance you'd give a new teammate, such as project conventions, build commands, and where files belong.

34Adherence drops when an instruction is vague enough to interpret multiple ways, when two files give conflicting direction, or when the file has grown long enough that individual rules get less attention. [Write effective instructions](/en/memory#write-effective-instructions) covers the specificity, size, and structure patterns that keep adherence high.

36<Note>

37 CLAUDE.md and permissions solve different problems. CLAUDE.md tells Claude how your project works so it makes good decisions. [Permissions](/en/permissions) and [hooks](/en/hooks) enforce limits regardless of what Claude decides. Use CLAUDE.md for "we do it this way here." Use permissions or hooks for security boundaries and anything that must never happen, where you need a guarantee instead of guidance.

38</Note>

40## Check resolved settings

42Settings merge across managed, user, project, and local scopes. Managed settings always win when present. Among the rest, the closer scope overrides the broader one in the order local, then project, then user. Some settings can also be set by command-line flags or [environment variables](/en/env-vars), which act as another override layer. When a setting doesn't seem to apply, the value you set is usually being overridden by another scope or an environment variable.

44Run `/doctor` to validate your configuration files and surface invalid keys or schema errors. Run `/status` to see which settings sources are active, including whether managed settings are in effect. To understand which scope wins for a given key, see [How scopes interact](/en/settings#how-scopes-interact).

46## Check MCP servers

48Run `/mcp` to see every configured server, its connection status, and whether you have approved it for the current project. A server can be defined correctly but still not provide tools for a few common reasons:

50* Project-scoped servers in `.mcp.json` require a one-time approval. If the prompt was dismissed, the server stays disabled until you approve it from `/mcp`.

51* A server that fails to start shows as failed in `/mcp`. Relative file paths in `command` or `args` are a frequent cause, since they resolve against the directory you launched Claude Code from rather than the location of `.mcp.json`.

52* A server that shows as connected but lists zero tools has started successfully but isn't returning a tool list. Select **Reconnect** from `/mcp`. If the count stays at zero, run `claude --debug mcp` to see the server's stderr output.

54For configuration locations and scope rules, see [MCP](/en/mcp).

56## Check hooks

58Run `/hooks` to list every hook registered for the current session, grouped by event. If a hook you defined doesn't appear, it isn't being read: hooks go under the `"hooks"` key in a settings file, not in a standalone file.

60If the hook appears but doesn't fire, the matcher is the usual cause. The `matcher` field is a single string that uses `|` to match multiple tool names, for example `"Edit|Write"`. A misspelled tool name fails silently because the matcher never matches. An array value is a schema error: Claude Code shows a settings error notice, `/doctor` reports the validation failure, and the hook entry is dropped so it won't appear in `/hooks`.

62Edits to `settings.json` take effect in the running session after a brief file-stability delay. You don't need to restart. If `/hooks` still shows the old definition a few seconds after saving, run `/hooks` again to refresh the view.

64If `/hooks` shows the hook but it still does not fire, the next step is to watch hook evaluation live. Start a session with `claude --debug hooks` and trigger the tool call. The debug log records each event, which matchers were checked, and the hook's exit code and output. See [Debug hooks](/en/hooks#debug-hooks) for the log format and [hooks troubleshooting](/en/hooks-guide#limitations-and-troubleshooting) for common failure patterns.

66## Common causes

68Most configuration surprises trace back to a small set of location and syntax rules. Check these before assuming a bug:

70| Symptom | Cause | Fix |

71| :--------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

73| Hook never fires | `matcher` value is lowercase, for example `"bash"` | Matching is case-sensitive. Tool names are capitalized: `Bash`, `Edit`, `Write`, `Read`. |

74| Hook never fires | Hooks are in a standalone `.claude/hooks.json` file | There is no standalone hooks file. Define hooks under the `"hooks"` key in `settings.json`. See [hook configuration](/en/hooks). |

75| Permissions, hooks, or env set globally are ignored | Configuration was added to `~/.claude.json` | `~/.claude.json` holds app state and UI toggles. `permissions`, `hooks`, and `env` belong in `~/.claude/settings.json`. These are two different files. |

76| A `settings.json` value seems ignored | The same key is set in `settings.local.json` | `settings.local.json` overrides `settings.json`, and both override `~/.claude/settings.json`. See [settings precedence](/en/settings#how-scopes-interact). |

77| Skill doesn't appear in `/skills` | Skill file is at `.claude/skills/name.md` instead of in a folder | Use a folder with `SKILL.md` inside: `.claude/skills/name/SKILL.md`. |

78| Skill appears in `/skills` but Claude never invokes it | Skill has `disable-model-invocation: true` in its frontmatter, or its description doesn't match how you phrase the request | Check the badge in `/skills`: a "user-only" label means Claude won't trigger it on its own. See [skill invocation](/en/skills). |

79| Subdirectory `CLAUDE.md` instructions seem ignored | Subdirectory files load on demand, not at session start | They load when Claude reads a file in that directory with the Read tool, not at launch and not when writing or creating files there. See [how CLAUDE.md files load](/en/memory#how-claude-md-files-load). |

80| Subagent ignores `CLAUDE.md` instructions | Subagents don't always inherit project memory | Put critical rules in the agent file body, which becomes the subagent's system prompt. See [subagent configuration](/en/sub-agents). |

81| Cleanup logic never runs at session end | No `SessionEnd` hook configured | `SessionStart` and `SessionEnd` both exist. See the [hook events list](/en/hooks#hook-events). |

82| MCP servers in `.mcp.json` never load | File is under `.claude/` or uses Claude Desktop's config format | Project MCP config goes at the repository root as `.mcp.json`, not inside `.claude/`. See [MCP configuration](/en/mcp). |

83| Project MCP server added but doesn't appear | The one-time approval prompt was dismissed | Project-scoped servers require approval. Run `/mcp` to see status and approve. |

84| MCP server fails to start from some directories | `command` or `args` uses a relative file path | Use absolute paths for local scripts. Executables on your `PATH` like `npx` or `uvx` work as-is. |

85| MCP server starts without expected environment variables | Variables are in `settings.json` `env`, which doesn't propagate to MCP child processes | Set per-server `env` inside `.mcp.json` instead. |

86| `Bash(rm *)` deny rule doesn't block `/bin/rm` or `find -delete` | Prefix rules match the literal command string, not the underlying executable | Add explicit patterns for each variant, or use a [PreToolUse hook](/en/hooks-guide) or the [sandbox](/en/sandboxing) for a hard guarantee. |

88## Related resources

90For full reference on each configuration surface, see the dedicated page:

92* **[`.claude` directory reference](/en/claude-directory)**: every config file location and what reads it

93* **[Settings](/en/settings)**: precedence order and the full key list

94* **[Hooks reference](/en/hooks)**: event names, payloads, and `--debug hooks` output format

95* **[MCP](/en/mcp)**: server configuration, approval, and `/mcp` output

96* **[Troubleshooting](/en/troubleshooting)**: `claude doctor`, platform issues, and installation problems

desktop.md +43 −12

Details

8 8

9The Code tab within the Claude Desktop app lets you use Claude Code through a graphical interface instead of the terminal.9The Code tab within the Claude Desktop app lets you use Claude Code through a graphical interface instead of the terminal.

10 10

11<CardGroup cols={2}>

12 <Card title="Download for macOS" icon="apple" href="https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs">

13 Universal build for Intel and Apple Silicon

14 </Card>

16 <Card title="Download for Windows" icon="windows" href="https://claude.ai/api/desktop/win32/x64/setup/latest/redirect?utm_source=claude_code&utm_medium=docs">

17 For x64 processors

18 </Card>

19</CardGroup>

21For Windows ARM64, download the [ARM64 installer](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs). Linux is not supported.

23After installing, launch Claude, sign in, and click the **Code** tab. See the [Get started guide](/en/desktop-quickstart) for a full walkthrough of your first session.

11Desktop adds these capabilities on top of the standard Claude Code experience:25Desktop adds these capabilities on top of the standard Claude Code experience:

12 26

13* [Parallel sessions](#work-in-parallel-with-sessions) with automatic Git worktree isolation27* [Parallel sessions](#work-in-parallel-with-sessions) with automatic Git worktree isolation

22* [Connectors](#connect-external-tools) for GitHub, Slack, Linear, and more36* [Connectors](#connect-external-tools) for GitHub, Slack, Linear, and more

23* Local, [SSH](#ssh-sessions), and [cloud](#run-long-running-tasks-remotely) environments37* Local, [SSH](#ssh-sessions), and [cloud](#run-long-running-tasks-remotely) environments

24 38

~~25<Tip>~~

~~26 New to Desktop? Start with [Get started](/en/desktop-quickstart) to install the app and make your first edit.~~

~~27</Tip>~~

29<Note>39<Note>

30 The workspace layout, terminal, file editor, side chats, and view modes described on this page require Claude Desktop v1.2581.0 or later. Open **Claude → Check for Updates** on macOS or **Help → Check for Updates** on Windows to update.40 The workspace layout, terminal, file editor, side chats, and view modes described on this page require Claude Desktop v1.2581.0 or later. Open **Claude → Check for Updates** on macOS or **Help → Check for Updates** on Windows to update.

31</Note>41</Note>

65Permission modes control how much autonomy Claude has during a session: whether it asks before editing files, running commands, or both. You can switch modes at any time using the mode selector next to the send button. Start with Ask permissions to see exactly what Claude does, then move to Auto accept edits or Plan mode as you get comfortable.75Permission modes control how much autonomy Claude has during a session: whether it asks before editing files, running commands, or both. You can switch modes at any time using the mode selector next to the send button. Start with Ask permissions to see exactly what Claude does, then move to Auto accept edits or Plan mode as you get comfortable.

66 76

68| ---------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |78| ---------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

70| **Auto accept edits** | `acceptEdits` | Claude auto-accepts file edits and common filesystem commands like `mkdir`, `touch`, and `mv`, but still asks before running other terminal commands. Use this when you trust file changes and want faster iteration. |80| **Auto accept edits** | `acceptEdits` | Claude auto-accepts file edits and common filesystem commands like `mkdir`, `touch`, and `mv`, but still asks before running other terminal commands. Use this when you trust file changes and want faster iteration. |

71| **Plan mode** | `plan` | Claude reads files and runs commands to explore, then proposes a plan without editing your source code. Good for complex tasks where you want to review the approach first. |81| **Plan mode** | `plan` | Claude reads files and runs commands to explore, then proposes a plan without editing your source code. Good for complex tasks where you want to review the approach first. |

72| **Auto** | `auto` | Claude executes all actions with background safety checks that verify alignment with your request. Reduces permission prompts while maintaining oversight. Currently a research preview. Available on Team, Enterprise, and API plans. Requires Claude Sonnet 4.6 or Opus 4.6. Enable in your Settings → Claude Code. |82| **Auto** | `auto` | Claude executes all actions with background safety checks that verify alignment with your request. Reduces permission prompts while maintaining oversight. Currently a research preview. Available on Max, Team, Enterprise, and API plans. Requires Claude Sonnet 4.6, Opus 4.6, or Opus 4.7 on Team, Enterprise, and API plans; Claude Opus 4.7 only on Max plans. Not available on Pro plans or third-party providers. Enable in your Settings → Claude Code. |

73| **Bypass permissions** | `bypassPermissions` | Claude runs without any permission prompts, equivalent to `--dangerously-skip-permissions` in the CLI. Enable in your Settings → Claude Code under "Allow bypass permissions mode". Only use this in sandboxed containers or VMs. Enterprise admins can disable this option. |83| **Bypass permissions** | `bypassPermissions` | Claude runs without any permission prompts, equivalent to `--dangerously-skip-permissions` in the CLI. Enable in your Settings → Claude Code under "Allow bypass permissions mode". Only use this in sandboxed containers or VMs. Enterprise admins can disable this option. |

74 84

75The `dontAsk` permission mode is available only in the [CLI](/en/permission-modes#allow-only-pre-approved-tools-with-dontask-mode).85The `dontAsk` permission mode is available only in the [CLI](/en/permission-modes#allow-only-pre-approved-tools-with-dontask-mode).

506 516

507To set environment variables for local sessions and dev servers on any platform, open the environment dropdown in the prompt box, hover over **Local**, and click the gear icon to open the local environment editor. Variables you save here are stored encrypted on your machine and apply to every local session and preview server you start. You can also add variables to the `env` key in your `~/.claude/settings.json` file, though these reach Claude sessions only and not dev servers. See [environment variables](/en/env-vars) for the full list of supported variables.517To set environment variables for local sessions and dev servers on any platform, open the environment dropdown in the prompt box, hover over **Local**, and click the gear icon to open the local environment editor. Variables you save here are stored encrypted on your machine and apply to every local session and preview server you start. You can also add variables to the `env` key in your `~/.claude/settings.json` file, though these reach Claude sessions only and not dev servers. See [environment variables](/en/env-vars) for the full list of supported variables.

508 518

509[Extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) is enabled by default, which improves performance on complex reasoning tasks but uses additional tokens. To disable thinking entirely, set `MAX_THINKING_TOKENS` to `0` in the local environment editor. On Opus 4.6 and Sonnet 4.6, any other `MAX_THINKING_TOKENS` value is ignored because adaptive reasoning controls thinking depth instead. To use a fixed thinking budget on these models, also set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` to `1`.519[Extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) is enabled by default, which improves performance on complex reasoning tasks but uses additional tokens. To disable thinking entirely, set `MAX_THINKING_TOKENS` to `0` in the local environment editor. On models with [adaptive reasoning](/en/model-config#adjust-effort-level), any other `MAX_THINKING_TOKENS` value is ignored because adaptive reasoning controls thinking depth instead. On Opus 4.6 and Sonnet 4.6, set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` to `1` to use a fixed thinking budget; Opus 4.7 always uses adaptive reasoning and has no fixed-budget mode.

510 520

511### Remote sessions521### Remote sessions

512 522

529 539

530The remote machine must run Linux or macOS, and Claude Code must be installed on it. Once connected, SSH sessions support permission modes, connectors, plugins, and MCP servers.540The remote machine must run Linux or macOS, and Claude Code must be installed on it. Once connected, SSH sessions support permission modes, connectors, plugins, and MCP servers.

531 541

542#### Pre-configure SSH connections for your team

543

544Administrators can distribute SSH connections to team members by adding `sshConfigs` to a [managed settings](/en/settings#settings-precedence) file. Connections defined this way appear in each user's environment dropdown automatically and are shown as managed, so users can select them but cannot edit or delete them in the app.

545

546The following example pre-configures a single connection that opens in `~/projects` on the remote host:

547

548```json theme={null}

549{

550 "sshConfigs": [

551 {

552 "id": "shared-dev-vm",

553 "name": "Shared Dev VM",

554 "sshHost": "user@dev.example.com",

555 "sshPort": 22,

556 "sshIdentityFile": "~/.ssh/id_ed25519",

557 "startDirectory": "~/projects"

558 }

559 ]

560}

561```

562

563Each entry requires `id`, `name`, and `sshHost`. The `sshPort`, `sshIdentityFile`, and `startDirectory` fields are optional. Users can also add `sshConfigs` to their own `~/.claude/settings.json`, which is where connections added through the dialog are stored.

564

532## Enterprise configuration565## Enterprise configuration

533 566

534Organizations on Team or Enterprise plans can manage desktop app behavior through admin console controls, managed settings files, and device management policies.567Organizations on Team or Enterprise plans can manage desktop app behavior through admin console controls, managed settings files, and device management policies.

551| `permissions.disableBypassPermissionsMode` | set to `"disable"` to prevent users from enabling Bypass permissions mode. |584| `permissions.disableBypassPermissionsMode` | set to `"disable"` to prevent users from enabling Bypass permissions mode. |

552| `disableAutoMode` | set to `"disable"` to prevent users from enabling [Auto](/en/permission-modes#eliminate-prompts-with-auto-mode) mode. Removes Auto from the mode selector. Also accepted under `permissions`. |585| `disableAutoMode` | set to `"disable"` to prevent users from enabling [Auto](/en/permission-modes#eliminate-prompts-with-auto-mode) mode. Removes Auto from the mode selector. Also accepted under `permissions`. |

553| `autoMode` | customize what the auto mode classifier trusts and blocks across your organization. See [Configure the auto mode classifier](/en/permissions#configure-the-auto-mode-classifier). |586| `autoMode` | customize what the auto mode classifier trusts and blocks across your organization. See [Configure the auto mode classifier](/en/permissions#configure-the-auto-mode-classifier). |

587| `sshConfigs` | pre-configure [SSH connections](#pre-configure-ssh-connections-for-your-team) that appear in the environment dropdown. Users cannot edit or delete managed connections. |

554 588

555`permissions.disableBypassPermissionsMode` and `disableAutoMode` also work in user and project settings, but placing them in managed settings prevents users from overriding them. `autoMode` is read from user settings, `.claude/settings.local.json`, and managed settings, but not from the checked-in `.claude/settings.json`: a cloned repo cannot inject its own classifier rules. For the complete list of managed-only settings including `allowManagedPermissionRulesOnly` and `allowManagedHooksOnly`, see [managed-only settings](/en/permissions#managed-only-settings).589`permissions.disableBypassPermissionsMode` and `disableAutoMode` also work in user and project settings, but placing them in managed settings prevents users from overriding them. `autoMode` is read from user settings, `.claude/settings.local.json`, and managed settings, but not from the checked-in `.claude/settings.json`: a cloned repo cannot inject its own classifier rules. For the complete list of managed-only settings including `allowManagedPermissionRulesOnly` and `allowManagedHooksOnly`, see [managed-only settings](/en/permissions#managed-only-settings).

556 590

654 688

655## Troubleshooting689## Troubleshooting

656 690

691The sections below cover issues specific to the desktop app. For runtime API errors that appear in the chat such as `API Error: 500`, `529 Overloaded`, `429`, or `Prompt is too long`, see the [Error reference](/en/errors). Those errors and their fixes are the same across the CLI, desktop, and web.

692

657### Check your version693### Check your version

658 694

659To see which version of the desktop app you're running:695To see which version of the desktop app you're running:

707 743

708* **PATH not updated after install**: open a new terminal window. PATH updates only apply to new terminal sessions.744* **PATH not updated after install**: open a new terminal window. PATH updates only apply to new terminal sessions.

709* **Concurrent installation error**: if you see an error about another installation in progress but there isn't one, try running the installer as Administrator.745* **Concurrent installation error**: if you see an error about another installation in progress but there isn't one, try running the installer as Administrator.

710* **ARM64**: Windows ARM64 devices are fully supported.

~~711~~

712### Cowork tab unavailable on Intel Macs

~~713~~

714The Cowork tab requires Apple Silicon (M1 or later) on macOS. On Windows, Cowork is available on all supported hardware. The Chat and Code tabs work normally on Intel Macs.

715 746

716### "Branch doesn't exist yet" when opening in CLI747### "Branch doesn't exist yet" when opening in CLI

717 748

desktop-quickstart.md +4 −12

Details

8 8

9The desktop app gives you Claude Code with a graphical interface built for running multiple sessions side by side: a sidebar for managing parallel work, a drag-and-drop layout with an integrated terminal and file editor, visual diff review, live app preview, GitHub PR monitoring with auto-merge, and scheduled tasks. No terminal required.9The desktop app gives you Claude Code with a graphical interface built for running multiple sessions side by side: a sidebar for managing parallel work, a drag-and-drop layout with an integrated terminal and file editor, visual diff review, live app preview, GitHub PR monitoring with auto-merge, and scheduled tasks. No terminal required.

10 10

~~11Download Claude for your platform:~~

13<CardGroup cols={2}>11<CardGroup cols={2}>

~~14 <Card title="macOS" icon="apple" href="https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs">~~12 <Card title="Download for macOS" icon="apple" href="https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs">

15 Universal build for Intel and Apple Silicon13 Universal build for Intel and Apple Silicon

16 </Card>14 </Card>

17 15

~~18 <Card title="Windows" icon="windows" href="https://claude.ai/api/desktop/win32/x64/setup/latest/redirect?utm_source=claude_code&utm_medium=docs">~~16 <Card title="Download for Windows" icon="windows" href="https://claude.ai/api/desktop/win32/x64/setup/latest/redirect?utm_source=claude_code&utm_medium=docs">

19 For x64 processors17 For x64 processors

20 </Card>18 </Card>

21</CardGroup>19</CardGroup>

22 20

~~23For Windows ARM64, download the [ARM64 installer](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs). Linux is not currently supported.~~21For Windows ARM64, download the [ARM64 installer](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs). Linux is not supported.

24 22

25<Note>23<Note>

26 Claude Code requires a [Pro, Max, Team, or Enterprise subscription](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=desktop_quickstart_pricing).24 Claude Code requires a [Pro, Max, Team, or Enterprise subscription](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=desktop_quickstart_pricing).

40 38

41<Steps>39<Steps>

42 <Step title="Install and sign in">40 <Step title="Install and sign in">

~~43 Download Claude for your platform and run the installer:~~41 Download the installer for your platform from the links above and run it. Launch Claude from your Applications folder on macOS or the Start menu on Windows, then sign in with your Anthropic account.

~~45 * [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs): universal build for Intel and Apple Silicon~~

~~46 * [Windows x64](https://claude.ai/api/desktop/win32/x64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs): for x64 processors~~

~~47 * [Windows ARM64](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs): for ARM processors~~

~~49 Launch Claude from your Applications folder (macOS) or Start menu (Windows). Sign in with your Anthropic account.~~

50 </Step>42 </Step>

51 43

52 <Step title="Open the Code tab">44 <Step title="Open the Code tab">

desktop-scheduled-tasks.md +2 −2

Details

13Claude Code offers three ways to schedule recurring work:13Claude Code offers three ways to schedule recurring work:

14 14

~~16| :------------------------- | :----------------------------- | :------------------------------------- | :----------------------------- |~~16| :------------------------- | :----------------------------- | :------------------------------------- | :---------------------------------- |

18| Requires machine on | No | Yes | Yes |18| Requires machine on | No | Yes | Yes |

19| Requires open session | No | No | Yes |19| Requires open session | No | No | Yes |

~~20| Persistent across restarts | Yes | Yes | No (session-scoped) |~~20| Persistent across restarts | Yes | Yes | Restored on `--resume` if unexpired |

21| Access to local files | No (fresh clone) | Yes | Yes |21| Access to local files | No (fresh clone) | Yes | Yes |

discover-plugins.md +9 −3

Details

259 259

260You may also see plugins with **managed** scope—these are installed by administrators via [managed settings](/en/settings#settings-files) and cannot be modified.260You may also see plugins with **managed** scope—these are installed by administrators via [managed settings](/en/settings#settings-files) and cannot be modified.

261 261

262Run `/plugin` and go to the **Installed** tab to see your plugins grouped by scope.

~~263~~

264<Warning>262<Warning>

265 Make sure you trust a plugin before installing it. Anthropic does not control what MCP servers, files, or other software are included in plugins and cannot verify that they work as intended. Check each plugin's homepage for more information.263 Make sure you trust a plugin before installing it. Anthropic does not control what MCP servers, files, or other software are included in plugins and cannot verify that they work as intended. Check each plugin's homepage for more information.

266</Warning>264</Warning>

267 265

268## Manage installed plugins266## Manage installed plugins

269 267

270Run `/plugin` and go to the **Installed** tab to view, enable, disable, or uninstall your plugins. Type to filter the list by plugin name or description.268Run `/plugin` and go to the **Installed** tab to view, enable, disable, or uninstall your plugins. The list is grouped by scope and sorted so you see problems first: plugins with load errors or unresolved dependencies appear at the top, followed by your favorites, with disabled plugins folded behind a collapsed header at the bottom.

269

270From the list you can:

271

272* press `f` to favorite or unfavorite the selected plugin

273* type to filter by plugin name or description

274* press Enter to open a plugin's detail view and enable, disable, or uninstall it

275

276When you install a plugin that declares dependencies, the install output lists which dependencies were auto-installed alongside it.

271 277

272You can also manage plugins with direct commands.278You can also manage plugins with direct commands.

273 279

env-vars.md +19 −9

Details

65| `CLAUDE_CODE_DEBUG_LOGS_DIR` | Override the debug log file path. Despite the name, this is a file path, not a directory. Requires debug mode to be enabled separately via `--debug` or `/debug`: setting this variable alone does not enable logging. The [`--debug-file`](/en/cli-reference#cli-flags) flag does both at once. Defaults to `~/.claude/debug/<session-id>.txt` |65| `CLAUDE_CODE_DEBUG_LOGS_DIR` | Override the debug log file path. Despite the name, this is a file path, not a directory. Requires debug mode to be enabled separately via `--debug` or `/debug`: setting this variable alone does not enable logging. The [`--debug-file`](/en/cli-reference#cli-flags) flag does both at once. Defaults to `~/.claude/debug/<session-id>.txt` |

66| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | Minimum log level written to the debug log file. Values: `verbose`, `debug` (default), `info`, `warn`, `error`. Set to `verbose` to include high-volume diagnostics like full status line command output, or raise to `error` to reduce noise |66| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | Minimum log level written to the debug log file. Values: `verbose`, `debug` (default), `info`, `warn`, `error`. Set to `verbose` to include high-volume diagnostics like full status line command output, or raise to `error` to reduce noise |

67| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Set to `1` to disable [1M context window](/en/model-config#extended-context) support. When set, 1M model variants are unavailable in the model picker. Useful for enterprise environments with compliance requirements |67| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Set to `1` to disable [1M context window](/en/model-config#extended-context) support. When set, 1M model variants are unavailable in the model picker. Useful for enterprise environments with compliance requirements |

68| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | Set to `1` to disable [adaptive reasoning](/en/model-config#adjust-effort-level) for Opus 4.6 and Sonnet 4.6. When disabled, these models fall back to the fixed thinking budget controlled by `MAX_THINKING_TOKENS` |68| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | Set to `1` to disable [adaptive reasoning](/en/model-config#adjust-effort-level) on Opus 4.6 and Sonnet 4.6 and fall back to the fixed thinking budget controlled by `MAX_THINKING_TOKENS`. {/* min-version: 2.1.111 */}Has no effect on Opus 4.7, which always uses adaptive reasoning |

69| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | Set to `1` to disable attachment processing. File mentions with `@` syntax are sent as plain text instead of being expanded into file content |69| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | Set to `1` to disable attachment processing. File mentions with `@` syntax are sent as plain text instead of being expanded into file content |

70| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Set to `1` to disable [auto memory](/en/memory#auto-memory). Set to `0` to force auto memory on during the gradual rollout. When disabled, Claude does not create or load auto memory files |70| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Set to `1` to disable [auto memory](/en/memory#auto-memory). Set to `0` to force auto memory on during the gradual rollout. When disabled, Claude does not create or load auto memory files |

71| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Set to `1` to disable all background task functionality, including the `run_in_background` parameter on Bash and subagent tools, auto-backgrounding, and the Ctrl+B shortcut |71| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Set to `1` to disable all background task functionality, including the `run_in_background` parameter on Bash and subagent tools, auto-backgrounding, and the Ctrl+B shortcut |

85| `CLAUDE_CODE_DISABLE_THINKING` | Set to `1` to force-disable [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) regardless of model support or other settings. More direct than `MAX_THINKING_TOKENS=0` |85| `CLAUDE_CODE_DISABLE_THINKING` | Set to `1` to force-disable [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) regardless of model support or other settings. More direct than `MAX_THINKING_TOKENS=0` |

86| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | Set to `1` to disable virtual scrolling in [fullscreen rendering](/en/fullscreen) and render every message in the transcript. Use this if scrolling in fullscreen mode shows blank regions where messages should appear |86| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | Set to `1` to disable virtual scrolling in [fullscreen rendering](/en/fullscreen) and render every message in the transcript. Use this if scrolling in fullscreen mode shows blank regions where messages should appear |

87| `CLAUDE_CODE_EFFORT_LEVEL` | Set the effort level for supported models. Values: `low`, `medium`, `high`, `max` (Opus 4.6 only), or `auto` to use the model default. Takes precedence over `/effort` and the `effortLevel` setting. See [Adjust effort level](/en/model-config#adjust-effort-level) |87| `CLAUDE_CODE_EFFORT_LEVEL` | Set the effort level for supported models. Values: `low`, `medium`, `high`, `xhigh`, `max`, or `auto` to use the model default. Available levels depend on the model. Takes precedence over `/effort` and the `effortLevel` setting. See [Adjust effort level](/en/model-config#adjust-effort-level) |

88| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | Override [session recap](/en/interactive-mode#session-recap) availability. Set to `0` to force recaps off regardless of the `/config` toggle. Set to `1` to force recaps on when [`awaySummaryEnabled`](/en/settings#available-settings) is `false`. Takes precedence over the setting and `/config` toggle |

89| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | Set to `1` to refresh plugin state at turn boundaries in [non-interactive mode](/en/headless) after a background install completes. Off by default because the refresh changes the system prompt mid-session, which invalidates [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for that turn |

88| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | Set to `1` to force-enable fine-grained tool input streaming. Without this, the API buffers tool input parameters fully before sending delta events, which can delay display on large tool inputs. Anthropic API only: has no effect on Bedrock, Vertex, or Foundry |90| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | Set to `1` to force-enable fine-grained tool input streaming. Without this, the API buffers tool input parameters fully before sending delta events, which can delay display on large tool inputs. Anthropic API only: has no effect on Bedrock, Vertex, or Foundry |

89| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | Set to `false` to disable prompt suggestions (the "Prompt suggestions" toggle in `/config`). These are the grayed-out predictions that appear in your prompt input after Claude responds. See [Prompt suggestions](/en/interactive-mode#prompt-suggestions) |91| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | Set to `false` to disable prompt suggestions (the "Prompt suggestions" toggle in `/config`). These are the grayed-out predictions that appear in your prompt input after Claude responds. See [Prompt suggestions](/en/interactive-mode#prompt-suggestions) |

90| `CLAUDE_CODE_ENABLE_TASKS` | Set to `1` to enable the task tracking system in non-interactive mode (the `-p` flag). Tasks are on by default in interactive mode. See [Task list](/en/interactive-mode#task-list) |92| `CLAUDE_CODE_ENABLE_TASKS` | Set to `1` to enable the task tracking system in non-interactive mode (the `-p` flag). Tasks are on by default in interactive mode. See [Task list](/en/interactive-mode#task-list) |

105| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | Maximum number of read-only tools and subagents that can execute in parallel (default: 10). Higher values increase parallelism but consume more resources |107| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | Maximum number of read-only tools and subagents that can execute in parallel (default: 10). Higher values increase parallelism but consume more resources |

106| `CLAUDE_CODE_NEW_INIT` | Set to `1` to make `/init` run an interactive setup flow. The flow asks which files to generate, including CLAUDE.md, skills, and hooks, before exploring the codebase and writing them. Without this variable, `/init` generates a CLAUDE.md automatically without prompting. |108| `CLAUDE_CODE_NEW_INIT` | Set to `1` to make `/init` run an interactive setup flow. The flow asks which files to generate, including CLAUDE.md, skills, and hooks, before exploring the codebase and writing them. Without this variable, `/init` generates a CLAUDE.md automatically without prompting. |

107| `CLAUDE_CODE_NO_FLICKER` | Set to `1` to enable [fullscreen rendering](/en/fullscreen), a research preview that reduces flicker and keeps memory flat in long conversations |109| `CLAUDE_CODE_NO_FLICKER` | Set to `1` to enable [fullscreen rendering](/en/fullscreen), a research preview that reduces flicker and keeps memory flat in long conversations. Equivalent to the [`tui`](/en/settings#available-settings) setting; you can also switch with `/tui fullscreen` |

108| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | OAuth refresh token for Claude.ai authentication. When set, `claude auth login` exchanges this token directly instead of opening a browser. Requires `CLAUDE_CODE_OAUTH_SCOPES`. Useful for provisioning authentication in automated environments |110| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | OAuth refresh token for Claude.ai authentication. When set, `claude auth login` exchanges this token directly instead of opening a browser. Requires `CLAUDE_CODE_OAUTH_SCOPES`. Useful for provisioning authentication in automated environments |

109| `CLAUDE_CODE_OAUTH_SCOPES` | Space-separated OAuth scopes the refresh token was issued with, such as `"user:profile user:inference user:sessions:claude_code"`. Required when `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` is set |111| `CLAUDE_CODE_OAUTH_SCOPES` | Space-separated OAuth scopes the refresh token was issued with, such as `"user:profile user:inference user:sessions:claude_code"`. Required when `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` is set |

110| `CLAUDE_CODE_OAUTH_TOKEN` | OAuth access token for Claude.ai authentication. Alternative to `/login` for SDK and automated environments. Takes precedence over keychain-stored credentials. Generate one with [`claude setup-token`](/en/authentication#generate-a-long-lived-token) |112| `CLAUDE_CODE_OAUTH_TOKEN` | OAuth access token for Claude.ai authentication. Alternative to `/login` for SDK and automated environments. Takes precedence over keychain-stored credentials. Generate one with [`claude setup-token`](/en/authentication#generate-a-long-lived-token) |

117| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | Set to `1` to keep the existing marketplace cache when a `git pull` fails instead of wiping and re-cloning. Useful in offline or airgapped environments where re-cloning would fail the same way. See [Marketplace updates fail in offline environments](/en/plugin-marketplaces#marketplace-updates-fail-in-offline-environments) |119| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | Set to `1` to keep the existing marketplace cache when a `git pull` fails instead of wiping and re-cloning. Useful in offline or airgapped environments where re-cloning would fail the same way. See [Marketplace updates fail in offline environments](/en/plugin-marketplaces#marketplace-updates-fail-in-offline-environments) |

118| `CLAUDE_CODE_PLUGIN_SEED_DIR` | Path to one or more read-only plugin seed directories, separated by `:` on Unix or `;` on Windows. Use this to bundle a pre-populated plugins directory into a container image. Claude Code registers marketplaces from these directories at startup and uses pre-cached plugins without re-cloning. See [Pre-populate plugins for containers](/en/plugin-marketplaces#pre-populate-plugins-for-containers) |120| `CLAUDE_CODE_PLUGIN_SEED_DIR` | Path to one or more read-only plugin seed directories, separated by `:` on Unix or `;` on Windows. Use this to bundle a pre-populated plugins directory into a container image. Claude Code registers marketplaces from these directories at startup and uses pre-cached plugins without re-cloning. See [Pre-populate plugins for containers](/en/plugin-marketplaces#pre-populate-plugins-for-containers) |

119| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | Set to `1` to allow the proxy to perform DNS resolution instead of the caller. Opt-in for environments where the proxy should handle hostname resolution |121| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | Set to `1` to allow the proxy to perform DNS resolution instead of the caller. Opt-in for environments where the proxy should handle hostname resolution |

122| `CLAUDE_CODE_REMOTE` | Set automatically to `true` when Claude Code is running as a [cloud session](/en/claude-code-on-the-web). Read this from a hook or setup script to detect whether you are in a cloud environment |

123| `CLAUDE_CODE_REMOTE_SESSION_ID` | Set automatically in [cloud sessions](/en/claude-code-on-the-web) to the current session's ID. Read this to construct a link back to the session transcript. See [Link artifacts back to the session](/en/claude-code-on-the-web#link-artifacts-back-to-the-session) |

120| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | Set to `1` to automatically resume if the previous session ended mid-turn. Used in SDK mode so the model continues without requiring the SDK to re-send the prompt |124| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | Set to `1` to automatically resume if the previous session ended mid-turn. Used in SDK mode so the model continues without requiring the SDK to re-send the prompt |

121| `CLAUDE_CODE_SCRIPT_CAPS` | JSON object limiting how many times specific scripts may be invoked per session when `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` is set. Keys are substrings matched against the command text; values are integer call limits. For example, `{"deploy.sh": 2}` allows `deploy.sh` to be called at most twice. Matching is substring-based so shell-expansion tricks like `./scripts/deploy.sh $(evil)` still count against the cap. Runtime fan-out via `xargs` or `find -exec` is not detected; this is a defense-in-depth control |125| `CLAUDE_CODE_SCRIPT_CAPS` | JSON object limiting how many times specific scripts may be invoked per session when `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` is set. Keys are substrings matched against the command text; values are integer call limits. For example, `{"deploy.sh": 2}` allows `deploy.sh` to be called at most twice. Matching is substring-based so shell-expansion tricks like `./scripts/deploy.sh $(evil)` still count against the cap. Runtime fan-out via `xargs` or `find -exec` is not detected; this is a defense-in-depth control |

122| `CLAUDE_CODE_SCROLL_SPEED` | Set the mouse wheel scroll multiplier in [fullscreen rendering](/en/fullscreen#adjust-wheel-scroll-speed). Accepts values from 1 to 20. Set to `3` to match `vim` if your terminal sends one wheel event per notch without amplification |126| `CLAUDE_CODE_SCROLL_SPEED` | Set the mouse wheel scroll multiplier in [fullscreen rendering](/en/fullscreen#mouse-wheel-scrolling). Accepts values from 1 to 20. Set to `3` to match `vim` if your terminal sends one wheel event per notch without amplification |

123| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | Override the time budget in milliseconds for [SessionEnd](/en/hooks#sessionend) hooks. Applies to session exit, `/clear`, and switching sessions via interactive `/resume`. By default the budget is 1.5 seconds, automatically raised to the highest per-hook `timeout` configured in settings files, up to 60 seconds. Timeouts on plugin-provided hooks do not raise the budget |127| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | Override the time budget in milliseconds for [SessionEnd](/en/hooks#sessionend) hooks. Applies to session exit, `/clear`, and switching sessions via interactive `/resume`. By default the budget is 1.5 seconds, automatically raised to the highest per-hook `timeout` configured in settings files, up to 60 seconds. Timeouts on plugin-provided hooks do not raise the budget |

124| `CLAUDE_CODE_SHELL` | Override automatic shell detection. Useful when your login shell differs from your preferred working shell (for example, `bash` vs `zsh`) |128| `CLAUDE_CODE_SHELL` | Override automatic shell detection. Useful when your login shell differs from your preferred working shell (for example, `bash` vs `zsh`) |

125| `CLAUDE_CODE_SHELL_PREFIX` | Command prefix to wrap all bash commands (for example, for logging or auditing). Example: `/path/to/logger.sh` will execute `/path/to/logger.sh <command>` |129| `CLAUDE_CODE_SHELL_PREFIX` | Command prefix to wrap all bash commands (for example, for logging or auditing). Example: `/path/to/logger.sh` will execute `/path/to/logger.sh <command>` |

126| `CLAUDE_CODE_SIMPLE` | Set to `1` to run with a minimal system prompt and only the Bash, file read, and file edit tools. MCP tools from `--mcp-config` are still available. Disables auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md. The [`--bare`](/en/headless#start-faster-with-bare-mode) CLI flag sets this |130| `CLAUDE_CODE_SIMPLE` | Set to `1` to run with a minimal system prompt and only the Bash, file read, and file edit tools. MCP tools from `--mcp-config` are still available. Disables auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md. The [`--bare`](/en/headless#start-faster-with-bare-mode) CLI flag sets this |

131| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | Set to `1` to use the minimal system prompt and collapsed tool descriptions from `CLAUDE_CODE_SIMPLE` without the other simple-mode changes. The full tool set, hooks, MCP servers, and CLAUDE.md discovery remain enabled |

128| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Skip Azure authentication for Microsoft Foundry (for example, when using an LLM gateway) |133| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Skip Azure authentication for Microsoft Foundry (for example, when using an LLM gateway) |

137| `CLAUDE_CODE_TASK_LIST_ID` | Share a task list across sessions. Set the same ID in multiple Claude Code instances to coordinate on a shared task list. See [Task list](/en/interactive-mode#task-list) |142| `CLAUDE_CODE_TASK_LIST_ID` | Share a task list across sessions. Set the same ID in multiple Claude Code instances to coordinate on a shared task list. See [Task list](/en/interactive-mode#task-list) |

138| `CLAUDE_CODE_TEAM_NAME` | Name of the agent team this teammate belongs to. Set automatically on [agent team](/en/agent-teams) members |143| `CLAUDE_CODE_TEAM_NAME` | Name of the agent team this teammate belongs to. Set automatically on [agent team](/en/agent-teams) members |

139| `CLAUDE_CODE_TMPDIR` | Override the temp directory used for internal temp files. Claude Code appends `/claude-{uid}/` (Unix) or `/claude/` (Windows) to this path. Default: `/tmp` on macOS, `os.tmpdir()` on Linux/Windows |144| `CLAUDE_CODE_TMPDIR` | Override the temp directory used for internal temp files. Claude Code appends `/claude-{uid}/` (Unix) or `/claude/` (Windows) to this path. Default: `/tmp` on macOS, `os.tmpdir()` on Linux/Windows |

145| `CLAUDE_CODE_TMUX_TRUECOLOR` | Set to `1` to allow 24-bit truecolor output inside tmux. By default, Claude Code clamps to 256 colors when `$TMUX` is set because tmux does not pass through truecolor escape sequences unless configured to. Set this after adding `set -ga terminal-overrides ',*:Tc'` to your `~/.tmux.conf`. See [Terminal configuration](/en/terminal-config) for other tmux settings |

143| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | Set to `1` to enable the PowerShell tool on Windows (opt-in preview). When enabled, Claude can run PowerShell commands natively instead of routing through Git Bash. Only supported on native Windows, not WSL. See [PowerShell tool](/en/tools-reference#powershell-tool) |149| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | Controls the PowerShell tool. On Windows, the tool is rolling out progressively: set to `1` to opt in or `0` to opt out. On Linux, macOS, and WSL, set to `1` to enable it, which requires `pwsh` on your `PATH`. When enabled on Windows, Claude can run PowerShell commands natively instead of routing through Git Bash. See [PowerShell tool](/en/tools-reference#powershell-tool) |

145| `CLAUDE_CONFIG_DIR` | Override the configuration directory (default: `~/.claude`). All settings, credentials, session history, and plugins are stored under this path. Useful for running multiple accounts side by side: for example, `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |151| `CLAUDE_CONFIG_DIR` | Override the configuration directory (default: `~/.claude`). All settings, credentials, session history, and plugins are stored under this path. Useful for running multiple accounts side by side: for example, `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |

146| `CLAUDE_ENABLE_BYTE_WATCHDOG` | Set to `1` to force-enable the byte-level streaming idle watchdog, or set to `0` to force-disable it. When unset, the watchdog is enabled by default for Anthropic API connections. The byte watchdog aborts a connection when no bytes arrive on the wire for the duration set by `CLAUDE_STREAM_IDLE_TIMEOUT_MS`, with a minimum of 5 minutes, independent of the event-level watchdog |152| `CLAUDE_ENABLE_BYTE_WATCHDOG` | Set to `1` to force-enable the byte-level streaming idle watchdog, or set to `0` to force-disable it. When unset, the watchdog is enabled by default for Anthropic API connections. The byte watchdog aborts a connection when no bytes arrive on the wire for the duration set by `CLAUDE_STREAM_IDLE_TIMEOUT_MS`, with a minimum of 5 minutes, independent of the event-level watchdog |

147| `CLAUDE_ENABLE_STREAM_WATCHDOG` | Set to `1` to enable the event-level streaming idle watchdog. Off by default. For Bedrock, Vertex, and Foundry, this is the only idle watchdog available. Configure the timeout with `CLAUDE_STREAM_IDLE_TIMEOUT_MS` |153| `CLAUDE_ENABLE_STREAM_WATCHDOG` | Set to `1` to enable the event-level streaming idle watchdog. Off by default. For Bedrock, Vertex, and Foundry, this is the only idle watchdog available. Configure the timeout with `CLAUDE_STREAM_IDLE_TIMEOUT_MS` |

148| `CLAUDE_ENV_FILE` | Path to a shell script that Claude Code sources before each Bash command. Use to persist virtualenv or conda activation across commands. Also populated dynamically by [SessionStart](/en/hooks#persist-environment-variables), [CwdChanged](/en/hooks#cwdchanged), and [FileChanged](/en/hooks#filechanged) hooks |154| `CLAUDE_ENV_FILE` | Path to a shell script whose contents Claude Code runs before each Bash command in the same shell process, so exports in the file are visible to the command. Use to persist virtualenv or conda activation across commands. Also populated dynamically by [SessionStart](/en/hooks#persist-environment-variables), [CwdChanged](/en/hooks#cwdchanged), and [FileChanged](/en/hooks#filechanged) hooks |

149| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | Prefix for auto-generated [Remote Control](/en/remote-control) session names when no explicit name is provided. Defaults to your machine's hostname, producing names like `myhost-graceful-unicorn`. The `--remote-control-session-name-prefix` CLI flag sets the same value for a single invocation |155| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | Prefix for auto-generated [Remote Control](/en/remote-control) session names when no explicit name is provided. Defaults to your machine's hostname, producing names like `myhost-graceful-unicorn`. The `--remote-control-session-name-prefix` CLI flag sets the same value for a single invocation |

150| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | Timeout in milliseconds before the streaming idle watchdog closes a stalled connection. For the byte-level watchdog on the Anthropic API: default and minimum `300000` (5 minutes); lower values are silently clamped to absorb extended thinking pauses and proxy buffering. For the event-level watchdog: default `90000` (90 seconds), no minimum. For third-party providers, requires `CLAUDE_ENABLE_STREAM_WATCHDOG=1` |156| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | Timeout in milliseconds before the streaming idle watchdog closes a stalled connection. For the byte-level watchdog on the Anthropic API: default and minimum `300000` (5 minutes); lower values are silently clamped to absorb extended thinking pauses and proxy buffering. For the event-level watchdog: default `90000` (90 seconds), no minimum. For third-party providers, requires `CLAUDE_ENABLE_STREAM_WATCHDOG=1` |

168| `DISABLE_TELEMETRY` | Set to `1` to opt out of Statsig telemetry (note that Statsig events do not include user data like code, file paths, or bash commands) |174| `DISABLE_TELEMETRY` | Set to `1` to opt out of Statsig telemetry (note that Statsig events do not include user data like code, file paths, or bash commands) |

170| `ENABLE_CLAUDEAI_MCP_SERVERS` | Set to `false` to disable [claude.ai MCP servers](/en/mcp#use-mcp-servers-from-claude-ai) in Claude Code. Enabled by default for logged-in users |176| `ENABLE_CLAUDEAI_MCP_SERVERS` | Set to `false` to disable [claude.ai MCP servers](/en/mcp#use-mcp-servers-from-claude-ai) in Claude Code. Enabled by default for logged-in users |

171| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | Set to `1` when using [Bedrock](/en/amazon-bedrock) to request a 1-hour prompt cache TTL instead of the default 5 minutes. Bedrock only |177| `ENABLE_PROMPT_CACHING_1H` | Set to `1` to request a 1-hour prompt cache TTL instead of the default 5 minutes. Intended for API key, [Bedrock](/en/amazon-bedrock), [Vertex](/en/google-vertex-ai), and [Foundry](/en/microsoft-foundry) users. Subscription users receive 1-hour TTL automatically. 1-hour cache writes are billed at a higher rate |

178| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | Deprecated. Use `ENABLE_PROMPT_CACHING_1H` instead |

172| `ENABLE_TOOL_SEARCH` | Controls [MCP tool search](/en/mcp#scale-with-mcp-tool-search). Unset: all MCP tools deferred by default, but loaded upfront when `ANTHROPIC_BASE_URL` points to a non-first-party host. Values: `true` (always defer including proxies), `auto` (threshold mode: load upfront if tools fit within 10% of context), `auto:N` (custom threshold, e.g., `auto:5` for 5%), `false` (load all upfront) |179| `ENABLE_TOOL_SEARCH` | Controls [MCP tool search](/en/mcp#scale-with-mcp-tool-search). Unset: all MCP tools deferred by default, but loaded upfront when `ANTHROPIC_BASE_URL` points to a non-first-party host. Values: `true` (always defer including proxies), `auto` (threshold mode: load upfront if tools fit within 10% of context), `auto:N` (custom threshold, e.g., `auto:5` for 5%), `false` (load all upfront) |

173| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | Set to any non-empty value to trigger fallback to [`--fallback-model`](/en/cli-reference#cli-flags) after repeated overload errors on any primary model. By default, only Opus models trigger the fallback |180| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | Set to any non-empty value to trigger fallback to [`--fallback-model`](/en/cli-reference#cli-flags) after repeated overload errors on any primary model. By default, only Opus models trigger the fallback |

174| `FORCE_AUTOUPDATE_PLUGINS` | Set to `1` to force plugin auto-updates even when the main auto-updater is disabled via `DISABLE_AUTOUPDATER` |181| `FORCE_AUTOUPDATE_PLUGINS` | Set to `1` to force plugin auto-updates even when the main auto-updater is disabled via `DISABLE_AUTOUPDATER` |

182| `FORCE_PROMPT_CACHING_5M` | Set to `1` to force the 5-minute prompt cache TTL even when 1-hour TTL would otherwise apply. Overrides `ENABLE_PROMPT_CACHING_1H` |

177| `IS_DEMO` | Set to `1` to enable demo mode: hides your email and organization name from the header and `/status` output, and skips onboarding. Useful when streaming or recording a session |185| `IS_DEMO` | Set to `1` to enable demo mode: hides your email and organization name from the header and `/status` output, and skips onboarding. Useful when streaming or recording a session |

178| `MAX_MCP_OUTPUT_TOKENS` | Maximum number of tokens allowed in MCP tool responses. Claude Code displays a warning when output exceeds 10,000 tokens. Tools that declare [`anthropic/maxResultSizeChars`](/en/mcp#raise-the-limit-for-a-specific-tool) use that character limit for text content instead, but image content from those tools is still subject to this variable (default: 25000) |186| `MAX_MCP_OUTPUT_TOKENS` | Maximum number of tokens allowed in MCP tool responses. Claude Code displays a warning when output exceeds 10,000 tokens. Tools that declare [`anthropic/maxResultSizeChars`](/en/mcp#raise-the-limit-for-a-specific-tool) use that character limit for text content instead, but image content from those tools is still subject to this variable (default: 25000) |

179| `MAX_STRUCTURED_OUTPUT_RETRIES` | Number of times to retry when the model's response fails validation against the [`--json-schema`](/en/cli-reference#cli-flags) in non-interactive mode (the `-p` flag). Defaults to 5 |187| `MAX_STRUCTURED_OUTPUT_RETRIES` | Number of times to retry when the model's response fails validation against the [`--json-schema`](/en/cli-reference#cli-flags) in non-interactive mode (the `-p` flag). Defaults to 5 |

180| `MAX_THINKING_TOKENS` | Override the [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) token budget. The ceiling is the model's [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) minus one. Set to `0` to disable thinking entirely. On models with adaptive reasoning (Opus 4.6, Sonnet 4.6), the budget is ignored unless adaptive reasoning is disabled via `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` |188| `MAX_THINKING_TOKENS` | Override the [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) token budget. The ceiling is the model's [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) minus one. Set to `0` to disable thinking entirely. On models with [adaptive reasoning](/en/model-config#adjust-effort-level), the budget is ignored unless adaptive reasoning is disabled via `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` |

181| `MCP_CLIENT_SECRET` | OAuth client secret for MCP servers that require [pre-configured credentials](/en/mcp#use-pre-configured-oauth-credentials). Avoids the interactive prompt when adding a server with `--client-secret` |189| `MCP_CLIENT_SECRET` | OAuth client secret for MCP servers that require [pre-configured credentials](/en/mcp#use-pre-configured-oauth-credentials). Avoids the interactive prompt when adding a server with `--client-secret` |

182| `MCP_CONNECTION_NONBLOCKING` | Set to `true` in non-interactive mode (`-p`) to skip the MCP connection wait entirely. Useful for scripted pipelines where MCP tools are not needed. Without this variable, the first query waits up to 5 seconds for `--mcp-config` server connections |190| `MCP_CONNECTION_NONBLOCKING` | Set to `true` in non-interactive mode (`-p`) to skip the MCP connection wait entirely. Useful for scripted pipelines where MCP tools are not needed. Without this variable, the first query waits up to 5 seconds for `--mcp-config` server connections |

183| `MCP_OAUTH_CALLBACK_PORT` | Fixed port for the OAuth redirect callback, as an alternative to `--callback-port` when adding an MCP server with [pre-configured credentials](/en/mcp#use-pre-configured-oauth-credentials) |191| `MCP_OAUTH_CALLBACK_PORT` | Fixed port for the OAuth redirect callback, as an alternative to `--callback-port` when adding an MCP server with [pre-configured credentials](/en/mcp#use-pre-configured-oauth-credentials) |

197| `OTEL_LOG_RAW_API_BODIES` | Emit Anthropic Messages API request and response JSON as `api_request_body` / `api_response_body` log events. Set to `1` for inline bodies truncated at 60 KB, or `file:<dir>` to write untruncated bodies to disk and emit a `body_ref` path instead. Disabled by default; bodies include the entire conversation history. See [Monitoring](/en/monitoring-usage#api-request-body-event) |

189| `OTEL_LOG_TOOL_CONTENT` | Set to `1` to include tool input and output content in OpenTelemetry span events. Disabled by default to protect sensitive data. See [Monitoring](/en/monitoring-usage) |198| `OTEL_LOG_TOOL_CONTENT` | Set to `1` to include tool input and output content in OpenTelemetry span events. Disabled by default to protect sensitive data. See [Monitoring](/en/monitoring-usage) |

190| `OTEL_LOG_TOOL_DETAILS` | Set to `1` to include tool input arguments, MCP server names, and tool details in OpenTelemetry traces and logs. Disabled by default to protect PII. See [Monitoring](/en/monitoring-usage) |199| `OTEL_LOG_TOOL_DETAILS` | Set to `1` to include tool input arguments, MCP server names, raw error strings on tool failures, and other tool details in OpenTelemetry traces and logs. Disabled by default to protect PII. See [Monitoring](/en/monitoring-usage) |

191| `OTEL_LOG_USER_PROMPTS` | Set to `1` to include user prompt text in OpenTelemetry traces and logs. Disabled by default (prompts are redacted). See [Monitoring](/en/monitoring-usage) |200| `OTEL_LOG_USER_PROMPTS` | Set to `1` to include user prompt text in OpenTelemetry traces and logs. Disabled by default (prompts are redacted). See [Monitoring](/en/monitoring-usage) |

192| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | Set to `false` to exclude account UUID from metrics attributes (default: included). See [Monitoring](/en/monitoring-usage) |201| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | Set to `false` to exclude account UUID from metrics attributes (default: included). See [Monitoring](/en/monitoring-usage) |

193| `OTEL_METRICS_INCLUDE_SESSION_ID` | Set to `false` to exclude session ID from metrics attributes (default: included). See [Monitoring](/en/monitoring-usage) |202| `OTEL_METRICS_INCLUDE_SESSION_ID` | Set to `false` to exclude session ID from metrics attributes (default: included). See [Monitoring](/en/monitoring-usage) |

217| `VERTEX_REGION_CLAUDE_4_7_OPUS` | {/* min-version: 2.1.111 */}Override region for Claude Opus 4.7 when using Vertex AI |

209 219

210Standard OpenTelemetry exporter variables (`OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_METRIC_EXPORT_INTERVAL`, `OTEL_RESOURCE_ATTRIBUTES`, and signal-specific variants) are also supported. See [Monitoring](/en/monitoring-usage) for configuration details.220Standard OpenTelemetry exporter variables (`OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_METRIC_EXPORT_INTERVAL`, `OTEL_RESOURCE_ATTRIBUTES`, and signal-specific variants) are also supported. See [Monitoring](/en/monitoring-usage) for configuration details.

errors.md +535 −0 added

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Error reference

7> Look up Claude Code runtime error messages with what each one means and how to fix it.

9This page lists runtime errors Claude Code displays and how to recover from each one, plus what to check when responses seem off without an error. For installation errors such as `command not found` or TLS failures during setup, see [Troubleshooting](/en/troubleshooting).

11These errors and recovery commands apply across the CLI, the [Desktop app](/en/desktop), and [Claude Code on the web](/en/claude-code-on-the-web), since all three wrap the same Claude Code CLI. For surface-specific issues, see the troubleshooting section on that surface's page.

13<Note>

14 Claude Code calls the Claude API for model responses, so most runtime errors map to an underlying API error code. This page covers what each error means inside Claude Code and how to recover. For the raw HTTP status code definitions, see the [Claude Platform error reference](https://platform.claude.com/docs/en/api/errors).

15</Note>

17## Find your error

19Match the message you see in your terminal to a section below.

21| Message | Section |

22| :----------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- |

23| `API Error: 500 ... Internal server error` | [Server errors](#api-error-500-internal-server-error) |

24| `API Error: Repeated 529 Overloaded errors` | [Server errors](#api-error-repeated-529-overloaded-errors) |

25| `Request timed out` | [Server errors](#request-timed-out), or [Network](#unable-to-connect-to-api) if the message mentions your internet connection |

26| `<model> is temporarily unavailable, so auto mode cannot determine the safety of...` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |

27| `You've hit your session limit` / `You've hit your weekly limit` | [Usage limits](#youve-hit-your-session-limit) |

28| `Server is temporarily limiting requests` | [Usage limits](#server-is-temporarily-limiting-requests) |

29| `Request rejected (429)` | [Usage limits](#request-rejected-429) |

30| `Credit balance is too low` | [Usage limits](#credit-balance-is-too-low) |

31| `Not logged in · Please run /login` | [Authentication](#not-logged-in) |

32| `Invalid API key` | [Authentication](#invalid-api-key) |

33| `This organization has been disabled` | [Authentication](#this-organization-has-been-disabled) |

34| `OAuth token revoked` / `OAuth token has expired` | [Authentication](#oauth-token-revoked-or-expired) |

35| `does not meet scope requirement user:profile` | [Authentication](#oauth-scope-requirement) |

36| `Unable to connect to API` | [Network](#unable-to-connect-to-api) |

37| `SSL certificate verification failed` | [Network](#ssl-certificate-errors) |

38| `Prompt is too long` | [Request errors](#prompt-is-too-long) |

39| `Error during compaction: Conversation too long` | [Request errors](#error-during-compaction-conversation-too-long) |

40| `Request too large` | [Request errors](#request-too-large) |

41| `Image was too large` | [Request errors](#image-was-too-large) |

42| `PDF too large` / `PDF is password protected` | [Request errors](#pdf-errors) |

43| `Extra inputs are not permitted` | [Request errors](#extra-inputs-are-not-permitted) |

44| `There's an issue with the selected model` | [Request errors](#theres-an-issue-with-the-selected-model) |

45| `Claude Opus is not available with the Claude Pro plan` | [Request errors](#claude-opus-is-not-available-with-the-claude-pro-plan) |

46| `thinking.type.enabled is not supported for this model` | [Request errors](#thinking-type-enabled-is-not-supported-for-this-model) |

47| `max_tokens must be greater than thinking.budget_tokens` | [Request errors](#thinking-budget-exceeds-output-limit) |

48| `API Error: 400 due to tool use concurrency issues` | [Request errors](#tool-use-or-thinking-block-mismatch) |

49| Responses seem lower quality than usual | [Response quality](#responses-seem-lower-quality-than-usual) |

51## Automatic retries

53Claude Code retries transient failures before showing you an error. Server errors, overloaded responses, request timeouts, temporary 429 throttles, and dropped connections are all retried up to 10 times with exponential backoff. While retrying, the spinner shows a `Retrying in Ns · attempt x/y` countdown.

55When you see one of the errors on this page, those retries have already been exhausted. You can tune the behavior with two environment variables:

57| Variable | Default | Effect |

58| :---------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------- |

59| [`CLAUDE_CODE_MAX_RETRIES`](/en/env-vars) | 10 | Number of retry attempts. Lower it to surface failures faster in scripts; raise it to wait through longer incidents. |

60| [`API_TIMEOUT_MS`](/en/env-vars) | 600000 | Per-request timeout in milliseconds. Raise it for slow networks or proxies. |

62## Server errors

64These errors come from Anthropic infrastructure rather than your account or request.

66### API Error: 500 Internal server error

68Claude Code shows the raw API response body for any 5xx status. The example below shows a 500 response:

70```text theme={null}

71API Error: 500 {"type":"error","error":{"type":"api_error","message":"Internal server error"}} · check status.claude.com

72```

74This indicates an unexpected failure inside the API. It is not caused by your prompt, settings, or account.

76**What to do:**

78* Check [status.claude.com](https://status.claude.com) for active incidents

79* Wait a minute, then send your message again. Your original message is still in the conversation, so for a long prompt you can type `try again` instead of pasting the whole thing.

80* If the error persists with no posted incident, run `/feedback` so Anthropic can investigate with your request details. See [Report an error](#report-an-error) if `/feedback` is unavailable on your provider.

82### API Error: Repeated 529 Overloaded errors

84The API is temporarily at capacity across all users. Claude Code has already retried several times before showing this message:

86```text theme={null}

87API Error: Repeated 529 Overloaded errors · check status.claude.com

88```

90A 529 is not your usage limit and does not count against your quota.

92**What to do:**

94* Check [status.claude.com](https://status.claude.com) for capacity notices

95* Try again in a few minutes

96* Run `/model` and switch to a different model to keep working, since capacity is tracked per model. Claude Code prompts you to do this when one model is under particularly high load, for example `Opus is experiencing high load, please use /model to switch to Sonnet`.

98### Request timed out

100The API did not respond before the connection deadline.

101

102```text theme={null}

103Request timed out

104```

105

106This can happen during periods of high load or when a very large response is being generated. The default request timeout is 10 minutes.

107

108**What to do:**

109

110* Retry the request

111* For long-running tasks, break the work into smaller prompts

112* If a slow network or proxy is the cause, raise `API_TIMEOUT_MS` as described in [Automatic retries](#automatic-retries)

113* If timeouts are frequent and your network is otherwise healthy, see [Network and connection errors](#network-and-connection-errors) below

114

115### Auto mode cannot determine the safety of an action

116

117The model that [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) uses to classify actions is overloaded, so auto mode blocked the action instead of approving it unchecked.

118

119```text theme={null}

120<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait briefly and then try this action again.

121```

122

123Reads, searches, and edits inside your working directory skip the classifier, so they keep working during the outage.

124

125**What to do:**

126

127* Retry after a few seconds; Claude sees the same message and usually retries on its own

128* If retries keep failing, continue with read-only tasks and come back to the blocked action later

129* This is transient and unrelated to [auto mode eligibility](/en/permission-modes#eliminate-prompts-with-auto-mode); you do not need to change settings

130

131## Usage limits

132

133These errors mean a quota tied to your account or plan has been reached. They are distinct from [server errors](#server-errors), which affect everyone.

134

135### You've hit your session limit

136

137Subscription plans include a rolling usage allowance. When it runs out you see one of these messages:

138

139```text theme={null}

140You've hit your session limit · resets 3:45pm

141You've hit your weekly limit · resets Mon 12:00am

142You've hit your Opus limit · resets 3:45pm

143```

144

145Claude Code blocks further requests until the reset time shown in the message.

146

147**What to do:**

148

149* Wait for the reset time shown in the error

150* Run `/usage` to see your plan limits and when they reset

151* Run `/extra-usage` to buy additional usage on Pro and Max, or to request it from your admin on Team and Enterprise. See [Extra usage for paid plans](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) for how this is billed.

152* To upgrade your plan for higher base limits, see [claude.com/pricing](https://claude.com/pricing)

153

154To watch your remaining allowance before you hit the limit, add the `rate_limits` fields to a [custom status line](/en/statusline#rate-limit-usage), or in the Desktop app click the [usage ring](/en/desktop#check-usage) next to the model picker.

155

156### Server is temporarily limiting requests

157

158The API applied a short-lived throttle that is unrelated to your plan quota.

159

160```text theme={null}

161API Error: Server is temporarily limiting requests (not your usage limit)

162```

163

164This is [retried automatically](#automatic-retries) before being shown.

165

166**What to do:**

167

168* Wait briefly and try again

169* Check [status.claude.com](https://status.claude.com) if it persists

170

171### Request rejected (429)

172

173You have hit the rate limit configured for your API key, Amazon Bedrock project, or Google Vertex AI project.

174

175```text theme={null}

176API Error: Request rejected (429) · this may be a temporary capacity issue

177```

178

179**What to do:**

180

181* Run `/status` and confirm the active credential is the one you expect. A stray `ANTHROPIC_API_KEY` in your environment can route requests through a low-tier key instead of your subscription.

182* Check your provider console for the active limits and request a higher tier if needed

183* For Anthropic API keys, see the [rate limits reference](https://platform.claude.com/docs/en/api/rate-limits) for how tiers work and how to set per-workspace caps

184* Reduce concurrency: lower [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/en/env-vars), avoid running many parallel subagents, or switch to a smaller model with `/model` for high-volume scripted runs

185

186### Credit balance is too low

187

188Your Console organization has run out of prepaid credits.

189

190```text theme={null}

191Credit balance is too low

192```

193

194**What to do:**

195

196* Add credits at [platform.claude.com/settings/billing](https://platform.claude.com/settings/billing), and consider enabling auto-reload there so the balance refills before it hits zero

197* Switch to subscription authentication with `/login` if you have a Pro, Max, Team, or Enterprise plan

198* Set per-workspace spend caps in the Console to prevent a single project from draining the org balance. See [Manage costs effectively](/en/costs).

199

200## Authentication errors

201

202These errors mean Claude Code cannot prove who you are to the API. Run `/status` at any time to see which credential is currently active.

203

204### Not logged in

205

206No valid credential is available for this session.

207

208```text theme={null}

209Not logged in · Please run /login

210```

211

212**What to do:**

213

214* Run `/login` to authenticate with your Claude subscription or Console account

215* If you expected an environment variable to authenticate you, confirm `ANTHROPIC_API_KEY` is set and exported in the shell where you launched `claude`

216* For CI or automation where interactive login is not possible, configure an [`apiKeyHelper`](/en/settings#available-settings) script that fetches a key at startup

217* See [Authentication precedence](/en/authentication#authentication-precedence) to understand which credential wins when several are present

218

219If you are prompted to log in repeatedly, see [Not logged in or token expired](/en/troubleshooting#not-logged-in-or-token-expired) for system clock and macOS Keychain fixes.

220

221### Invalid API key

222

223The `ANTHROPIC_API_KEY` environment variable or `apiKeyHelper` script returned a key the API rejected.

224

225```text theme={null}

226Invalid API key · Fix external API key

227```

228

229**What to do:**

230

231* Check for typos and confirm the key has not been revoked in the [Console](https://platform.claude.com/settings/keys)

232* Run `env | grep ANTHROPIC` in the same shell. Tools like direnv, dotenv shell plugins, and IDE terminals can load a stale key from a `.env` file in your project without you setting it explicitly.

233* Unset `ANTHROPIC_API_KEY` and run `/login` to use subscription auth instead

234* If the key comes from an [`apiKeyHelper`](/en/settings#available-settings) script, run the script directly to confirm it prints a valid key on stdout

235* Run `/status` to confirm which credential source Claude Code is actually using

236

237### This organization has been disabled

238

239A stale `ANTHROPIC_API_KEY` from a disabled Console organization is overriding your subscription login.

240

241```text theme={null}

242Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your other credentials

243API Error: 400 ... This organization has been disabled.

244```

245

246Environment variables take precedence over `/login`, so a key exported in your shell profile or loaded from a `.env` file is used even when you have a working Pro or Max subscription. In non-interactive mode (`-p`), the key is always used when present.

247

248**What to do:**

249

250* Unset `ANTHROPIC_API_KEY` in the current shell and remove it from your shell profile, then relaunch `claude`

251* Run `/status` afterward to confirm the active credential is your subscription

252* If no environment variable is set and the error persists, the disabled organization is the one tied to your `/login`. Contact support or sign in with a different account.

253

254### OAuth token revoked or expired

255

256Your saved login is no longer valid. A revoked token means you signed out everywhere or an admin removed access; an expired token means the automatic refresh failed mid-session.

257

258```text theme={null}

259OAuth token revoked · Please run /login

260OAuth token has expired · Please run /login

261API Error: 401 ... authentication_error

262```

263

264**What to do:**

265

266* Run `/login` to sign in again

267* If the error returns within the same session after re-authenticating, run `/logout` first to fully clear the stored token, then `/login`

268* For repeated prompts to log in across launches, see the system clock and macOS Keychain checks in [Troubleshooting](/en/troubleshooting#not-logged-in-or-token-expired)

269* For other failures including `403 Forbidden` and OAuth browser issues, see [Permissions and authentication](/en/troubleshooting#permissions-and-authentication)

270

271### OAuth scope requirement

272

273The stored token predates a permission scope that a newer feature needs. You see this most often from `/usage` and the status line usage indicator:

274

275```text theme={null}

276OAuth token does not meet scope requirement: user:profile

277```

278

279**What to do:**

280

281* Run `/login` to mint a new token with the current scopes. You do not need to log out first.

282

283## Network and connection errors

284

285These errors mean Claude Code could not reach the API at all. They almost always originate in your local network, proxy, or firewall rather than Anthropic infrastructure.

286

287### Unable to connect to API

288

289The TCP connection to the API failed or never completed.

290

291```text theme={null}

292Unable to connect to API. Check your internet connection

293Unable to connect to API (ECONNREFUSED)

294Unable to connect to API (ECONNRESET)

295Unable to connect to API (ETIMEDOUT)

296fetch failed

297Request timed out. Check your internet connection and proxy settings

298```

299

300Common causes include no internet access, a VPN that blocks `api.anthropic.com`, or a required corporate proxy that is not configured.

301

302**What to do:**

303

304* Confirm you can reach the API host from the same shell by running `curl -I https://api.anthropic.com`. On Windows PowerShell use `curl.exe -I https://api.anthropic.com` so the built-in `Invoke-WebRequest` alias is not used.

305* If you are behind a corporate proxy, set `HTTPS_PROXY` before launching Claude Code and see [Network configuration](/en/network-config)

306* If you route through an LLM gateway or relay, set [`ANTHROPIC_BASE_URL`](/en/env-vars) to its address. See [LLM gateway configuration](/en/llm-gateway) for setup.

307* Ensure your firewall allows the hosts listed in [Network access requirements](/en/network-config#network-access-requirements)

308* Intermittent failures are [retried automatically](#automatic-retries); persistent failures point to a local network issue

309

310If `curl` succeeds but Claude Code still fails, the cause is usually something between Node.js and the network rather than the network itself:

311

312* On Linux and WSL, check `/etc/resolv.conf` for an unreachable nameserver. WSL in particular can inherit a broken resolver from the host.

313* On macOS, a VPN client that was disconnected or uninstalled can leave a tunnel interface or routing rule behind. Check `ifconfig` for stale `utun` interfaces and remove the VPN's network extension in System Settings.

314* Docker Desktop and similar container runtimes can intercept outbound traffic. Quit them and retry to rule this out.

315

316### SSL certificate errors

317

318A proxy or security appliance on your network is intercepting TLS traffic with its own certificate, and Node.js does not trust it.

319

320```text theme={null}

321Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates

322Unable to connect to API: Self-signed certificate detected

323```

324

325**What to do:**

326

327* Export your organization's CA bundle and point Node at it with `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem`

328* See [Network configuration](/en/network-config#custom-ca-certificates) for full setup instructions

329* Do not set `NODE_TLS_REJECT_UNAUTHORIZED=0`, which disables certificate validation entirely

330

331## Request errors

332

333These errors mean the API received your request but rejected its content.

334

335### Prompt is too long

336

337The conversation plus attached files exceeds the model's context window.

338

339```text theme={null}

340Prompt is too long

341```

342

343**What to do:**

344

345* Run `/compact` to summarize earlier turns and free space, or `/clear` to start fresh

346* Run `/context` to see a breakdown of what is consuming the window: system prompt, tools, memory files, and messages

347* Disable MCP servers you are not using with `/mcp disable <name>` to remove their tool definitions from context

348* Trim large `CLAUDE.md` memory files or split them into [imports](/en/memory)

349* Subagents inherit every MCP tool definition from the parent session, which can fill their context window before the first turn. Disable MCP servers you are not using before spawning subagents.

350* Auto-compact is on by default and normally prevents this error. If you have set [`DISABLE_AUTO_COMPACT`](/en/env-vars), re-enable it or run `/compact` manually before the window fills.

351

352See [Explore the context window](/en/context-window) for an interactive view of how context fills up.

353

354### Error during compaction: Conversation too long

355

356`/compact` itself failed because there is not enough free context to hold the summary it produces.

357

358```text theme={null}

359Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.

360```

361

362This can happen when the window is already full at the moment auto-compact triggers, or when you run `/compact` after seeing `Prompt is too long`.

363

364**What to do:**

365

366* Press Esc twice to open the message list and step back several turns. This drops the most recent messages from context. Then run `/compact` again.

367* If stepping back does not free enough space, run `/clear` to start a fresh session. Your previous conversation is preserved and can be reopened with `/resume`.

368

369### Request too large

370

371The raw request body exceeded the API's byte limit before tokenization, usually because of a large pasted file or attachment.

372

373```text theme={null}

374Request too large (max 30 MB). Double press esc to go back and remove or shrink the attached content.

375```

376

377This is a size limit on the HTTP request, separate from the [context window limit](#prompt-is-too-long).

378

379**What to do:**

380

381* Press Esc twice and step back past the turn that added the oversized content

382* Reference large files by path instead of pasting their contents, so Claude can read them in chunks

383* For images, see [Image was too large](#image-was-too-large) below

384

385### Image was too large

386

387A pasted or attached image exceeds the API's size or dimension limits.

388

389```text theme={null}

390Image was too large. Double press esc to go back and try again with a smaller image.

391API Error: 400 ... image dimensions exceed max allowed size

392```

393

394The image stays in conversation history after the error, so every subsequent message fails with the same error until you remove it.

395

396**What to do:**

397

398* Press Esc twice and step back past the turn where the image was added

399* Resize the image before pasting. The API accepts images up to 8000 pixels on the longest edge for a single image, or 2000 pixels when many images are in context.

400* Take a tighter screenshot of the relevant region instead of the full screen

401

402### PDF errors

403

404The PDF you attached could not be processed.

405

406```text theme={null}

407PDF too large (max 100 pages, 32 MB). Try splitting it or extracting text first.

408PDF is password protected. Try removing protection or extracting text first.

409The PDF file was not valid. Try converting to a different format first.

410```

411

412**What to do:**

413

414* For oversized PDFs, ask Claude to read a page range with the Read tool instead of attaching the whole file, or extract text with a tool like `pdftotext` and reference the output file by path

415* For protected or invalid PDFs, remove the password or re-export the file from its source application, then try again

416

417### Extra inputs are not permitted

418

419A proxy or LLM gateway between Claude Code and the API stripped the `anthropic-beta` request header, so the API rejected fields that depend on it.

420

421```text theme={null}

422API Error: 400 ... Extra inputs are not permitted ... context_management

423API Error: 400 ... Extra inputs are not permitted ... tools.0.custom.input_examples

424API Error: 400 ... Unexpected value(s) for the `anthropic-beta` header

425```

426

427Claude Code sends beta-only fields such as `context_management`, `effort`, and tool `input_examples` alongside an `anthropic-beta` header that enables them. When a gateway forwards the body but drops the header, the API sees fields it does not recognize.

428

429**What to do:**

430

431* Configure your gateway to forward the `anthropic-beta` header. See [LLM gateway configuration](/en/llm-gateway).

432* As a fallback, set [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/en/env-vars) before launching. This disables features that require the beta header so requests succeed through a gateway that cannot forward it.

433

434### There's an issue with the selected model

435

436The configured model name was not recognized or your account lacks access to it.

437

438```text theme={null}

439There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to select a different one.

440```

441

442**What to do:**

443

444* Run `/model` to pick from models available to your account

445* Use an alias such as `sonnet` or `opus` instead of a full versioned ID. Aliases track the latest release so they do not go stale. See [Model configuration](/en/model-config).

446* See [Model not found](/en/troubleshooting#model-not-found-or-not-accessible) to locate where a stale ID is set across `--model`, `ANTHROPIC_MODEL`, and settings files

447

448### Claude Opus is not available with the Claude Pro plan

449

450Your active subscription plan does not include the model you selected.

451

452```text theme={null}

453Claude Opus is not available with the Claude Pro plan · Select a different model in /model

454```

455

456**What to do:**

457

458* Run `/model` and select a model your plan includes

459* If you upgraded your plan recently and still see this, run `/logout` then `/login`. The stored token reflects your plan at the time you signed in, so upgrading on the web does not take effect in an existing session until you re-authenticate.

460* See [claude.com/pricing](https://claude.com/pricing) for which models each plan includes

461

462### thinking.type.enabled is not supported for this model

463

464Your Claude Code version is older than the minimum for Opus 4.7. The CLI sent a thinking configuration the model no longer accepts.

465

466```text theme={null}

467API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

468```

469

470**What to do:**

471

472* Run `claude update` to upgrade to v2.1.111 or later, then restart Claude Code

473* If you cannot upgrade, run `/model` and select Opus 4.6 or Sonnet instead

474* If you hit this in the Agent SDK, see [SDK troubleshooting](/en/agent-sdk/quickstart#troubleshooting)

475

476### Thinking budget exceeds output limit

477

478The configured extended thinking budget exceeds the maximum response length, so there is no room left for the actual answer.

479

480```text theme={null}

481API Error: 400 ... max_tokens must be greater than thinking.budget_tokens

482```

483

484Claude Code adjusts these values automatically on the Anthropic API. You typically see this error on Amazon Bedrock or Google Vertex AI when [`MAX_THINKING_TOKENS`](/en/env-vars) is set higher than the provider's output limit, or when plan mode raises the thinking budget.

485

486**What to do:**

487

488* Lower `MAX_THINKING_TOKENS`, or raise [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/en/env-vars) above the thinking budget

489* See [Extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) for how the budget interacts with output length

490

491### Tool use or thinking block mismatch

492

493The conversation history reached the API in an inconsistent state, usually after a tool call was interrupted or a turn was edited mid-stream.

494

495```text theme={null}

496API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.

497API Error: 400 ... unexpected `tool_use_id` found in `tool_result` blocks

498API Error: 400 ... thinking blocks ... cannot be modified

499```

500

501All three variants mean the same thing: the sequence of `tool_use`, `tool_result`, and `thinking` blocks in history no longer matches what the API expects.

502

503**What to do:**

504

505* Run `/rewind`, or press Esc twice, to step back to a checkpoint before the corrupted turn and continue from there. See [Checkpointing](/en/checkpointing) for how checkpoints are created and restored.

506

507## Responses seem lower quality than usual

508

509If Claude's answers seem less capable than you expect but no error is shown, the cause is usually conversation state rather than the model itself. Claude Code does not silently change model versions. It can switch to a fallback model in specific cases such as an Opus quota being reached or a Bedrock or Vertex AI region lacking your model; the Model selection check below catches both, and [Model configuration](/en/model-config) explains when fallback applies.

510

511Check these first:

512

513* **Model selection**: run `/model` to confirm you are on the model you expect. A previous `/model` choice or an `ANTHROPIC_MODEL` environment variable may have you on a smaller model than you intended.

514* **Effort level**: run `/effort` to check the current reasoning level and raise it for hard debugging or design work. Defaults vary by model and plan, so check before assuming you are below the maximum. See [Adjust effort level](/en/model-config#adjust-effort-level) for per-model defaults and the `ultrathink` shortcut.

515* **Context pressure**: run `/context` to see how full the window is. If it is near capacity, run `/compact` at a natural breakpoint or `/clear` to start fresh. See [Explore the context window](/en/context-window) for how auto-compact affects earlier turns.

516* **Stale instructions**: large or outdated `CLAUDE.md` files and MCP tool definitions consume context and can steer responses. `/doctor` flags oversized memory files and subagent definitions; `/context` shows MCP tool token usage.

517

518When a response goes wrong, rewinding usually works better than replying with corrections. Press Esc twice or run `/rewind` to step back to before the bad turn, then rephrase the prompt with more specifics. Correcting in-thread keeps the wrong attempt in context, which can anchor later answers to it. See [Checkpointing](/en/checkpointing).

519

520If quality still seems off after checking the above, run `/feedback` and describe what you expected versus what you got. Feedback submitted this way includes the conversation transcript, which is the fastest way for Anthropic to diagnose a real regression. See [Report an error](#report-an-error) if `/feedback` is unavailable on your provider.

521

522## Report an error

523

524This page covers errors from the Claude API. For errors from other Claude Code components, see the relevant guide:

525

526* MCP server failed to connect or authenticate: [MCP](/en/mcp)

527* Hook script failed or blocked a tool: [Debug hooks](/en/hooks#debug-hooks)

528* Permission denied or filesystem errors during install: [Troubleshooting](/en/troubleshooting)

529

530If an error is not listed here or the suggested fix does not help:

531

532* Run `/feedback` inside Claude Code to send the transcript and a description to Anthropic. The command also offers to open a prefilled GitHub issue. Feedback is unavailable on Bedrock, Vertex AI, and Foundry deployments.

533* Run `/doctor` to check for local configuration problems

534* Check [status.claude.com](https://status.claude.com) for active incidents

535* Search [existing issues](https://github.com/anthropics/claude-code/issues) on GitHub

fast-mode.md +1 −1

Details

12 12

13Fast mode is a high-speed configuration for Claude Opus 4.6, making the model 2.5x faster at a higher cost per token. Toggle it on with `/fast` when you need speed for interactive work like rapid iteration or live debugging, and toggle it off when cost matters more than latency.13Fast mode is a high-speed configuration for Claude Opus 4.6, making the model 2.5x faster at a higher cost per token. Toggle it on with `/fast` when you need speed for interactive work like rapid iteration or live debugging, and toggle it off when cost matters more than latency.

14 14

15Fast mode is not a different model. It uses the same Opus 4.6 with a different API configuration that prioritizes speed over cost efficiency. You get identical quality and capabilities, just faster responses.15Fast mode is not a different model. It uses the same Opus 4.6 with a different API configuration that prioritizes speed over cost efficiency. You get identical quality and capabilities, just faster responses. Fast mode is not available on Opus 4.7 or other models.

16 16

17<Note>17<Note>

18 Fast mode requires Claude Code v2.1.36 or later. Check your version with `claude --version`.18 Fast mode requires Claude Code v2.1.36 or later. Check your version with `claude --version`.

fullscreen.md +19 −16

Details

7> Enable a smoother, flicker-free rendering mode with mouse support and stable memory usage in long conversations.7> Enable a smoother, flicker-free rendering mode with mouse support and stable memory usage in long conversations.

8 8

9<Note>9<Note>

~~10 Fullscreen rendering is an opt-in [research preview](#research-preview) and requires Claude Code v2.1.89 or later. Enable it with `CLAUDE_CODE_NO_FLICKER=1`. Behavior may change based on feedback.~~10 Fullscreen rendering is an opt-in [research preview](#research-preview) and requires Claude Code v2.1.89 or later. Run `/tui fullscreen` to switch in your current conversation, or set `CLAUDE_CODE_NO_FLICKER=1` on versions before v2.1.110. Behavior may change based on feedback.

11</Note>11</Note>

12 12

13Fullscreen rendering is an alternative rendering path for the Claude Code CLI that eliminates flicker, keeps memory usage flat in long conversations, and adds mouse support. It draws the interface on the terminal's alternate screen buffer, like `vim` or `htop`, and only renders messages that are currently visible. This reduces the amount of data sent to your terminal on each update.13Fullscreen rendering is an alternative rendering path for the Claude Code CLI that eliminates flicker, keeps memory usage flat in long conversations, and adds mouse support. It draws the interface on the terminal's alternate screen buffer, like `vim` or `htop`, and only renders messages that are currently visible. This reduces the amount of data sent to your terminal on each update.

20 20

21## Enable fullscreen rendering21## Enable fullscreen rendering

22 22

~~23Set the `CLAUDE_CODE_NO_FLICKER` environment variable when starting Claude Code:~~23Run `/tui fullscreen` inside any Claude Code conversation. The CLI saves the [`tui` setting](/en/settings#available-settings) and relaunches into fullscreen with your conversation intact, so you can switch mid-session without losing context. Run `/tui` with no argument to print which renderer is active.

25You can also set the `CLAUDE_CODE_NO_FLICKER` environment variable before starting Claude Code:

24 26

25```bash theme={null}27```bash theme={null}

26CLAUDE_CODE_NO_FLICKER=1 claude28CLAUDE_CODE_NO_FLICKER=1 claude

27```29```

28 30

~~29To enable it for every session, export the variable in your shell profile such as `~/.zshrc` or `~/.bashrc`:~~31The `tui` setting and the environment variable are equivalent. The `/tui` command clears `CLAUDE_CODE_NO_FLICKER` from the relaunched process so the setting it writes takes effect.

~~31```bash theme={null}~~

~~32export CLAUDE_CODE_NO_FLICKER=1~~

~~33```~~

34 32

35## What changes33## What changes

36 34

39Because the conversation lives in the alternate screen buffer instead of your terminal's scrollback, a few things work differently:37Because the conversation lives in the alternate screen buffer instead of your terminal's scrollback, a few things work differently:

40 38

41| Before | Now | Details |39| Before | Now | Details |

42| :-------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ |40| :-------------------------------------------------- | :----------------------------------------------------------------------------- | :------------------------------------------------------------------------ |

43| `Cmd+f` or tmux search to find text | `Ctrl+o` once for transcript mode (then `/` to search or `[` to write to scrollback), or `Ctrl+o` twice for focus view (last prompt + tool summary + response) | [Search and review the conversation](#search-and-review-the-conversation) |41| `Cmd+f` or tmux search to find text | `Ctrl+o` for transcript mode, then `/` to search or `[` to write to scrollback | [Search and review the conversation](#search-and-review-the-conversation) |

46 44

58 56

59Selected text copies to your clipboard automatically on mouse release. To turn this off, toggle Copy on select in `/config`. With it off, press `Ctrl+Shift+c` to copy manually. On terminals that support the kitty keyboard protocol, such as kitty, WezTerm, Ghostty, and iTerm2, `Cmd+c` also works. If you have a selection active, `Ctrl+c` copies instead of cancelling.57Selected text copies to your clipboard automatically on mouse release. To turn this off, toggle Copy on select in `/config`. With it off, press `Ctrl+Shift+c` to copy manually. On terminals that support the kitty keyboard protocol, such as kitty, WezTerm, Ghostty, and iTerm2, `Cmd+c` also works. If you have a selection active, `Ctrl+c` copies instead of cancelling.

60 58

59With a selection active, hold `Shift` and press the arrow keys to extend it from the keyboard. `Shift+↑` and `Shift+↓` scroll the viewport when the selection reaches the top or bottom edge. `Shift+Home` and `Shift+End` extend to the start or end of the current line.

61## Scroll the conversation61## Scroll the conversation

62 62

63Fullscreen rendering handles scrolling inside the app. Use these shortcuts to navigate:63Fullscreen rendering handles scrolling inside the app. Use these shortcuts to navigate:

71 71

72On keyboards without dedicated `PgUp`, `PgDn`, `Home`, or `End` keys, like MacBook keyboards, hold `Fn` with the arrow keys: `Fn+↑` sends `PgUp`, `Fn+↓` sends `PgDn`, `Fn+←` sends `Home`, and `Fn+→` sends `End`. That makes `Ctrl+Fn+→` the jump-to-bottom shortcut. If that feels awkward, scroll to the bottom with the mouse wheel to resume following, or rebind `scroll:bottom` to something reachable.72On keyboards without dedicated `PgUp`, `PgDn`, `Home`, or `End` keys, like MacBook keyboards, hold `Fn` with the arrow keys: `Fn+↑` sends `PgUp`, `Fn+↓` sends `PgDn`, `Fn+←` sends `Home`, and `Fn+→` sends `End`. That makes `Ctrl+Fn+→` the jump-to-bottom shortcut. If that feels awkward, scroll to the bottom with the mouse wheel to resume following, or rebind `scroll:bottom` to something reachable.

73 73

74These actions are rebindable. See [Scroll actions](/en/keybindings#scroll-actions) for the full list of action names, including half-page and full-page variants that have no default binding.

76### Auto-follow

74Scrolling up pauses auto-follow so new output does not pull you back to the bottom. Press `Ctrl+End` or scroll to the bottom to resume following.78Scrolling up pauses auto-follow so new output does not pull you back to the bottom. Press `Ctrl+End` or scroll to the bottom to resume following.

75 79

~~76These actions are rebindable. See [Scroll actions](/en/keybindings#scroll-actions) for the full list of action names, including half-page and full-page variants that have no default binding.~~80To turn auto-follow off entirely so the view stays where you leave it, open `/config` and set Auto-scroll to off. With auto-scroll disabled, the view never jumps to the bottom on its own. Permission prompts and other dialogs that need a response still scroll into view regardless of this setting.

77 81

78Mouse wheel scrolling requires your terminal to forward mouse events to Claude Code. Most terminals do this whenever an application requests it. iTerm2 makes it a per-profile setting: if the wheel does nothing but `PgUp` and `PgDn` work, open Settings → Profiles → Terminal and turn on Enable mouse reporting. The same setting is also required for click-to-expand and text selection to work.82### Mouse wheel scrolling

79 83

~~80### Adjust wheel scroll speed~~84Mouse wheel scrolling requires your terminal to forward mouse events to Claude Code. Most terminals do this whenever an application requests it. iTerm2 makes it a per-profile setting: if the wheel does nothing but `PgUp` and `PgDn` work, open Settings → Profiles → Terminal and turn on Enable mouse reporting. The same setting is also required for click-to-expand and text selection to work.

81 85

82If mouse wheel scrolling feels slow, your terminal may be sending one scroll event per physical notch with no multiplier. Some terminals, like Ghostty and iTerm2 with faster scrolling enabled, already amplify wheel events. Others, including the VS Code integrated terminal, send exactly one event per notch. Claude Code cannot detect which.86If mouse wheel scrolling feels slow, your terminal may be sending one scroll event per physical notch with no multiplier. Some terminals, like Ghostty and iTerm2 with faster scrolling enabled, already amplify wheel events. Others, including the VS Code integrated terminal, send exactly one event per notch. Claude Code cannot detect which.

83 87

91 95

92## Search and review the conversation96## Search and review the conversation

93 97

94In fullscreen rendering, `Ctrl+o` cycles through three states: normal prompt, transcript mode, and focus view. Press it once to enter transcript mode, press it again to return to a focus view showing just your last prompt, a one-line summary of tool calls with edit diffstats, and the final response. Press it a third time to return to the normal prompt screen.98`Ctrl+o` toggles between the normal prompt and transcript mode. For a quieter view that shows only your last prompt, a one-line summary of tool calls with edit diffstats, and the final response, run `/focus`. The setting persists across sessions. Run `/focus` again to turn it off.

95 99

96Transcript mode gains `less`-style navigation and search:100Transcript mode gains `less`-style navigation and search:

97 101

107| `Esc` or `q` | Exit transcript mode and return to the prompt |

108 111

109Your terminal's `Cmd+f` and tmux search don't see the conversation because it lives in the alternate screen buffer, not the native scrollback. To hand the content back to your terminal, press `Ctrl+o` to enter transcript mode first, then:112Your terminal's `Cmd+f` and tmux search don't see the conversation because it lives in the alternate screen buffer, not the native scrollback. To hand the content back to your terminal, press `Ctrl+o` to enter transcript mode first, then:

110 113

147 150

148If you encounter a problem, run `/feedback` inside Claude Code to report it, or open an issue on the [claude-code GitHub repo](https://github.com/anthropics/claude-code/issues). Include your terminal emulator name and version.151If you encounter a problem, run `/feedback` inside Claude Code to report it, or open an issue on the [claude-code GitHub repo](https://github.com/anthropics/claude-code/issues). Include your terminal emulator name and version.

149 152

150To turn fullscreen rendering off, unset the environment variable or set `CLAUDE_CODE_NO_FLICKER=0`.153To turn fullscreen rendering off, run `/tui default`, or unset the environment variable if you enabled it that way.

github-actions.md +1 −1

Details

13</Note>13</Note>

14 14

15<Info>15<Info>

~~16 **Claude Opus 4.6 is now available.** Claude Code GitHub Actions default to Sonnet. To use Opus 4.6, configure the [model parameter](#breaking-changes-reference) to use `claude-opus-4-6`.~~16 **Claude Opus 4.7 is now available.** Claude Code GitHub Actions default to Sonnet. To use Opus 4.7, configure the [model parameter](#breaking-changes-reference) to use `claude-opus-4-7`.

17</Info>17</Info>

18 18

19## Why use Claude Code GitHub Actions?19## Why use Claude Code GitHub Actions?

google-vertex-ai.md +7 −5

Details

120 Pin specific model versions when deploying to multiple users. Without pinning, model aliases such as `sonnet` and `opus` resolve to the latest version, which may not yet be enabled in your Vertex AI project when Anthropic releases an update. Claude Code [falls back](#startup-model-checks) to the previous version at startup when the latest is unavailable, but pinning lets you control when your users move to a new model.120 Pin specific model versions when deploying to multiple users. Without pinning, model aliases such as `sonnet` and `opus` resolve to the latest version, which may not yet be enabled in your Vertex AI project when Anthropic releases an update. Claude Code [falls back](#startup-model-checks) to the previous version at startup when the latest is unavailable, but pinning lets you control when your users move to a new model.

121</Warning>121</Warning>

122 122

123Set these environment variables to specific Vertex AI model IDs:123Set these environment variables to specific Vertex AI model IDs.

124

125Without `ANTHROPIC_DEFAULT_OPUS_MODEL`, the `opus` alias on Vertex resolves to Opus 4.6. Set it to the Opus 4.7 ID to use the latest model:

124 126

125```bash theme={null}127```bash theme={null}

126export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6'128export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-7'

127export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'129export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'

128export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'130export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

129```131```

140To customize models further:142To customize models further:

141 143

142```bash theme={null}144```bash theme={null}

143export ANTHROPIC_MODEL='claude-opus-4-6'145export ANTHROPIC_MODEL='claude-opus-4-7'

144export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'146export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

145```147```

146 148

170 172

171## 1M token context window173## 1M token context window

172 174

173Claude Opus 4.6, Sonnet 4.6, Sonnet 4.5, and Sonnet 4 support the [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) on Vertex AI. Claude Code automatically enables the extended context window when you select a 1M model variant.175Claude Opus 4.7, Opus 4.6, and Sonnet 4.6 support the [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) on Vertex AI. Claude Code automatically enables the extended context window when you select a 1M model variant.

174 176

175To enable the 1M context window for your pinned model, append `[1m]` to the model ID. See [Pin models for third-party deployments](/en/model-config#pin-models-for-third-party-deployments) for details.177The [setup wizard](#sign-in-with-vertex-ai) offers a 1M context option when it pins models. To enable it for a manually pinned model instead, append `[1m]` to the model ID. See [Pin models for third-party deployments](/en/model-config#pin-models-for-third-party-deployments) for details.

176 178

177## Troubleshooting179## Troubleshooting

178 180

headless.md +20 −1

Details

136 136

137The `system/init` event reports session metadata including the model, tools, MCP servers, and loaded plugins. It is the first event in the stream unless [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/en/env-vars) is set, in which case `plugin_install` events precede it. Use the plugin fields to fail CI when a plugin did not load:

138

139| Field | Type | Description |

140| --------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

141| `plugins` | array | plugins that loaded successfully, each with `name` and `path` |

142| `plugin_errors` | array | plugin load-time errors such as an unsatisfied dependency version, each with `plugin`, `type`, and `message`. Affected plugins are demoted and absent from `plugins`. The key is omitted when there are no errors |

143

144When [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/en/env-vars) is set, Claude Code emits `system/plugin_install` events while marketplace plugins install before the first turn. Use these to surface install progress in your own UI.

145

146| Field | Type | Description |

147| ------------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |

148| `type` | `"system"` | message type |

149| `subtype` | `"plugin_install"` | identifies this as a plugin install event |

150| `status` | `"started"`, `"installed"`, `"failed"`, or `"completed"` | `started` and `completed` bracket the overall install; `installed` and `failed` report individual marketplaces |

151| `name` | string, optional | marketplace name, present on `installed` and `failed` |

152| `error` | string, optional | failure message, present on `failed` |

153| `uuid` | string | unique event identifier |

154| `session_id` | string | session the event belongs to |

155

137For programmatic streaming with callbacks and message objects, see [Stream responses in real-time](/en/agent-sdk/streaming-output) in the Agent SDK documentation.156For programmatic streaming with callbacks and message objects, see [Stream responses in real-time](/en/agent-sdk/streaming-output) in the Agent SDK documentation.

138 157

139### Auto-approve tools158### Auto-approve tools

145 --allowedTools "Bash,Read,Edit"164 --allowedTools "Bash,Read,Edit"

146```165```

147 166

148To set a baseline for the whole session instead of listing individual tools, pass a [permission mode](/en/permission-modes). `dontAsk` denies anything not in your `permissions.allow` rules, which is useful for locked-down CI runs. `acceptEdits` lets Claude write files without prompting and also auto-approves common filesystem commands such as `mkdir`, `touch`, `mv`, and `cp`. Other shell commands and network requests still need an `--allowedTools` entry or a `permissions.allow` rule, otherwise the run aborts when one is attempted:167To set a baseline for the whole session instead of listing individual tools, pass a [permission mode](/en/permission-modes). `dontAsk` denies anything not in your `permissions.allow` rules or the [read-only command set](/en/permissions#read-only-commands), which is useful for locked-down CI runs. `acceptEdits` lets Claude write files without prompting and also auto-approves common filesystem commands such as `mkdir`, `touch`, `mv`, and `cp`. Other shell commands and network requests still need an `--allowedTools` entry or a `permissions.allow` rule, otherwise the run aborts when one is attempted:

149 168

150```bash theme={null}169```bash theme={null}

151claude -p "Apply the lint fixes" --permission-mode acceptEdits170claude -p "Apply the lint fixes" --permission-mode acceptEdits

hooks.md +82 −20

Details

18 18

19<div style={{maxWidth: "500px", margin: "0 auto"}}>19<div style={{maxWidth: "500px", margin: "0 auto"}}>

20 <Frame>20 <Frame>

21 <img src="https://mintcdn.com/claude-code/UMJp-WgTWngzO609/images/hooks-lifecycle.svg?fit=max&auto=format&n=UMJp-WgTWngzO609&q=85&s=3f4de67df216c87dc313943b32c15f62" alt="Hook lifecycle diagram showing SessionStart, then a per-turn loop containing UserPromptSubmit, the nested agentic loop (PreToolUse, PermissionRequest, PostToolUse, SubagentStart/Stop, TaskCreated, TaskCompleted), and Stop or StopFailure, followed by TeammateIdle, PreCompact, PostCompact, and SessionEnd, with Elicitation and ElicitationResult nested inside MCP tool execution, PermissionDenied as a side branch from PermissionRequest for auto-mode denials, and WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged, and FileChanged as standalone async events" width="520" height="1155" data-path="images/hooks-lifecycle.svg" />21 <img src="https://mintcdn.com/claude-code/NgDeMMkM7ZmaRibg/images/hooks-lifecycle.svg?fit=max&auto=format&n=NgDeMMkM7ZmaRibg&q=85&s=ec53c77f9943a6470cb2c8ecace6d809" alt="Hook lifecycle diagram showing SessionStart, then a per-turn loop containing UserPromptSubmit, UserPromptExpansion for slash commands, the nested agentic loop (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, SubagentStart/Stop, TaskCreated, TaskCompleted), and Stop or StopFailure, followed by TeammateIdle, PreCompact, PostCompact, and SessionEnd, with Elicitation and ElicitationResult nested inside MCP tool execution, PermissionDenied as a side branch from PermissionRequest for auto-mode denials, and WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged, and FileChanged as standalone async events" width="520" height="1155" data-path="images/hooks-lifecycle.svg" />

22 </Frame>22 </Frame>

23</div>23</div>

24 24

25The table below summarizes when each event fires. The [Hook events](#hook-events) section documents the full input schema and decision control options for each one.25The table below summarizes when each event fires. The [Hook events](#hook-events) section documents the full input schema and decision control options for each one.

26 26

27| Event | When it fires |27| Event | When it fires |

~~28| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |~~28| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

29| `SessionStart` | When a session begins or resumes |29| `SessionStart` | When a session begins or resumes |

30| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |30| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |

31| `UserPromptExpansion` | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion |

31| `PreToolUse` | Before a tool call executes. Can block it |32| `PreToolUse` | Before a tool call executes. Can block it |

32| `PermissionRequest` | When a permission dialog appears |33| `PermissionRequest` | When a permission dialog appears |

33| `PermissionDenied` | When a tool call is denied by the auto mode classifier. Return `{retry: true}` to tell the model it may retry the denied tool call |34| `PermissionDenied` | When a tool call is denied by the auto mode classifier. Return `{retry: true}` to tell the model it may retry the denied tool call |

55 56

56### How a hook resolves57### How a hook resolves

57 58

58To see how these pieces fit together, consider this `PreToolUse` hook that blocks destructive shell commands. The `matcher` narrows to Bash tool calls and the `if` condition narrows further to commands starting with `rm`, so `block-rm.sh` only spawns when both filters match:59To see how these pieces fit together, consider this `PreToolUse` hook that blocks destructive shell commands. The `matcher` narrows to Bash tool calls and the `if` condition narrows further to Bash subcommands matching `rm *`, so `block-rm.sh` only spawns when both filters match:

59 60

60```json theme={null}61```json theme={null}

61{62{

116 </Step>117 </Step>

117 118

118 <Step title="If condition checks">119 <Step title="If condition checks">

119 The `if` condition `"Bash(rm *)"` matches because the command starts with `rm`, so this handler spawns. If the command had been `npm test`, the `if` check would fail and `block-rm.sh` would never run, avoiding the process spawn overhead. The `if` field is optional; without it, every handler in the matched group runs.120 The `if` condition `"Bash(rm *)"` matches because `rm -rf /tmp/build` is a subcommand matching `rm *`, so this handler spawns. If the command had been `npm test`, the `if` check would fail and `block-rm.sh` would never run, avoiding the process spawn overhead. The `if` field is optional; without it, every handler in the matched group runs.

120 </Step>121 </Step>

121 122

122 <Step title="Hook handler runs">123 <Step title="Hook handler runs">

203| `UserPromptExpansion` | command name | your skill or command names |

204| `UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove` | no matcher support | always fires on every occurrence |206| `UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove` | no matcher support | always fires on every occurrence |

227 229

228`UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, and `CwdChanged` don't support matchers and always fire on every occurrence. If you add a `matcher` field to these events, it is silently ignored.230`UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, and `CwdChanged` don't support matchers and always fire on every occurrence. If you add a `matcher` field to these events, it is silently ignored.

229 231

230For tool events, you can filter more narrowly by setting the [`if` field](#common-fields) on individual hook handlers. `if` uses [permission rule syntax](/en/permissions) to match against the tool name and arguments together, so `"Bash(git *)"` runs only for `git` commands and `"Edit(*.ts)"` runs only for TypeScript files.232For tool events, you can filter more narrowly by setting the [`if` field](#common-fields) on individual hook handlers. `if` uses [permission rule syntax](/en/permissions) to match against the tool name and arguments together, so `"Bash(git *)"` runs when any subcommand of the Bash input matches `git *` and `"Edit(*.ts)"` runs only for TypeScript files.

231 233

232#### Match MCP tools234#### Match MCP tools

233 235

280* **[Command hooks](#command-hook-fields)** (`type: "command"`): run a shell command. Your script receives the event's [JSON input](#hook-input-and-output) on stdin and communicates results back through exit codes and stdout.282* **[Command hooks](#command-hook-fields)** (`type: "command"`): run a shell command. Your script receives the event's [JSON input](#hook-input-and-output) on stdin and communicates results back through exit codes and stdout.

281* **[HTTP hooks](#http-hook-fields)** (`type: "http"`): send the event's JSON input as an HTTP POST request to a URL. The endpoint communicates results back through the response body using the same [JSON output format](#json-output) as command hooks.283* **[HTTP hooks](#http-hook-fields)** (`type: "http"`): send the event's JSON input as an HTTP POST request to a URL. The endpoint communicates results back through the response body using the same [JSON output format](#json-output) as command hooks.

282* **[Prompt hooks](#prompt-and-agent-hook-fields)** (`type: "prompt"`): send a prompt to a Claude model for single-turn evaluation. The model returns a yes/no decision as JSON. See [Prompt-based hooks](#prompt-based-hooks).284* **[Prompt hooks](#prompt-and-agent-hook-fields)** (`type: "prompt"`): send a prompt to a Claude model for single-turn evaluation. The model returns a yes/no decision as JSON. See [Prompt-based hooks](#prompt-based-hooks).

283* **[Agent hooks](#prompt-and-agent-hook-fields)** (`type: "agent"`): spawn a subagent that can use tools like Read, Grep, and Glob to verify conditions before returning a decision. See [Agent-based hooks](#agent-based-hooks).285* **[Agent hooks](#prompt-and-agent-hook-fields)** (`type: "agent"`): spawn a subagent that can use tools like Read, Grep, and Glob to verify conditions before returning a decision. Agent hooks are experimental and may change. See [Agent-based hooks](#agent-based-hooks).

284 286

285#### Common fields287#### Common fields

286 288

287These fields apply to all hook types:289These fields apply to all hook types:

288 290

290| :-------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |292| :-------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

291| `type` | yes | `"command"`, `"http"`, `"prompt"`, or `"agent"` |293| `type` | yes | `"command"`, `"http"`, `"prompt"`, or `"agent"` |

292| `if` | no | Permission rule syntax to filter when this hook runs, such as `"Bash(git *)"` or `"Edit(*.ts)"`. The hook only spawns if the tool call matches the pattern. Only evaluated on tool events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, and `PermissionDenied`. On other events, a hook with `if` set never runs. Uses the same syntax as [permission rules](/en/permissions) |294| `if` | no | Permission rule syntax to filter when this hook runs, such as `"Bash(git *)"` or `"Edit(*.ts)"`. The hook only spawns if the tool call matches the pattern, or if a Bash command is too complex to parse. Only evaluated on tool events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, and `PermissionRequest`. On other events, a hook with `if` set never runs. Uses the same syntax as [permission rules](/en/permissions) |

293| `timeout` | no | Seconds before canceling. Defaults: 600 for command, 30 for prompt, 60 for agent |295| `timeout` | no | Seconds before canceling. Defaults: 600 for command, 30 for prompt, 60 for agent |

294| `statusMessage` | no | Custom spinner message displayed while the hook runs |296| `statusMessage` | no | Custom spinner message displayed while the hook runs |

295| `once` | no | If `true`, runs only once per session then is removed. Skills only, not agents. See [Hooks in skills and agents](#hooks-in-skills-and-agents) |297| `once` | no | If `true`, runs once per session then is removed. Only honored for hooks declared in [skill frontmatter](#hooks-in-skills-and-agents); ignored in settings files and agent frontmatter |

298

299The `if` field holds exactly one permission rule. There is no `&&`, `||`, or list syntax for combining rules; to apply multiple conditions, define a separate hook handler for each. For Bash, the rule is matched against each subcommand of the tool input after leading `VAR=value` assignments are stripped, so `if: "Bash(git push *)"` matches both `FOO=bar git push` and `npm test && git push`. The hook runs if any subcommand matches, and always runs when the command is too complex to parse.

296 300

297#### Command hook fields301#### Command hook fields

298 302

510 514

511The exit code from your hook command tells Claude Code whether the action should proceed, be blocked, or be ignored.515The exit code from your hook command tells Claude Code whether the action should proceed, be blocked, or be ignored.

512 516

513**Exit 0** means success. Claude Code parses stdout for [JSON output fields](#json-output). JSON output is only processed on exit 0. For most events, stdout is written to the debug log but not shown in the transcript. The exceptions are `UserPromptSubmit` and `SessionStart`, where stdout is added as context that Claude can see and act on.517**Exit 0** means success. Claude Code parses stdout for [JSON output fields](#json-output). JSON output is only processed on exit 0. For most events, stdout is written to the debug log but not shown in the transcript. The exceptions are `UserPromptSubmit`, `UserPromptExpansion`, and `SessionStart`, where stdout is added as context that Claude can see and act on.

514 518

515**Exit 2** means a blocking error. Claude Code ignores stdout and any JSON in it. Instead, stderr text is fed back to Claude as an error message. The effect depends on the event: `PreToolUse` blocks the tool call, `UserPromptSubmit` rejects the prompt, and so on. See [exit code 2 behavior](#exit-code-2-behavior-per-event) for the full list.519**Exit 2** means a blocking error. Claude Code ignores stdout and any JSON in it. Instead, stderr text is fed back to Claude as an error message. The effect depends on the event: `PreToolUse` blocks the tool call, `UserPromptSubmit` rejects the prompt, and so on. See [exit code 2 behavior](#exit-code-2-behavior-per-event) for the full list.

516 520

540Exit code 2 is the way a hook signals "stop, don't do this." The effect depends on the event, because some events represent actions that can be blocked (like a tool call that hasn't happened yet) and others represent things that already happened or can't be prevented.544Exit code 2 is the way a hook signals "stop, don't do this." The effect depends on the event, because some events represent actions that can be blocked (like a tool call that hasn't happened yet) and others represent things that already happened or can't be prevented.

541 545

543| :------------------- | :--------- | :----------------------------------------------------------------------------------------------------------------------------------- |547| :-------------------- | :--------- | :----------------------------------------------------------------------------------------------------------------------------------- |

544| `PreToolUse` | Yes | Blocks the tool call |548| `PreToolUse` | Yes | Blocks the tool call |

545| `PermissionRequest` | Yes | Denies the permission |549| `PermissionRequest` | Yes | Denies the permission |

546| `UserPromptSubmit` | Yes | Blocks prompt processing and erases the prompt |550| `UserPromptSubmit` | Yes | Blocks prompt processing and erases the prompt |

551| `UserPromptExpansion` | Yes | Blocks the expansion |

547| `Stop` | Yes | Prevents Claude from stopping, continues the conversation |552| `Stop` | Yes | Prevents Claude from stopping, continues the conversation |

548| `SubagentStop` | Yes | Prevents the subagent from stopping |553| `SubagentStop` | Yes | Prevents the subagent from stopping |

549| `TeammateIdle` | Yes | Prevents the teammate from going idle (teammate continues working) |554| `TeammateIdle` | Yes | Prevents the teammate from going idle (teammate continues working) |

616Not every event supports blocking or controlling behavior through JSON. The events that do each use a different set of fields to express that decision. Use this table as a quick reference before writing a hook:621Not every event supports blocking or controlling behavior through JSON. The events that do each use a different set of fields to express that decision. Use this table as a quick reference before writing a hook:

617 622

619| :-------------------------------------------------------------------------------------------------------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |624| :------------------------------------------------------------------------------------------------------------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

621| TeammateIdle, TaskCreated, TaskCompleted | Exit code or `continue: false` | Exit code 2 blocks the action with stderr feedback. JSON `{"continue": false, "stopReason": "..."}` also stops the teammate entirely, matching `Stop` hook behavior |626| TeammateIdle, TaskCreated, TaskCompleted | Exit code or `continue: false` | Exit code 2 blocks the action with stderr feedback. JSON `{"continue": false, "stopReason": "..."}` also stops the teammate entirely, matching `Stop` hook behavior |

631 636

632<Tabs>637<Tabs>

633 <Tab title="Top-level decision">638 <Tab title="Top-level decision">

634 Used by `UserPromptSubmit`, `PostToolUse`, `PostToolUseFailure`, `Stop`, `SubagentStop`, `ConfigChange`, and `PreCompact`. The only value is `"block"`. To allow the action to proceed, omit `decision` from your JSON, or exit 0 without any JSON at all:639 Used by `UserPromptSubmit`, `UserPromptExpansion`, `PostToolUse`, `PostToolUseFailure`, `Stop`, `SubagentStop`, `ConfigChange`, and `PreCompact`. The only value is `"block"`. To allow the action to proceed, omit `decision` from your JSON, or exit 0 without any JSON at all:

635 640

636 ```json theme={null}641 ```json theme={null}

637 {642 {

863 block prompts or want more structured control.868 block prompts or want more structured control.

864</Note>869</Note>

865 870

871### UserPromptExpansion

872

873Runs when a user-typed slash command expands into a prompt before reaching Claude. Use this to block specific commands from direct invocation, inject context for a particular skill, or log which commands users invoke. For example, a hook matching `deploy` can block `/deploy` unless an approval file is present, or a hook matching a review skill can append the team's review checklist as `additionalContext`.

874

875This event covers the path `PreToolUse` does not: a `PreToolUse` hook matching the `Skill` tool fires only when Claude calls the tool, but typing `/skillname` directly bypasses `PreToolUse`. `UserPromptExpansion` fires on that direct path.

876

877Matches on `command_name`. Leave the matcher empty to fire on every prompt-type slash command.

878

879#### UserPromptExpansion input

880

881In addition to the [common input fields](#common-input-fields), UserPromptExpansion hooks receive `expansion_type`, `command_name`, `command_args`, `command_source`, and the original `prompt` string. The `expansion_type` field is `slash_command` for skill and custom commands, or `mcp_prompt` for MCP server prompts.

882

883```json theme={null}

884{

885 "session_id": "abc123",

886 "transcript_path": "/Users/.../00893aaf.jsonl",

887 "cwd": "/Users/...",

888 "permission_mode": "default",

889 "hook_event_name": "UserPromptExpansion",

890 "expansion_type": "slash_command",

891 "command_name": "example-skill",

892 "command_args": "arg1 arg2",

893 "command_source": "plugin",

894 "prompt": "/example-skill arg1 arg2"

895}

896```

897

898#### UserPromptExpansion decision control

899

900`UserPromptExpansion` hooks can block the expansion or add context. All [JSON output fields](#json-output) are available.

901

902| Field | Description |

903| :------------------ | :------------------------------------------------------------------------------- |

904| `decision` | `"block"` prevents the slash command from expanding. Omit to allow it to proceed |

905| `reason` | Shown to the user when `decision` is `"block"` |

906| `additionalContext` | String added to Claude's context alongside the expanded prompt |

907

908```json theme={null}

909{

910 "decision": "block",

911 "reason": "This slash command is not available",

912 "hookSpecificOutput": {

913 "hookEventName": "UserPromptExpansion",

914 "additionalContext": "Additional context for this expansion"

915 }

916}

917```

918

866### PreToolUse919### PreToolUse

867 920

868Runs after Claude creates tool parameters and before processing the tool call. Matches on tool name: `Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `WebFetch`, `WebSearch`, `AskUserQuestion`, `ExitPlanMode`, and any [MCP tool names](#match-mcp-tools).921Runs after Claude creates tool parameters and before processing the tool call. Matches on tool name: `Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `WebFetch`, `WebSearch`, `AskUserQuestion`, `ExitPlanMode`, and any [MCP tool names](#match-mcp-tools).

1091`PermissionRequest` hooks can allow or deny permission requests. In addition to the [JSON output fields](#json-output) available to all hooks, your hook script can return a `decision` object with these event-specific fields:1144`PermissionRequest` hooks can allow or deny permission requests. In addition to the [JSON output fields](#json-output) available to all hooks, your hook script can return a `decision` object with these event-specific fields:

1092 1145

1093| Field | Description |1146| Field | Description |

1094| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1147| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

1095| `behavior` | `"allow"` grants the permission, `"deny"` denies it |1148| `behavior` | `"allow"` grants the permission, `"deny"` denies it. [Deny and ask rules](/en/permissions#manage-permissions) are still evaluated, so a hook returning `"allow"` does not override a matching deny rule |

1096| `updatedInput` | For `"allow"` only: modifies the tool's input parameters before execution. Replaces the entire input object, so include unchanged fields alongside modified ones |1149| `updatedInput` | For `"allow"` only: modifies the tool's input parameters before execution. Replaces the entire input object, so include unchanged fields alongside modified ones. The modified input is re-evaluated against deny and ask rules |

1097| `updatedPermissions` | For `"allow"` only: array of [permission update entries](#permission-update-entries) to apply, such as adding an allow rule or changing the session permission mode |1150| `updatedPermissions` | For `"allow"` only: array of [permission update entries](#permission-update-entries) to apply, such as adding an allow rule or changing the session permission mode |

1127 1180

1181<Note>

1182 `setMode` with `bypassPermissions` only takes effect if the session was launched with bypass mode already available: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`, or `permissions.defaultMode: "bypassPermissions"` in settings, and the mode is not disabled by [`permissions.disableBypassPermissionsMode`](/en/permissions#managed-settings). Otherwise the update is a no-op. `bypassPermissions` is never persisted as `defaultMode` regardless of `destination`.

1183</Note>

1184

1128The `destination` field on every entry determines whether the change stays in memory or persists to a settings file.1185The `destination` field on every entry determines whether the change stays in memory or persists to a settings file.

1129 1186

1694 1751

1695Runs when the working directory changes during a session, for example when Claude executes a `cd` command. Use this to react to directory changes: reload environment variables, activate project-specific toolchains, or run setup scripts automatically. Pairs with [FileChanged](#filechanged) for tools like [direnv](https://direnv.net/) that manage per-directory environment.1752Runs when the working directory changes during a session, for example when Claude executes a `cd` command. Use this to react to directory changes: reload environment variables, activate project-specific toolchains, or run setup scripts automatically. Pairs with [FileChanged](#filechanged) for tools like [direnv](https://direnv.net/) that manage per-directory environment.

1696 1753

1697CwdChanged hooks have access to `CLAUDE_ENV_FILE`. Variables written to that file persist into subsequent Bash commands for the session, just as in [SessionStart hooks](#persist-environment-variables). Only `type: "command"` hooks are supported.1754CwdChanged hooks have access to `CLAUDE_ENV_FILE`. Variables written to that file persist into subsequent Bash commands for the session, just as in [SessionStart hooks](#persist-environment-variables).

1698 1755

1699CwdChanged does not support matchers and fires on every directory change.1756CwdChanged does not support matchers and fires on every directory change.

1700 1757

1732* **Build the watch list**: the value is split on `|` and each segment is registered as a literal filename in the working directory, so `".envrc|.env"` watches exactly those two files. Regex patterns are not useful here: a value like `^\.env` would watch a file literally named `^\.env`.1789* **Build the watch list**: the value is split on `|` and each segment is registered as a literal filename in the working directory, so `".envrc|.env"` watches exactly those two files. Regex patterns are not useful here: a value like `^\.env` would watch a file literally named `^\.env`.

1733* **Filter which hooks run**: when a watched file changes, the same value filters which hook groups run using the standard [matcher rules](#matcher-patterns) against the changed file's basename.1790* **Filter which hooks run**: when a watched file changes, the same value filters which hook groups run using the standard [matcher rules](#matcher-patterns) against the changed file's basename.

1734 1791

1735FileChanged hooks have access to `CLAUDE_ENV_FILE`. Variables written to that file persist into subsequent Bash commands for the session, just as in [SessionStart hooks](#persist-environment-variables). Only `type: "command"` hooks are supported.1792FileChanged hooks have access to `CLAUDE_ENV_FILE`. Variables written to that file persist into subsequent Bash commands for the session, just as in [SessionStart hooks](#persist-environment-variables).

1736 1793

1737#### FileChanged input1794#### FileChanged input

1738 1795

2081* `SubagentStop`2138* `SubagentStop`

2082* `TaskCompleted`2139* `TaskCompleted`

2083* `TaskCreated`2140* `TaskCreated`

2141* `UserPromptExpansion`

2084* `UserPromptSubmit`2142* `UserPromptSubmit`

2085 2143

2086Events that support `command` and `http` hooks but not `prompt` or `agent`:2144Events that support `command` and `http` hooks but not `prompt` or `agent`:

2182 2240

2183## Agent-based hooks2241## Agent-based hooks

2184 2242

2243<Warning>

2244 Agent hooks are experimental. Behavior and configuration may change in future releases. For production workflows, prefer [command hooks](#command-hook-fields).

2245</Warning>

2246

2185Agent-based hooks (`type: "agent"`) are like prompt-based hooks but with multi-turn tool access. Instead of a single LLM call, an agent hook spawns a subagent that can read files, search code, and inspect the codebase to verify conditions. Agent hooks support the same events as prompt-based hooks.2247Agent-based hooks (`type: "agent"`) are like prompt-based hooks but with multi-turn tool access. Instead of a single LLM call, an agent hook spawns a subagent that can read files, search code, and inspect the codebase to verify conditions. Agent hooks support the same events as prompt-based hooks.

2186 2248

2187### How agent hooks work2249### How agent hooks work

2383 2445

2384For more granular hook matching details, set `CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose` to see additional log lines such as hook matcher counts and query matching.2446For more granular hook matching details, set `CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose` to see additional log lines such as hook matcher counts and query matching.

2385 2447

2386For troubleshooting common issues like hooks not firing, infinite Stop hook loops, or configuration errors, see [Limitations and troubleshooting](/en/hooks-guide#limitations-and-troubleshooting) in the guide.2448For troubleshooting common issues like hooks not firing, infinite Stop hook loops, or configuration errors, see [Limitations and troubleshooting](/en/hooks-guide#limitations-and-troubleshooting) in the guide. For a broader diagnostic walkthrough covering `/context`, `/doctor`, and settings precedence, see [Debug your config](/en/debug-your-config).

hooks-guide.md +31 −9

Details

316 316

317Some projects set different environment variables depending on which directory you are in. Tools like [direnv](https://direnv.net/) do this automatically in your shell, but Claude's Bash tool does not pick up those changes on its own.317Some projects set different environment variables depending on which directory you are in. Tools like [direnv](https://direnv.net/) do this automatically in your shell, but Claude's Bash tool does not pick up those changes on its own.

318 318

319A `CwdChanged` hook fixes this: it runs each time Claude changes directory, so you can reload the correct variables for the new location. The hook writes the updated values to `CLAUDE_ENV_FILE`, which Claude Code applies before each Bash command. Add this to `~/.claude/settings.json`:319Pairing a `SessionStart` hook with a `CwdChanged` hook fixes this. `SessionStart` loads the variables for the directory you launch in, and `CwdChanged` reloads them each time Claude changes directory. Both write to `CLAUDE_ENV_FILE`, which Claude Code runs as a script preamble before each Bash command. Add this to `~/.claude/settings.json`:

320 320

321```json theme={null}321```json theme={null}

322{322{

323 "hooks": {323 "hooks": {

324 "SessionStart": [

325 {

326 "hooks": [

327 {

328 "type": "command",

329 "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""

330 }

331 ]

332 }

333 ],

324 "CwdChanged": [334 "CwdChanged": [

325 {335 {

326 "hooks": [336 "hooks": [

327 {337 {

328 "type": "command",338 "type": "command",

329 "command": "direnv export bash >> \"$CLAUDE_ENV_FILE\""339 "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""

330 }340 }

331 ]341 ]

332 }342 }

335}345}

336```346```

337 347

348Run `direnv allow` once in each directory that has an `.envrc` so direnv is permitted to load it. If you use devbox or nix instead of direnv, the same pattern works with `devbox shellenv` or `devbox global shellenv` in place of `direnv export bash`.

349

338To react to specific files instead of every directory change, use `FileChanged` with a `matcher` listing the filenames to watch, separated by `|`. To build the watch list, this value is split into literal filenames rather than evaluated as a regex. See [FileChanged](/en/hooks#filechanged) for how the same value also filters which hook groups run when a file changes. This example watches `.envrc` and `.env` in the working directory:350To react to specific files instead of every directory change, use `FileChanged` with a `matcher` listing the filenames to watch, separated by `|`. To build the watch list, this value is split into literal filenames rather than evaluated as a regex. See [FileChanged](/en/hooks#filechanged) for how the same value also filters which hook groups run when a file changes. This example watches `.envrc` and `.env` in the working directory:

339 351

340```json theme={null}352```json theme={null}

346 "hooks": [358 "hooks": [

347 {359 {

348 "type": "command",360 "type": "command",

349 "command": "direnv export bash >> \"$CLAUDE_ENV_FILE\""361 "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""

350 }362 }

351 ]363 ]

352 }364 }

387 399

388To set a specific permission mode instead, your hook's output can include an `updatedPermissions` array with a `setMode` entry. The `mode` value is any permission mode like `default`, `acceptEdits`, or `bypassPermissions`, and `destination: "session"` applies it for the current session only.400To set a specific permission mode instead, your hook's output can include an `updatedPermissions` array with a `setMode` entry. The `mode` value is any permission mode like `default`, `acceptEdits`, or `bypassPermissions`, and `destination: "session"` applies it for the current session only.

389 401

402<Note>

403 `bypassPermissions` only applies if the session was launched with bypass mode already available: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`, or `permissions.defaultMode: "bypassPermissions"` in settings, and not disabled by [`permissions.disableBypassPermissionsMode`](/en/permissions#managed-settings). It is never persisted as `defaultMode`.

404</Note>

405

390To switch the session to `acceptEdits`, your hook writes this JSON to stdout:406To switch the session to `acceptEdits`, your hook writes this JSON to stdout:

391 407

392```json theme={null}408```json theme={null}

410Hook events fire at specific lifecycle points in Claude Code. When an event fires, all matching hooks run in parallel, and identical hook commands are automatically deduplicated. The table below shows each event and when it triggers:426Hook events fire at specific lifecycle points in Claude Code. When an event fires, all matching hooks run in parallel, and identical hook commands are automatically deduplicated. The table below shows each event and when it triggers:

411 427

412| Event | When it fires |428| Event | When it fires |

413| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |429| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

432| `UserPromptExpansion` | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion |

418| `PermissionDenied` | When a tool call is denied by the auto mode classifier. Return `{retry: true}` to tell the model it may retry the denied tool call |435| `PermissionDenied` | When a tool call is denied by the auto mode classifier. Return `{retry: true}` to tell the model it may retry the denied tool call |

444 461

445* `"type": "http"`: POST event data to a URL. See [HTTP hooks](#http-hooks).462* `"type": "http"`: POST event data to a URL. See [HTTP hooks](#http-hooks).

446* `"type": "prompt"`: single-turn LLM evaluation. See [Prompt-based hooks](#prompt-based-hooks).463* `"type": "prompt"`: single-turn LLM evaluation. See [Prompt-based hooks](#prompt-based-hooks).

447* `"type": "agent"`: multi-turn verification with tool access. See [Agent-based hooks](#agent-based-hooks).464* `"type": "agent"`: multi-turn verification with tool access. Agent hooks are experimental and may change. See [Agent-based hooks](#agent-based-hooks).

448 465

449### Read input and return output466### Read input and return output

450 467

487 504

488The exit code determines what happens next:505The exit code determines what happens next:

489 506

490* **Exit 0**: the action proceeds. For `UserPromptSubmit` and `SessionStart` hooks, anything you write to stdout is added to Claude's context.507* **Exit 0**: the action proceeds. For `UserPromptSubmit`, `UserPromptExpansion`, and `SessionStart` hooks, anything you write to stdout is added to Claude's context.

491* **Exit 2**: the action is blocked. Write a reason to stderr, and Claude receives it as feedback so it can adjust.508* **Exit 2**: the action is blocked. Write a reason to stderr, and Claude receives it as feedback so it can adjust.

492* **Any other exit code**: the action proceeds. The transcript shows a `<hook name> hook error` notice followed by the first line of stderr; the full stderr goes to the [debug log](/en/hooks#debug-hooks).509* **Any other exit code**: the action proceeds. The transcript shows a `<hook name> hook error` notice followed by the first line of stderr; the full stderr goes to the [debug log](/en/hooks#debug-hooks).

493 510

583| `UserPromptExpansion` | command name | your skill or command names |

566| `UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `CwdChanged` | no matcher support | always fires on every occurrence |584| `UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `CwdChanged` | no matcher support | always fires on every occurrence |

567 585

568A few more examples showing matchers on different event types:586A few more examples showing matchers on different event types:

645 The `if` field requires Claude Code v2.1.85 or later. Earlier versions ignore it and run the hook on every matched call.663 The `if` field requires Claude Code v2.1.85 or later. Earlier versions ignore it and run the hook on every matched call.

646</Note>664</Note>

647 665

648The `if` field uses [permission rule syntax](/en/permissions) to filter hooks by tool name and arguments together, so the hook process only spawns when the tool call matches. This goes beyond `matcher`, which filters at the group level by tool name only.666The `if` field uses [permission rule syntax](/en/permissions) to filter hooks by tool name and arguments together, so the hook process only spawns when the tool call matches, or when a Bash command is too complex to parse. This goes beyond `matcher`, which filters at the group level by tool name only.

649 667

650For example, to run a hook only when Claude uses `git` commands rather than all Bash commands:668For example, to run a hook only when Claude uses `git` commands rather than all Bash commands:

651 669

668}686}

669```687```

670 688

671The hook process only spawns when the Bash command starts with `git`. Other Bash commands skip this handler entirely. The `if` field accepts the same patterns as permission rules: `"Bash(git *)"`, `"Edit(*.ts)"`, and so on. To match multiple tool names, use separate handlers each with its own `if` value, or match at the `matcher` level where pipe alternation is supported.689The hook process only spawns when a subcommand of the Bash command matches `git *`, or when the command is too complex to parse into subcommands. For compound commands like `npm test && git push`, Claude Code evaluates each subcommand and fires the hook because `git push` matches. The `if` field accepts the same patterns as permission rules: `"Bash(git *)"`, `"Edit(*.ts)"`, and so on. To match multiple tool names, use separate handlers each with its own `if` value, or match at the `matcher` level where pipe alternation is supported.

672 690

673`if` only works on tool events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, and `PermissionDenied`. Adding it to any other event prevents the hook from running.691`if` only works on tool events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, and `PermissionRequest`. Adding it to any other event prevents the hook from running.

674 692

675### Configure hook location693### Configure hook location

676 694

721 739

722## Agent-based hooks740## Agent-based hooks

723 741

742<Warning>

743 Agent hooks are experimental. Behavior and configuration may change in future releases. For production workflows, prefer [command hooks](/en/hooks#command-hook-fields).

744</Warning>

745

724When verification requires inspecting files or running commands, use `type: "agent"` hooks. Unlike prompt hooks which make a single LLM call, agent hooks spawn a subagent that can read files, search code, and use other tools to verify conditions before returning a decision.746When verification requires inspecting files or running commands, use `type: "agent"` hooks. Unlike prompt hooks which make a single LLM call, agent hooks spawn a subagent that can read files, search code, and use other tools to verify conditions before returning a decision.

725 747

726Agent hooks use the same `"ok"` / `"reason"` response format as prompt hooks, but with a longer default timeout of 60 seconds and up to 50 tool-use turns.748Agent hooks use the same `"ok"` / `"reason"` response format as prompt hooks, but with a longer default timeout of 60 seconds and up to 50 tool-use turns.

how-claude-code-works.md +1 −1

Details

100 100

101### Work across branches101### Work across branches

102 102

103Each Claude Code conversation is a session tied to your current directory. When you resume, you only see sessions from that directory.103Each Claude Code conversation is a session tied to your current directory. The `/resume` picker shows sessions from the current worktree by default, with keyboard shortcuts to widen the list to other worktrees or projects. See [Resume previous conversations](/en/common-workflows#resume-previous-conversations) for the full list of picker shortcuts and how name resolution works.

104 104

105Claude sees your current branch's files. When you switch branches, Claude sees the new branch's files, but your conversation history stays the same. Claude remembers what you discussed even after switching.105Claude sees your current branch's files. When you switch branches, Claude sees the new branch's files, but your conversation history stays the same. Claude remembers what you discussed even after switching.

106 106

interactive-mode.md +31 −17

Details

13 13

14 **macOS users**: Option/Alt key shortcuts (`Alt+B`, `Alt+F`, `Alt+Y`, `Alt+M`, `Alt+P`, `Alt+T`) require configuring Option as Meta in your terminal:14 **macOS users**: Option/Alt key shortcuts (`Alt+B`, `Alt+F`, `Alt+Y`, `Alt+M`, `Alt+P`, `Alt+T`) require configuring Option as Meta in your terminal:

15 15

~~16 * **iTerm2**: settings → Profiles → Keys → set Left/Right Option key to "Esc+"~~16 * **iTerm2**: Settings → Profiles → Keys → General → set Left/Right Option key to "Esc+"

~~17 * **Terminal.app**: settings → Profiles → Keyboard → check "Use Option as Meta Key"~~17 * **Apple Terminal**: Settings → Profiles → Keyboard → check "Use Option as Meta Key"

18 * **VS Code**: set `"terminal.integrated.macOptionIsMeta": true` in VS Code settings18 * **VS Code**: set `"terminal.integrated.macOptionIsMeta": true` in VS Code settings

19 19

20 See [Terminal configuration](/en/terminal-config) for details.20 See [Terminal configuration](/en/terminal-config) for details.

23### General controls23### General controls

24 24

26| :------------------------------------------------ | :------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |26| :------------------------------------------------ | :------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

30| `Ctrl+G` or `Ctrl+X Ctrl+E` | Open in default text editor | Edit your prompt or custom response in your default text editor. `Ctrl+X Ctrl+E` is the readline-native binding |30| `Ctrl+G` or `Ctrl+X Ctrl+E` | Open in default text editor | Edit your prompt or custom response in your default text editor. `Ctrl+X Ctrl+E` is the readline-native binding. Turn on Show last response in external editor in `/config` to prepend Claude's previous reply as `#`-commented context above your prompt; the comment block is stripped when you save |

32| `Ctrl+O` | Toggle transcript viewer | Shows detailed tool usage and execution. Also expands MCP calls, which collapse to a single line like "Called slack 3 times" by default. In [fullscreen rendering](/en/fullscreen), cycles through three states: normal prompt, transcript mode, and focus view (last prompt + tool summary + response) |32| `Ctrl+O` | Toggle transcript viewer | Shows detailed tool usage and execution. Also expands MCP calls, which collapse to a single line like "Called slack 3 times" by default |

34| `Ctrl+V` or `Cmd+V` (iTerm2) or `Alt+V` (Windows) | Paste image from clipboard | Inserts an `[Image #N]` chip at the cursor so you can reference it positionally in your prompt |34| `Ctrl+V` or `Cmd+V` (iTerm2) or `Alt+V` (Windows) | Paste image from clipboard | Inserts an `[Image #N]` chip at the cursor so you can reference it positionally in your prompt |

40| `Shift+Tab` or `Alt+M` (some configurations) | Cycle permission modes | Cycle through `default`, `acceptEdits`, `plan`, and any modes you have enabled, such as `auto` or `bypassPermissions`. See [permission modes](/en/permission-modes). |40| `Shift+Tab` or `Alt+M` (some configurations) | Cycle permission modes | Cycle through `default`, `acceptEdits`, `plan`, and any modes you have enabled, such as `auto` or `bypassPermissions`. See [permission modes](/en/permission-modes). |

45### Text editing45### Text editing

46 46

~~48| :----------------------- | :------------------------------- | :------------------------------------------------------------------------------------------------------------ |~~48| :----------------------- | :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

49| `Ctrl+A` | Move cursor to start of current line | In multiline input, moves to the start of the current logical line |

50| `Ctrl+E` | Move cursor to end of current line | In multiline input, moves to the end of the current logical line |

~~50| `Ctrl+U` | Delete from cursor to line start | Stores deleted text for pasting. Repeat to clear across lines in multiline input |~~52| `Ctrl+U` | Delete from cursor to line start | Stores deleted text for pasting. Repeat to clear across lines in multiline input. On macOS, terminal emulators including iTerm2 and Terminal.app map `Cmd+Backspace` to this shortcut |

54| `Ctrl+Y` | Paste deleted text | Paste text deleted with `Ctrl+K`, `Ctrl+U`, or `Ctrl+W` |

62### Multiline input65### Multiline input

63 66

~~65| :--------------- | :------------- | :------------------------------------------------------ |~~68| :--------------- | :------------- | :------------------------------------------------------------------------------------------------- |

71 74

72<Tip>75<Tip>

~~73 Shift+Enter works without configuration in iTerm2, WezTerm, Ghostty, and Kitty. For other terminals (VS Code, Alacritty, Zed, Warp), run `/terminal-setup` to install the binding.~~76 Shift+Enter works without configuration in iTerm2, WezTerm, Ghostty, Kitty, Warp, and Apple Terminal. For VS Code, Cursor, Windsurf, Alacritty, and Zed, run `/terminal-setup` to install the binding.

74</Tip>77</Tip>

75 78

76### Quick commands79### Quick commands

86When the transcript viewer is open (toggled with `Ctrl+O`), these shortcuts are available. `Ctrl+E` can be rebound via [`transcript:toggleShowAll`](/en/keybindings).89When the transcript viewer is open (toggled with `Ctrl+O`), these shortcuts are available. `Ctrl+E` can be rebound via [`transcript:toggleShowAll`](/en/keybindings).

87 90

88| Shortcut | Description |91| Shortcut | Description |

~~89| :------------------- | :-------------------------------------------------------------------------------------- |~~92| :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

94| `[` | Write the full conversation to your terminal's native scrollback so `Cmd+F`, tmux copy mode, and other native tools can search it. Requires [fullscreen rendering](/en/fullscreen#search-and-review-the-conversation) |

95| `v` | Write the conversation to a temporary file and open it in `$VISUAL` or `$EDITOR`. Requires [fullscreen rendering](/en/fullscreen) |

92 97

93### Voice input98### Voice input

160| `>>` | Indent line |165| `>>` | Indent line |

161| `<<` | Dedent line |166| `<<` | Dedent line |

162| `J` | Join lines |167| `J` | Join lines |

168| `u` | Undo |

163| `.` | Repeat last change |169| `.` | Repeat last change |

164 170

165### Text objects (NORMAL mode)171### Text objects (NORMAL mode)

295 301

296When working on complex, multi-step work, Claude creates a task list to track progress. Tasks appear in the status area of your terminal with indicators showing what's pending, in progress, or complete.302When working on complex, multi-step work, Claude creates a task list to track progress. Tasks appear in the status area of your terminal with indicators showing what's pending, in progress, or complete.

297 303

298* Press `Ctrl+T` to toggle the task list view. The display shows up to 10 tasks at a time304* Press `Ctrl+T` to toggle the task list view. The display shows up to 5 tasks at a time

299* To see all tasks or clear them, ask Claude directly: "show me all tasks" or "clear all tasks"305* To see all tasks or clear them, ask Claude directly: "show me all tasks" or "clear all tasks"

300* Tasks persist across context compactions, helping Claude stay organized on larger projects306* Tasks persist across context compactions, helping Claude stay organized on larger projects

301* To share a task list across sessions, set `CLAUDE_CODE_TASK_LIST_ID` to use a named directory in `~/.claude/tasks/`: `CLAUDE_CODE_TASK_LIST_ID=my-project claude`307* To share a task list across sessions, set `CLAUDE_CODE_TASK_LIST_ID` to use a named directory in `~/.claude/tasks/`: `CLAUDE_CODE_TASK_LIST_ID=my-project claude`

302 308

309## Session recap

310

311When you return to the terminal after stepping away, Claude Code shows a one-line recap of what happened in the session so far. The recap generates in the background once at least three minutes have passed since the last completed turn and the terminal is unfocused, so it's ready when you switch back. Recaps only appear once the session has at least three turns, and never twice in a row.

312

313Run `/recap` to generate a summary on demand. To turn automatic recaps off, open `/config` and disable **Session recap**.

314

315Session recap is on by default for every plan and provider. The recap is always skipped in non-interactive mode.

316

303## PR review status317## PR review status

304 318

305When working on a branch with an open pull request, Claude Code displays a clickable PR link in the footer (for example, "PR #446"). The link has a colored underline indicating the review state:319When working on a branch with an open pull request, Claude Code displays a clickable PR link in the footer (for example, "PR #446"). The link has a colored underline indicating the review state:

jetbrains.md +1 −1

Details

67 67

681. Run `claude`681. Run `claude`

692. Enter the `/config` command692. Enter the `/config` command

~~703. Set the diff tool to `auto` for automatic IDE detection~~703. Set the diff tool to `auto` to show diffs in the IDE, or `terminal` to keep them in the terminal

71 71

72### Plugin Settings72### Plugin Settings

73 73

keybindings.md +11 −4

Details

100Actions available in the `Chat` context:100Actions available in the `Chat` context:

101 101

103| :-------------------- | :------------------------ | :---------------------------------- |103| :-------------------- | :------------------------ | :------------------------------------------------ |

280Actions available in the `Plugin` context:280Actions available in the `Plugin` context:

281 281

283| :--------------- | :------ | :----------------------- |283| :---------------- | :------ | :------------------------------------------------------------------------- |

285| `plugin:install` | I | Install selected plugins |285| `plugin:install` | I | Install selected plugins |

286| `plugin:favorite` | F | Favorite the selected plugin so it sorts near the top of the Installed tab |

286 287

287### Settings actions288### Settings actions

288 289

315Actions available in the `Scroll` context when [fullscreen rendering](/en/fullscreen) is enabled:316Actions available in the `Scroll` context when [fullscreen rendering](/en/fullscreen) is enabled:

316 317

318| :-------------------- | :------------------- | :------------------------------------------------------------------------------------------------------ |319| :-------------------------- | :------------------- | :-------------------------------------------------------------------------------------------------------- |

332| `selection:extendLeft` | Shift+Left | Extend the active selection one column left |

333| `selection:extendRight` | Shift+Right | Extend the active selection one column right |

334| `selection:extendUp` | Shift+Up | Extend the active selection one row up. Scrolls the viewport when the selection reaches the top edge |

335| `selection:extendDown` | Shift+Down | Extend the active selection one row down. Scrolls the viewport when the selection reaches the bottom edge |

336| `selection:extendLineStart` | Shift+Home | Extend the active selection to the start of the line |

337| `selection:extendLineEnd` | Shift+End | Extend the active selection to the end of the line |

331 338

332## Keystroke syntax339## Keystroke syntax

333 340

mcp.md +31 −3

Details

126 126

127Claude Code supports MCP `list_changed` notifications, allowing MCP servers to dynamically update their available tools, prompts, and resources without requiring you to disconnect and reconnect. When an MCP server sends a `list_changed` notification, Claude Code automatically refreshes the available capabilities from that server.127Claude Code supports MCP `list_changed` notifications, allowing MCP servers to dynamically update their available tools, prompts, and resources without requiring you to disconnect and reconnect. When an MCP server sends a `list_changed` notification, Claude Code automatically refreshes the available capabilities from that server.

128 128

129### Automatic reconnection

130

131If an HTTP or SSE server disconnects mid-session, Claude Code automatically reconnects with exponential backoff: up to five attempts, starting at a one-second delay and doubling each time. The server appears as pending in `/mcp` while reconnection is in progress. After five failed attempts the server is marked as failed and you can retry manually from `/mcp`. Stdio servers are local processes and are not reconnected automatically.

132

129### Push messages with channels133### Push messages with channels

130 134

131An MCP server can also push messages directly into your session so Claude can react to external events like CI results, monitoring alerts, or chat messages. To enable this, your server declares the `claude/channel` capability and you opt it in with the `--channels` flag at startup. See [Channels](/en/channels) to use an officially supported channel, or [Channels reference](/en/channels-reference) to build your own.135An MCP server can also push messages directly into your session so Claude can react to external events like CI results, monitoring alerts, or chat messages. To enable this, your server declares the `claude/channel` capability and you opt it in with the `--channels` flag at startup. See [Channels](/en/channels) to use an officially supported channel, or [Channels reference](/en/channels-reference) to build your own.

559 563

560### Override OAuth metadata discovery564### Override OAuth metadata discovery

561 565

562If your MCP server's standard OAuth metadata endpoints return errors but the server exposes a working OIDC endpoint, you can point Claude Code at a specific metadata URL to bypass the default discovery chain. By default, Claude Code first checks RFC 9728 Protected Resource Metadata at `/.well-known/oauth-protected-resource`, then falls back to RFC 8414 authorization server metadata at `/.well-known/oauth-authorization-server`.566Point Claude Code at a specific OAuth authorization server metadata URL to bypass the default discovery chain. Set `authServerMetadataUrl` when the MCP server's standard endpoints error, or when you want to route discovery through an internal proxy. By default, Claude Code first checks RFC 9728 Protected Resource Metadata at `/.well-known/oauth-protected-resource`, then falls back to RFC 8414 authorization server metadata at `/.well-known/oauth-authorization-server`.

563 567

564Set `authServerMetadataUrl` in the `oauth` object of your server's config in `.mcp.json`:568Set `authServerMetadataUrl` in the `oauth` object of your server's config in `.mcp.json`:

565 569

577}581}

578```582```

579 583

580The URL must use `https://`. This option requires Claude Code v2.1.64 or later.584The URL must use `https://`. `authServerMetadataUrl` requires Claude Code v2.1.64 or later. The metadata URL's `scopes_supported` overrides the scopes the upstream server advertises.

585

586### Restrict OAuth scopes

587

588Set `oauth.scopes` to pin the scopes Claude Code requests during the authorization flow. This is the supported way to restrict an MCP server to a security-team-approved subset when the upstream authorization server advertises more scopes than you want to grant. The value is a single space-separated string, matching the `scope` parameter format in RFC 6749 §3.3.

589

590```json theme={null}

591{

592 "mcpServers": {

593 "slack": {

594 "type": "http",

595 "url": "https://mcp.slack.com/mcp",

596 "oauth": {

597 "scopes": "channels:read chat:write search:read"

598 }

599 }

600 }

601}

602```

603

604`oauth.scopes` takes precedence over both `authServerMetadataUrl` and the scopes the server discovers at `/.well-known`. Leave it unset to let the MCP server determine the requested scope set.

605

606If the authorization server advertises `offline_access` in `scopes_supported`, Claude Code appends it to the pinned scopes so the access token can be refreshed without a new browser sign-in.

607

608If the server later returns a 403 `insufficient_scope` for a tool call, Claude Code re-authenticates with the same pinned scopes. Widen `oauth.scopes` when a tool you need requires a scope outside the pin.

581 609

582### Use dynamic headers for custom authentication610### Use dynamic headers for custom authentication

583 611

705 733

706<Steps>734<Steps>

707 <Step title="Configure MCP servers in Claude.ai">735 <Step title="Configure MCP servers in Claude.ai">

708 Add servers at [claude.ai/settings/connectors](https://claude.ai/settings/connectors). On Team and Enterprise plans, only admins can add servers.736 Add servers at [claude.ai/customize/connectors](https://claude.ai/customize/connectors). On Team and Enterprise plans, only admins can add servers.

709 </Step>737 </Step>

710 738

711 <Step title="Authenticate the MCP server">739 <Step title="Authenticate the MCP server">

memory.md +1 −0

Details

402 402

403## Related resources403## Related resources

404 404

405* [Debug your configuration](/en/debug-your-config): diagnose why CLAUDE.md or settings aren't taking effect

405* [Skills](/en/skills): package repeatable workflows that load on demand406* [Skills](/en/skills): package repeatable workflows that load on demand

406* [Settings](/en/settings): configure Claude Code behavior with settings files407* [Settings](/en/settings): configure Claude Code behavior with settings files

407* [Subagent memory](/en/sub-agents#enable-persistent-memory): let subagents maintain their own auto memory408* [Subagent memory](/en/sub-agents#enable-persistent-memory): let subagents maintain their own auto memory

microsoft-foundry.md +4 −2

Details

85 Pin specific model versions for every deployment. If you use model aliases (`sonnet`, `opus`, `haiku`) without pinning, Claude Code may attempt to use a newer model version that isn't available in your Foundry account, breaking existing users when Anthropic releases updates. When you create Azure deployments, select a specific model version rather than "auto-update to latest."85 Pin specific model versions for every deployment. If you use model aliases (`sonnet`, `opus`, `haiku`) without pinning, Claude Code may attempt to use a newer model version that isn't available in your Foundry account, breaking existing users when Anthropic releases updates. When you create Azure deployments, select a specific model version rather than "auto-update to latest."

86</Warning>86</Warning>

87 87

~~88Set the model variables to match the deployment names you created in step 1:~~88Set the model variables to match the deployment names you created in step 1.

90Without `ANTHROPIC_DEFAULT_OPUS_MODEL`, the `opus` alias on Foundry resolves to Opus 4.6. Set it to the Opus 4.7 ID to use the latest model:

89 91

90```bash theme={null}92```bash theme={null}

~~91export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6'~~93export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-7'

92export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'94export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'

93export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'95export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'

94```96```

model-config.md +77 −33

Details

26| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |26| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

27| **`default`** | Special value that clears any model override and reverts to the recommended model for your account type. Not itself a model alias |27| **`default`** | Special value that clears any model override and reverts to the recommended model for your account type. Not itself a model alias |

28| **`best`** | Uses the most capable available model, currently equivalent to `opus` |28| **`best`** | Uses the most capable available model, currently equivalent to `opus` |

31| **`haiku`** | Uses the fast and efficient Haiku model for simple tasks |31| **`haiku`** | Uses the fast and efficient Haiku model for simple tasks |

32| **`sonnet[1m]`** | Uses Sonnet with a [1 million token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) for long sessions |32| **`sonnet[1m]`** | Uses Sonnet with a [1 million token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) for long sessions |

33| **`opus[1m]`** | Uses Opus with a [1 million token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) for long sessions |33| **`opus[1m]`** | Uses Opus with a [1 million token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) for long sessions |

34| **`opusplan`** | Special mode that uses `opus` during plan mode, then switches to `sonnet` for execution |34| **`opusplan`** | Special mode that uses `opus` during plan mode, then switches to `sonnet` for execution |

35 35

36Aliases always point to the latest version. To pin to a specific version, use the full model name (for example, `claude-opus-4-6`) or set the corresponding environment variable like `ANTHROPIC_DEFAULT_OPUS_MODEL`.36On the Anthropic API, `opus` resolves to Opus 4.7 and `sonnet` resolves to Sonnet 4.6. On Bedrock, Vertex, and Foundry, `opus` resolves to Opus 4.6 and `sonnet` resolves to Sonnet 4.5; newer models are available on those providers by selecting the full model name explicitly or setting `ANTHROPIC_DEFAULT_OPUS_MODEL` or `ANTHROPIC_DEFAULT_SONNET_MODEL`.

38Aliases point to the recommended version for your provider and update over time. To pin to a specific version, use the full model name (for example, `claude-opus-4-7`) or set the corresponding environment variable like `ANTHROPIC_DEFAULT_OPUS_MODEL`.

40<Note>

41 Opus 4.7 requires Claude Code v2.1.111 or later. Run `claude update` to upgrade.

42</Note>

37 43

38### Setting your model44### Setting your model

39 45

40You can configure your model in several ways, listed in order of priority:46You can configure your model in several ways, listed in order of priority:

41 47

~~421. **During session** - Use `/model <alias|name>` to switch models mid-session~~481. **During session** - Use `/model <alias|name>` to switch immediately, or run `/model` with no argument to open the picker. The picker asks for confirmation when the conversation has prior output, since the next response re-reads the full history without cached context

432. **At startup** - Launch with `claude --model <alias|name>`492. **At startup** - Launch with `claude --model <alias|name>`

443. **Environment variable** - Set `ANTHROPIC_MODEL=<alias|name>`503. **Environment variable** - Set `ANTHROPIC_MODEL=<alias|name>`

454. **Settings** - Configure permanently in your settings file using the `model`514. **Settings** - Configure permanently in your settings file using the `model`

122 128

123The behavior of `default` depends on your account type:129The behavior of `default` depends on your account type:

124 130

125* **Max and Team Premium**: defaults to Opus 4.6131* **Max and Team Premium**: defaults to Opus 4.7

126* **Pro and Team Standard**: defaults to Sonnet 4.6132* **Pro, Team Standard, Enterprise, and Anthropic API**: defaults to Sonnet 4.6

127* **Enterprise**: Opus 4.6 is available but not the default133* **Bedrock, Vertex, and Foundry**: defaults to Sonnet 4.5

128 134

129Claude Code may automatically fall back to Sonnet if you hit a usage threshold with Opus.135Claude Code may automatically fall back to Sonnet if you hit a usage threshold with Opus.

130 136

137<Note>

138 On April 23, 2026, the default model for Enterprise pay-as-you-go and Anthropic API users will change to Opus 4.7. To keep a different default, set `ANTHROPIC_MODEL` or the `model` field in [server-managed settings](/en/server-managed-settings).

139</Note>

140

131### `opusplan` model setting141### `opusplan` model setting

132 142

133The `opusplan` model alias provides an automated hybrid approach:143The `opusplan` model alias provides an automated hybrid approach:

140This gives you the best of both worlds: Opus's superior reasoning for planning,150This gives you the best of both worlds: Opus's superior reasoning for planning,

141and Sonnet's efficiency for execution.151and Sonnet's efficiency for execution.

142 152

153The plan-mode Opus phase runs with the standard 200K context window. The automatic 1M upgrade described in [Extended context](#extended-context) applies to the `opus` model setting and does not extend to `opusplan`.

154

143### Adjust effort level155### Adjust effort level

144 156

145[Effort levels](https://platform.claude.com/docs/en/build-with-claude/effort) control adaptive reasoning, which dynamically allocates thinking based on task complexity. Lower effort is faster and cheaper for straightforward tasks, while higher effort provides deeper reasoning for complex problems.157[Effort levels](https://platform.claude.com/docs/en/build-with-claude/effort) control adaptive reasoning, which lets the model decide whether and how much to think on each step based on task complexity. Lower effort is faster and cheaper for straightforward tasks, while higher effort provides deeper reasoning for complex problems.

158

159Effort is supported on Opus 4.7, Opus 4.6, and Sonnet 4.6. The available levels depend on the model:

160

161| Model | Levels |

162| :---------------------- | :-------------------------------------- |

163| Opus 4.7 | `low`, `medium`, `high`, `xhigh`, `max` |

164| Opus 4.6 and Sonnet 4.6 | `low`, `medium`, `high`, `max` |

146 165

147Three levels persist across sessions: **low**, **medium**, and **high**. A fourth level, **max**, provides the deepest reasoning with no constraint on token spending, so responses are slower and cost more than at `high`. `max` is available on Opus 4.6 only and does not persist across sessions except through the `CLAUDE_CODE_EFFORT_LEVEL` environment variable.166If you set a level the active model does not support, Claude Code falls back to the highest supported level at or below the one you set. For example, `xhigh` runs as `high` on Opus 4.6.

148 167

149The default effort level depends on your plan. Pro and Max subscribers default to medium effort. All other users default to high effort: API key, Team, Enterprise, and third-party provider (Bedrock, Vertex AI, Foundry) users.168On Opus 4.7, the default effort is `xhigh` for all plans and providers. On Opus 4.6 and Sonnet 4.6, the default is `high`, or `medium` on Pro and Max.

150 169

151Your plan's default suits most coding tasks. Raise effort for work that benefits from deeper reasoning, such as hard debugging problems or complex architectural decisions. Higher levels can cause the model to overthink routine work.170When you first run Opus 4.7, Claude Code applies `xhigh` even if you previously set a different effort level for Opus 4.6 or Sonnet 4.6. Run `/effort` again to choose a different level after switching.

152 171

153For one-off deep reasoning without changing your session setting, include "ultrathink" in your prompt to trigger high effort for that turn. This has no effect if your session is already at high or max.172`low`, `medium`, `high`, and `xhigh` persist across sessions. `max` provides the deepest reasoning with no constraint on token spending and applies to the current session only, except when set through the `CLAUDE_CODE_EFFORT_LEVEL` environment variable.

154 173

155**Setting effort:**174#### Choose an effort level

156 175

157* **`/effort`**: run `/effort low`, `/effort medium`, `/effort high`, or `/effort max` to change the level, or `/effort auto` to reset to the model default176Each level trades token spend against capability. The default suits most coding tasks; adjust when you want a different balance.

177

178| Level | When to use it |

179| :------- | :------------------------------------------------------------------------------------------------------------------------------------- |

180| `low` | Reserve for short, scoped, latency-sensitive tasks that are not intelligence-sensitive |

181| `medium` | Reduces token usage for cost-sensitive work that can trade off some intelligence |

182| `high` | Balances token usage and intelligence. Use as a minimum for intelligence-sensitive work, or to reduce token spend relative to `xhigh` |

183| `xhigh` | Best results for most coding and agentic tasks. Recommended default on Opus 4.7 |

184| `max` | Can improve performance on demanding tasks but may show diminishing returns and is prone to overthinking. Test before adopting broadly |

185

186The effort scale is calibrated per model, so the same level name does not represent the same underlying value across models.

187

188For one-off deep reasoning without changing your session setting, include "ultrathink" in your prompt. This adds an in-context instruction telling the model to reason more on that turn; it does not change the effort level sent to the API.

189

190#### Set the effort level

191

192You can change effort through any of the following:

193

194* **`/effort`**: run `/effort` with no arguments to open an interactive slider, `/effort` followed by a level name to set it directly, or `/effort auto` to reset to the model default

158* **In `/model`**: use left/right arrow keys to adjust the effort slider when selecting a model195* **In `/model`**: use left/right arrow keys to adjust the effort slider when selecting a model

159* **`--effort` flag**: pass `low`, `medium`, `high`, or `max` to set the level for a single session when launching Claude Code196* **`--effort` flag**: pass a level name to set it for a single session when launching Claude Code

160* **Environment variable**: set `CLAUDE_CODE_EFFORT_LEVEL` to `low`, `medium`, `high`, `max`, or `auto`197* **Environment variable**: set `CLAUDE_CODE_EFFORT_LEVEL` to a level name or `auto`

161* **Settings**: set `effortLevel` in your settings file to `"low"`, `"medium"`, or `"high"`198* **Settings**: set `effortLevel` in your settings file

162* **Skill and subagent frontmatter**: set `effort` in a [skill](/en/skills#frontmatter-reference) or [subagent](/en/sub-agents#supported-frontmatter-fields) markdown file to override the effort level when that skill or subagent runs199* **Skill and subagent frontmatter**: set `effort` in a [skill](/en/skills#frontmatter-reference) or [subagent](/en/sub-agents#supported-frontmatter-fields) markdown file to override the effort level when that skill or subagent runs

163 200

164The environment variable takes precedence over all other methods, then your configured level, then the model default. Frontmatter effort applies when that skill or subagent is active, overriding the session level but not the environment variable.201The environment variable takes precedence over all other methods, then your configured level, then the model default. Frontmatter effort applies when that skill or subagent is active, overriding the session level but not the environment variable.

165 202

166Effort is supported on Opus 4.6 and Sonnet 4.6. The effort slider appears in `/model` when a supported model is selected. The current effort level is also displayed next to the logo and spinner, for example "with low effort", so you can confirm which setting is active without opening `/model`.203The effort slider appears in `/model` when a supported model is selected. The current effort level is also displayed next to the logo and spinner, for example "with low effort", so you can confirm which setting is active without opening `/model`.

204

205#### Adaptive reasoning and fixed thinking budgets

206

207Adaptive reasoning makes thinking optional on each step, so Claude can respond faster to routine prompts and reserve deeper thinking for steps that benefit from it. If you want Claude to think more or less often than the current level produces, you can say so directly in your prompt or in `CLAUDE.md`; the model responds to that guidance within its effort setting.

208

209Opus 4.7 always uses adaptive reasoning. The fixed thinking budget mode and `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` do not apply to it.

167 210

168To disable adaptive reasoning on Opus 4.6 and Sonnet 4.6 and revert to the previous fixed thinking budget, set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`. When disabled, these models use the fixed budget controlled by `MAX_THINKING_TOKENS`. See [environment variables](/en/env-vars).211On Opus 4.6 and Sonnet 4.6, you can set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` to revert to the previous fixed thinking budget controlled by `MAX_THINKING_TOKENS`. See [environment variables](/en/env-vars).

169 212

170### Extended context213### Extended context

171 214

172Opus 4.6 and Sonnet 4.6 support a [1 million token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) for long sessions with large codebases.215Opus 4.7, Opus 4.6, and Sonnet 4.6 support a [1 million token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) for long sessions with large codebases.

173 216

174Availability varies by model and plan. On Max, Team, and Enterprise plans, Opus is automatically upgraded to 1M context with no additional configuration. This applies to both Team Standard and Team Premium seats.217Availability varies by model and plan. On Max, Team, and Enterprise plans, Opus is automatically upgraded to 1M context with no additional configuration. This applies to both Team Standard and Team Premium seats.

175 218

177| ------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |220| ------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |

179| Pro | Requires [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) | Requires [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |222| Pro | Requires [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) | Requires [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

193/model sonnet[1m]236/model sonnet[1m]

194 237

195# Or append [1m] to a full model name238# Or append [1m] to a full model name

196/model claude-opus-4-6[1m]239/model claude-opus-4-7[1m]

197```240```

198 241

199## Checking your current model242## Checking your current model

210This example sets all three variables to make a gateway-routed Opus deployment selectable:253This example sets all three variables to make a gateway-routed Opus deployment selectable:

211 254

212```bash theme={null}255```bash theme={null}

213export ANTHROPIC_CUSTOM_MODEL_OPTION="my-gateway/claude-opus-4-6"256export ANTHROPIC_CUSTOM_MODEL_OPTION="my-gateway/claude-opus-4-7"

214export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Opus via Gateway"257export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Opus via Gateway"

215export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Custom deployment routed through the internal LLM gateway"258export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Custom deployment routed through the internal LLM gateway"

216```259```

247Use the following environment variables with version-specific model IDs for your provider:290Use the following environment variables with version-specific model IDs for your provider:

248 291

249| Provider | Example |292| Provider | Example |

250| :-------- | :---------------------------------------------------------------------- |293| :-------- | :------------------------------------------------------------------- |

254 297

255Apply the same pattern for `ANTHROPIC_DEFAULT_SONNET_MODEL` and `ANTHROPIC_DEFAULT_HAIKU_MODEL`. For current and legacy model IDs across all providers, see [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). To upgrade users to a new model version, update these environment variables and redeploy.298Apply the same pattern for `ANTHROPIC_DEFAULT_SONNET_MODEL` and `ANTHROPIC_DEFAULT_HAIKU_MODEL`. For current and legacy model IDs across all providers, see [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). To upgrade users to a new model version, update these environment variables and redeploy.

256 299

257To enable [extended context](#extended-context) for a pinned model, append `[1m]` to the model ID in `ANTHROPIC_DEFAULT_OPUS_MODEL` or `ANTHROPIC_DEFAULT_SONNET_MODEL`:300To enable [extended context](#extended-context) for a pinned model, append `[1m]` to the model ID in `ANTHROPIC_DEFAULT_OPUS_MODEL` or `ANTHROPIC_DEFAULT_SONNET_MODEL`:

258 301

259```bash theme={null}302```bash theme={null}

260export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6[1m]'303export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-7[1m]'

261```304```

262 305

263The `[1m]` suffix applies the 1M context window to all usage of that alias, including `opusplan`. Claude Code strips the suffix before sending the model ID to your provider. Only append `[1m]` when the underlying model supports 1M context, such as Opus 4.6 or Sonnet 4.6.306The `[1m]` suffix applies the 1M context window to all usage of that alias, including `opusplan`. Claude Code strips the suffix before sending the model ID to your provider. Only append `[1m]` when the underlying model supports 1M context, such as Opus 4.7 or Sonnet 4.6.

264 307

265<Note>308<Note>

266 The `settings.availableModels` allowlist still applies when using third-party providers. Filtering matches on the model alias (`opus`, `sonnet`, `haiku`), not the provider-specific model ID.309 The `settings.availableModels` allowlist still applies when using third-party providers. Filtering matches on the model alias (`opus`, `sonnet`, `haiku`), not the provider-specific model ID.

285| Capability value | Enables |328| Capability value | Enables |

286| ---------------------- | ------------------------------------------------------------------------------- |329| ---------------------- | ------------------------------------------------------------------------------- |

331| `xhigh_effort` | {/* min-version: 2.1.111 */}The `xhigh` effort level |

297```bash theme={null}341```bash theme={null}

298export ANTHROPIC_DEFAULT_OPUS_MODEL='arn:aws:bedrock:us-east-1:123456789012:custom-model/abc'342export ANTHROPIC_DEFAULT_OPUS_MODEL='arn:aws:bedrock:us-east-1:123456789012:custom-model/abc'

299export ANTHROPIC_DEFAULT_OPUS_MODEL_NAME='Opus via Bedrock'343export ANTHROPIC_DEFAULT_OPUS_MODEL_NAME='Opus via Bedrock'

300export ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION='Opus 4.6 routed through a Bedrock custom endpoint'344export ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION='Opus 4.7 routed through a Bedrock custom endpoint'

301export ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES='effort,max_effort,thinking,adaptive_thinking,interleaved_thinking'345export ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES='effort,xhigh_effort,max_effort,thinking,adaptive_thinking,interleaved_thinking'

302```346```

303 347

304### Override model IDs per version348### Override model IDs per version

314```json theme={null}358```json theme={null}

315{359{

316 "modelOverrides": {360 "modelOverrides": {

317 "claude-opus-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-prod",361 "claude-opus-4-7": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-prod",

318 "claude-opus-4-5-20251101": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-45-prod",362 "claude-opus-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-46-prod",

319 "claude-sonnet-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-prod"363 "claude-sonnet-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-prod"

320 }364 }

321}365}

monitoring-usage.md +318 −8

Details

69### Common configuration variables69### Common configuration variables

70 70

72| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |72| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |

73| `CLAUDE_CODE_ENABLE_TELEMETRY` | Enables telemetry collection (required) | `1` |73| `CLAUDE_CODE_ENABLE_TELEMETRY` | Enables telemetry collection (required) | `1` |

88| `OTEL_LOG_TOOL_DETAILS` | Enable logging of tool parameters and input arguments in tool events and trace span attributes: Bash commands, MCP server and tool names, skill names, and tool input (default: disabled) | `1` to enable |88| `OTEL_LOG_TOOL_DETAILS` | Enable logging of tool parameters and input arguments in tool events and trace span attributes: Bash commands, MCP server and tool names, skill names, and tool input (default: disabled) | `1` to enable |

89| `OTEL_LOG_TOOL_CONTENT` | Enable logging of tool input and output content in span events (default: disabled). Requires [tracing](#traces-beta). Content is truncated at 60 KB | `1` to enable |89| `OTEL_LOG_TOOL_CONTENT` | Enable logging of tool input and output content in span events (default: disabled). Requires [tracing](#traces-beta). Content is truncated at 60 KB | `1` to enable |

90| `OTEL_LOG_RAW_API_BODIES` | Emit the full Anthropic Messages API request and response JSON as `api_request_body` / `api_response_body` log events (default: disabled). Bodies include the entire conversation history. Enabling this implies consent to everything `OTEL_LOG_USER_PROMPTS`, `OTEL_LOG_TOOL_DETAILS`, and `OTEL_LOG_TOOL_CONTENT` would reveal | `1` for inline bodies truncated at 60 KB, or `file:<dir>` for untruncated bodies on disk with a `body_ref` pointer in the event |

90| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | Metrics temporality preference (default: `delta`). Set to `cumulative` if your backend expects cumulative temporality | `delta`, `cumulative` |91| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | Metrics temporality preference (default: `delta`). Set to `cumulative` if your backend expects cumulative temporality | `delta`, `cumulative` |

91| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Interval for refreshing dynamic headers (default: 1740000ms / 29 minutes) | `900000` |92| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Interval for refreshing dynamic headers (default: 1740000ms / 29 minutes) | `900000` |

92 93

120 121

121When tracing is active, Bash and PowerShell subprocesses automatically inherit a `TRACEPARENT` environment variable containing the W3C trace context of the active tool execution span. This lets any subprocess that reads `TRACEPARENT` parent its own spans under the same trace, enabling end-to-end distributed tracing through scripts and commands that Claude runs.122When tracing is active, Bash and PowerShell subprocesses automatically inherit a `TRACEPARENT` environment variable containing the W3C trace context of the active tool execution span. This lets any subprocess that reads `TRACEPARENT` parent its own spans under the same trace, enabling end-to-end distributed tracing through scripts and commands that Claude runs.

122 123

124In Agent SDK and non-interactive sessions started with `-p`, Claude Code also reads `TRACEPARENT` and `TRACESTATE` from its own environment when starting each interaction span. This lets an embedding process pass its active W3C trace context into the subprocess so Claude Code's spans appear as children of the caller's distributed trace. Interactive sessions ignore inbound `TRACEPARENT` to avoid accidentally inheriting ambient values from CI or container environments.

125

126#### Span hierarchy

127

128Each user prompt starts a `claude_code.interaction` root span. API calls, tool calls, and hook executions are recorded as its children. Tool spans have two child spans of their own: one for the time spent waiting on a permission decision and one for the execution itself. When the Task tool spawns a subagent, the subagent's API and tool spans nest under the parent's `claude_code.tool` span.

129

130```text theme={null}

131claude_code.interaction

132├── claude_code.llm_request

133├── claude_code.hook (requires detailed beta tracing)

134└── claude_code.tool

135 ├── claude_code.tool.blocked_on_user

136 ├── claude_code.tool.execution

137 └── (Task tool) subagent claude_code.llm_request / claude_code.tool spans

138```

139

140In Agent SDK and `claude -p` sessions, `claude_code.interaction` itself becomes a child of the caller's span when `TRACEPARENT` is set in the environment.

141

142#### Span attributes

143

144Every span carries the [standard attributes](#standard-attributes) plus a `span.type` attribute matching its name. The tables below list the additional attributes set on each span. The `llm_request`, `tool.execution`, and `hook` spans set OpenTelemetry status `ERROR` when they record a failure; the other spans always end with status `UNSET`.

145

146**`claude_code.interaction`**

147

148| Attribute | Description | Gated by |

149| ------------------------- | --------------------------------------------------------- | ----------------------- |

150| `user_prompt` | Prompt text. Value is `<REDACTED>` unless the gate is set | `OTEL_LOG_USER_PROMPTS` |

151| `user_prompt_length` | Prompt length in characters | |

152| `interaction.sequence` | 1-based counter of interactions in this session | |

153| `interaction.duration_ms` | Wall-clock duration of the turn | |

154

155**`claude_code.llm_request`**

156

157| Attribute | Description | Gated by |

158| ------------------------ | -------------------------------------------------------------------------------- | -------- |

159| `model` | Model identifier | |

160| `gen_ai.system` | Always `anthropic`. OpenTelemetry GenAI semantic convention | |

161| `gen_ai.request.model` | Same value as `model`. OpenTelemetry GenAI semantic convention | |

162| `query_source` | Subsystem that issued the request, such as `repl_main_thread` or a subagent name | |

163| `speed` | `fast` or `normal` | |

164| `llm_request.context` | `interaction`, `tool`, or `standalone` depending on the parent span | |

165| `duration_ms` | Wall-clock duration including retries | |

166| `ttft_ms` | Time to first token in milliseconds | |

167| `input_tokens` | Input token count from the API usage block | |

168| `output_tokens` | Output token count | |

169| `cache_read_tokens` | Tokens read from prompt cache | |

170| `cache_creation_tokens` | Tokens written to prompt cache | |

171| `request_id` | Anthropic API request ID from the `request-id` response header | |

172| `gen_ai.response.id` | Same value as `request_id`. OpenTelemetry GenAI semantic convention | |

173| `client_request_id` | Client-generated `x-client-request-id` of the final attempt | |

174| `attempt` | Total attempts made for this request | |

175| `success` | `true` or `false` | |

176| `status_code` | HTTP status code when the request failed | |

177| `error` | Error message when the request failed | |

178| `response.has_tool_call` | `true` when the response contained tool-use blocks | |

179

180Each retry attempt is also recorded as a `gen_ai.request.attempt` span event with `attempt` and `client_request_id` attributes.

181

182**`claude_code.tool`**

183

184| Attribute | Description | Gated by |

185| --------------- | ----------------------------------------------------------- | ----------------------- |

186| `tool_name` | Tool name | |

187| `duration_ms` | Wall-clock duration including permission wait and execution | |

188| `result_tokens` | Approximate token size of the tool result | |

189| `file_path` | Target file path for Read, Edit, and Write tools | `OTEL_LOG_TOOL_DETAILS` |

190| `full_command` | Command string for the Bash tool | `OTEL_LOG_TOOL_DETAILS` |

191| `skill_name` | Skill name for the Skill tool | `OTEL_LOG_TOOL_DETAILS` |

192| `subagent_type` | Subagent type for the Task tool | `OTEL_LOG_TOOL_DETAILS` |

193

194When `OTEL_LOG_TOOL_CONTENT=1`, this span also records a `tool.output` span event whose attributes contain the tool's input and output bodies, truncated at 60 KB per attribute.

195

196**`claude_code.tool.blocked_on_user`**

197

198| Attribute | Description | Gated by |

199| ------------- | --------------------------------------------------- | -------- |

200| `duration_ms` | Time spent waiting for the permission decision | |

201| `decision` | `accept` or `reject` | |

202| `source` | Decision source, matching the `tool_decision` event | |

203

204**`claude_code.tool.execution`**

205

206| Attribute | Description | Gated by |

207| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |

208| `duration_ms` | Time spent running the tool body | |

209| `success` | `true` or `false` | |

210| `error` | Error category string when execution failed, such as `Error:ENOENT` or `ShellError`. Contains the full error message instead when the gate is set | `OTEL_LOG_TOOL_DETAILS` |

211

212**`claude_code.hook`**

213

214This span is emitted only when detailed beta tracing is active, which requires `ENABLE_BETA_TRACING_DETAILED=1` and `BETA_TRACING_ENDPOINT` in addition to the trace exporter configuration above. In interactive CLI sessions, this also requires your organization to be allowlisted for the feature. Agent SDK and non-interactive `-p` sessions are not gated. It is not emitted when only `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` is set.

215

216| Attribute | Description | Gated by |

217| ------------------------ | ------------------------------------------------ | ----------------------- |

218| `hook_event` | Hook event type, such as `PreToolUse` | |

219| `hook_name` | Full hook name, such as `PreToolUse:Write` | |

220| `num_hooks` | Number of matching hook commands executed | |

221| `hook_definitions` | JSON-serialized hook configuration | `OTEL_LOG_TOOL_DETAILS` |

222| `duration_ms` | Wall-clock duration of all matching hooks | |

223| `num_success` | Count of hooks that completed successfully | |

224| `num_blocking` | Count of hooks that returned a blocking decision | |

225| `num_non_blocking_error` | Count of hooks that failed without blocking | |

226| `num_cancelled` | Count of hooks cancelled before completion | |

227

228<Note>

229 Additional content-bearing attributes such as `new_context`, `system_prompt_preview`, `tool_input`, and `response.model_output` are emitted only when detailed beta tracing is active. They are not part of the stable span schema.

230</Note>

231

123### Dynamic headers232### Dynamic headers

124 233

125For enterprise environments that require dynamic authentication, you can configure a script to generate headers dynamically:234For enterprise environments that require dynamic authentication, you can configure a script to generate headers dynamically:

286**Attributes**:395**Attributes**:

287 396

288* All [standard attributes](#standard-attributes)397* All [standard attributes](#standard-attributes)

398* `start_type`: How the session was started. One of `"fresh"`, `"resume"`, or `"continue"`

289 399

290#### Lines of code counter400#### Lines of code counter

291 401

320 430

321* All [standard attributes](#standard-attributes)431* All [standard attributes](#standard-attributes)

322* `model`: Model identifier (for example, "claude-sonnet-4-6")432* `model`: Model identifier (for example, "claude-sonnet-4-6")

433* `query_source`: Category of the subsystem that issued the request. One of `"main"`, `"subagent"`, or `"auxiliary"`

434* `speed`: `"fast"` when the request used fast mode. Absent otherwise

323 435

324#### Token counter436#### Token counter

325 437

330* All [standard attributes](#standard-attributes)442* All [standard attributes](#standard-attributes)

331* `type`: (`"input"`, `"output"`, `"cacheRead"`, `"cacheCreation"`)443* `type`: (`"input"`, `"output"`, `"cacheRead"`, `"cacheCreation"`)

332* `model`: Model identifier (for example, "claude-sonnet-4-6")444* `model`: Model identifier (for example, "claude-sonnet-4-6")

445* `query_source`: Category of the subsystem that issued the request. One of `"main"`, `"subagent"`, or `"auxiliary"`

446* `speed`: `"fast"` when the request used fast mode. Absent otherwise

333 447

334#### Code edit tool decision counter448#### Code edit tool decision counter

335 449

400* `tool_name`: Name of the tool514* `tool_name`: Name of the tool

401* `success`: `"true"` or `"false"`515* `success`: `"true"` or `"false"`

402* `duration_ms`: Execution time in milliseconds516* `duration_ms`: Execution time in milliseconds

403* `error`: Error message (if failed)517* `error_type`: Error category string when the tool failed, such as `"Error:ENOENT"` or `"ShellError"`

518* `error` (when `OTEL_LOG_TOOL_DETAILS=1`): Full error message when the tool failed

404* `decision_type`: Either `"accept"` or `"reject"`519* `decision_type`: Either `"accept"` or `"reject"`

405* `decision_source`: Decision source - `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`520* `decision_source`: Decision source - `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`

406* `tool_result_size_bytes`: Size of the tool result in bytes521* `tool_result_size_bytes`: Size of the tool result in bytes

409 * For Bash tool: includes `bash_command`, `full_command`, `timeout`, `description`, `dangerouslyDisableSandbox`, and `git_commit_id` (the commit SHA, when a `git commit` command succeeds)524 * For Bash tool: includes `bash_command`, `full_command`, `timeout`, `description`, `dangerouslyDisableSandbox`, and `git_commit_id` (the commit SHA, when a `git commit` command succeeds)

410 * For MCP tools: includes `mcp_server_name`, `mcp_tool_name`525 * For MCP tools: includes `mcp_server_name`, `mcp_tool_name`

411 * For Skill tool: includes `skill_name`526 * For Skill tool: includes `skill_name`

527 * For Task tool: includes `subagent_type`

412* `tool_input` (when `OTEL_LOG_TOOL_DETAILS=1`): JSON-serialized tool arguments. Individual values over 512 characters are truncated, and the full payload is bounded to \~4 K characters. Applies to all tools including MCP tools.528* `tool_input` (when `OTEL_LOG_TOOL_DETAILS=1`): JSON-serialized tool arguments. Individual values over 512 characters are truncated, and the full payload is bounded to \~4 K characters. Applies to all tools including MCP tools.

413 529

414#### API request event530#### API request event

430* `output_tokens`: Number of output tokens546* `output_tokens`: Number of output tokens

431* `cache_read_tokens`: Number of tokens read from cache547* `cache_read_tokens`: Number of tokens read from cache

432* `cache_creation_tokens`: Number of tokens used for cache creation548* `cache_creation_tokens`: Number of tokens used for cache creation

549* `request_id`: Anthropic API request ID from the response's `request-id` header, such as `"req_011..."`. Present only when the API returns one.

433* `speed`: `"fast"` or `"normal"`, indicating whether fast mode was active550* `speed`: `"fast"` or `"normal"`, indicating whether fast mode was active

551* `query_source`: Subsystem that issued the request, such as `"repl_main_thread"`, `"compact"`, or a subagent name

434 552

435#### API error event553#### API error event

436 554

449* `status_code`: HTTP status code as a string, or `"undefined"` for non-HTTP errors567* `status_code`: HTTP status code as a string, or `"undefined"` for non-HTTP errors

450* `duration_ms`: Request duration in milliseconds568* `duration_ms`: Request duration in milliseconds

451* `attempt`: Total number of attempts made, including the initial request (`1` means no retries occurred)569* `attempt`: Total number of attempts made, including the initial request (`1` means no retries occurred)

570* `request_id`: Anthropic API request ID from the response's `request-id` header, such as `"req_011..."`. Present only when the API returns one.

452* `speed`: `"fast"` or `"normal"`, indicating whether fast mode was active571* `speed`: `"fast"` or `"normal"`, indicating whether fast mode was active

572* `query_source`: Subsystem that issued the request, such as `"repl_main_thread"`, `"compact"`, or a subagent name

573

574#### API request body event

575

576Logged for each API request attempt when `OTEL_LOG_RAW_API_BODIES` is set. One event is emitted per attempt, so retries with adjusted parameters each produce their own event.

577

578**Event Name**: `claude_code.api_request_body`

579

580**Attributes**:

581

582* All [standard attributes](#standard-attributes)

583* `event.name`: `"api_request_body"`

584* `event.timestamp`: ISO 8601 timestamp

585* `event.sequence`: monotonically increasing counter for ordering events within a session

586* `body`: JSON-serialized Messages API request parameters (system prompt, messages, tools, etc.), truncated at 60 KB. Extended-thinking content in prior assistant turns is redacted. Emitted only in inline mode (`OTEL_LOG_RAW_API_BODIES=1`).

587* `body_ref`: Absolute path to a `<dir>/<uuid>.request.json` file containing the untruncated body. Emitted only in file mode (`OTEL_LOG_RAW_API_BODIES=file:<dir>`).

588* `body_length`: Untruncated body length. UTF-8 bytes when `OTEL_LOG_RAW_API_BODIES=file:<dir>`, or UTF-16 code units when `=1`

589* `body_truncated`: `"true"` when inline truncation occurred. Absent in file mode and when no truncation occurred.

590* `model`: Model identifier from the request parameters

591* `query_source`: Subsystem that issued the request (for example, `"compact"`)

592

593#### API response body event

594

595Logged for each successful API response when `OTEL_LOG_RAW_API_BODIES` is set.

596

597**Event Name**: `claude_code.api_response_body`

598

599**Attributes**:

600

601* All [standard attributes](#standard-attributes)

602* `event.name`: `"api_response_body"`

603* `event.timestamp`: ISO 8601 timestamp

604* `event.sequence`: monotonically increasing counter for ordering events within a session

605* `body`: JSON-serialized Messages API response (id, content blocks, usage, stop reason), truncated at 60 KB. Extended-thinking content is redacted. Emitted only in inline mode (`OTEL_LOG_RAW_API_BODIES=1`).

606* `body_ref`: Absolute path to a `<dir>/<request_id>.response.json` file containing the untruncated body. Emitted only in file mode (`OTEL_LOG_RAW_API_BODIES=file:<dir>`).

607* `body_length`: Untruncated body length. UTF-8 bytes when `OTEL_LOG_RAW_API_BODIES=file:<dir>`, or UTF-16 code units when `=1`

608* `body_truncated`: `"true"` when inline truncation occurred. Absent in file mode and when no truncation occurred.

609* `model`: Model identifier

610* `query_source`: Subsystem that issued the request

611* `request_id`: Anthropic API request ID from the response's `request-id` header, such as `"req_011..."`. Present only when the API returns one.

453 612

454#### Tool decision event613#### Tool decision event

455 614

467* `decision`: Either `"accept"` or `"reject"`626* `decision`: Either `"accept"` or `"reject"`

468* `source`: Decision source - `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`627* `source`: Decision source - `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`

469 628

629#### Permission mode changed event

630

631Logged when the permission mode changes, for example from `Shift+Tab` cycling, exiting plan mode, or an auto mode gate check.

632

633**Event Name**: `claude_code.permission_mode_changed`

634

635**Attributes**:

636

637* All [standard attributes](#standard-attributes)

638* `event.name`: `"permission_mode_changed"`

639* `event.timestamp`: ISO 8601 timestamp

640* `event.sequence`: monotonically increasing counter for ordering events within a session

641* `from_mode`: The previous permission mode, for example `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, or `"bypassPermissions"`

642* `to_mode`: The new permission mode

643* `trigger`: What caused the change. One of `"shift_tab"`, `"exit_plan_mode"`, `"auto_gate_denied"`, or `"auto_opt_in"`. Absent when the transition originates from the SDK or bridge

644

645#### Auth event

646

647Logged when `/login` or `/logout` completes.

648

649**Event Name**: `claude_code.auth`

650

651**Attributes**:

652

653* All [standard attributes](#standard-attributes)

654* `event.name`: `"auth"`

655* `event.timestamp`: ISO 8601 timestamp

656* `event.sequence`: monotonically increasing counter for ordering events within a session

657* `action`: `"login"` or `"logout"`

658* `success`: `"true"` or `"false"`

659* `auth_method`: Authentication method, such as `"oauth"`

660* `error_category`: Categorical error kind when the action failed. The raw error message is never included

661* `status_code`: HTTP status code as a string when the action failed with an HTTP error

662

663#### MCP server connection event

664

665Logged when an MCP server connects, disconnects, or fails to connect.

666

667**Event Name**: `claude_code.mcp_server_connection`

668

669**Attributes**:

670

671* All [standard attributes](#standard-attributes)

672* `event.name`: `"mcp_server_connection"`

673* `event.timestamp`: ISO 8601 timestamp

674* `event.sequence`: monotonically increasing counter for ordering events within a session

675* `status`: `"connected"`, `"failed"`, or `"disconnected"`

676* `transport_type`: Server transport, such as `"stdio"`, `"sse"`, or `"http"`

677* `server_scope`: Scope the server is configured at, such as `"user"`, `"project"`, or `"local"`

678* `duration_ms`: Connection attempt duration in milliseconds

679* `error_code`: Error code when the connection failed

680* `server_name` (when `OTEL_LOG_TOOL_DETAILS=1`): Configured server name

681* `error` (when `OTEL_LOG_TOOL_DETAILS=1`): Full error message when the connection failed

682

683#### Internal error event

684

685Logged when Claude Code catches an unexpected internal error. Only the error class name and an errno-style code are recorded. The error message and stack trace are never included. This event is not emitted when running against Bedrock, Vertex, or Foundry, or when `DISABLE_ERROR_REPORTING` is set.

686

687**Event Name**: `claude_code.internal_error`

688

689**Attributes**:

690

691* All [standard attributes](#standard-attributes)

692* `event.name`: `"internal_error"`

693* `event.timestamp`: ISO 8601 timestamp

694* `event.sequence`: monotonically increasing counter for ordering events within a session

695* `error_name`: Error class name, such as `"TypeError"` or `"SyntaxError"`

696* `error_code`: Node.js errno code such as `"ENOENT"` when present on the error

697

470#### Plugin installed event698#### Plugin installed event

471 699

472Logged when a plugin finishes installing, from both the `claude plugin install` CLI command and the interactive `/plugin` UI.700Logged when a plugin finishes installing, from both the `claude plugin install` CLI command and the interactive `/plugin` UI.

479* `event.name`: `"plugin_installed"`707* `event.name`: `"plugin_installed"`

480* `event.timestamp`: ISO 8601 timestamp708* `event.timestamp`: ISO 8601 timestamp

481* `event.sequence`: monotonically increasing counter for ordering events within a session709* `event.sequence`: monotonically increasing counter for ordering events within a session

482* `plugin.name`: Name of the installed plugin

483* `plugin.version`: Plugin version when declared in the marketplace entry

484* `marketplace.name`: Marketplace the plugin was installed from

485* `marketplace.is_official`: `"true"` if the marketplace is an official Anthropic marketplace, `"false"` otherwise710* `marketplace.is_official`: `"true"` if the marketplace is an official Anthropic marketplace, `"false"` otherwise

486* `install.trigger`: `"cli"` or `"ui"`711* `install.trigger`: `"cli"` or `"ui"`

712* `plugin.name`: Name of the installed plugin. For third-party marketplaces this is included only when `OTEL_LOG_TOOL_DETAILS=1`

713* `plugin.version`: Plugin version when declared in the marketplace entry. For third-party marketplaces this is included only when `OTEL_LOG_TOOL_DETAILS=1`

714* `marketplace.name`: Marketplace the plugin was installed from. For third-party marketplaces this is included only when `OTEL_LOG_TOOL_DETAILS=1`

487 715

488#### Skill activated event716#### Skill activated event

489 717

497* `event.name`: `"skill_activated"`725* `event.name`: `"skill_activated"`

498* `event.timestamp`: ISO 8601 timestamp726* `event.timestamp`: ISO 8601 timestamp

499* `event.sequence`: monotonically increasing counter for ordering events within a session727* `event.sequence`: monotonically increasing counter for ordering events within a session

500* `skill.name`: Name of the skill728* `skill.name`: Name of the skill. For user-defined and third-party plugin skills the value is the placeholder `"custom_skill"` unless `OTEL_LOG_TOOL_DETAILS=1`

501* `skill.source`: Where the skill was loaded from (for example, `"bundled"`, `"userSettings"`, `"projectSettings"`, `"plugin"`)729* `skill.source`: Where the skill was loaded from (for example, `"bundled"`, `"userSettings"`, `"projectSettings"`, `"plugin"`)

502* `plugin.name`: Name of the owning plugin when the skill is provided by a plugin730* `plugin.name` (when `OTEL_LOG_TOOL_DETAILS=1` or the plugin is from an official marketplace): Name of the owning plugin when the skill is provided by a plugin

503* `marketplace.name`: Marketplace the owning plugin was installed from, when the skill is provided by a plugin731* `marketplace.name` (when `OTEL_LOG_TOOL_DETAILS=1` or the plugin is from an official marketplace): Marketplace the owning plugin was installed from, when the skill is provided by a plugin

732

733#### API retries exhausted event

734

735Logged once when an API request fails after more than one attempt. Emitted alongside the final `api_error` event.

736

737**Event Name**: `claude_code.api_retries_exhausted`

738

739**Attributes**:

740

741* All [standard attributes](#standard-attributes)

742* `event.name`: `"api_retries_exhausted"`

743* `event.timestamp`: ISO 8601 timestamp

744* `event.sequence`: monotonically increasing counter for ordering events within a session

745* `model`: Model used

746* `error`: Final error message

747* `status_code`: HTTP status code as a string

748* `total_attempts`: Total number of attempts made

749* `total_retry_duration_ms`: Total wall-clock time across all attempts

750* `speed`: `"fast"` or `"normal"`

751

752#### Hook execution start event

753

754Logged when one or more hooks begin executing for a hook event.

755

756**Event Name**: `claude_code.hook_execution_start`

757

758**Attributes**:

759

760* All [standard attributes](#standard-attributes)

761* `event.name`: `"hook_execution_start"`

762* `event.timestamp`: ISO 8601 timestamp

763* `event.sequence`: monotonically increasing counter for ordering events within a session

764* `hook_event`: Hook event type, such as `"PreToolUse"` or `"PostToolUse"`

765* `hook_name`: Full hook name including matcher, such as `"PreToolUse:Write"`

766* `num_hooks`: Number of matching hook commands

767* `managed_only`: `"true"` when only managed-policy hooks are permitted

768* `hook_source`: `"policySettings"` or `"merged"`

769* `hook_definitions`: JSON-serialized hook configuration. Included only when both detailed beta tracing and `OTEL_LOG_TOOL_DETAILS=1` are enabled

770

771#### Hook execution complete event

772

773Logged when all hooks for a hook event have finished.

774

775**Event Name**: `claude_code.hook_execution_complete`

776

777**Attributes**:

778

779* All [standard attributes](#standard-attributes)

780* `event.name`: `"hook_execution_complete"`

781* `event.timestamp`: ISO 8601 timestamp

782* `event.sequence`: monotonically increasing counter for ordering events within a session

783* `hook_event`: Hook event type

784* `hook_name`: Full hook name including matcher

785* `num_hooks`: Number of matching hook commands

786* `num_success`: Count that completed successfully

787* `num_blocking`: Count that returned a blocking decision

788* `num_non_blocking_error`: Count that failed without blocking

789* `num_cancelled`: Count cancelled before completion

790* `total_duration_ms`: Wall-clock duration of all matching hooks

791* `managed_only`: `"true"` when only managed-policy hooks are permitted

792* `hook_source`: `"policySettings"` or `"merged"`

793* `hook_definitions`: JSON-serialized hook configuration. Included only when both detailed beta tracing and `OTEL_LOG_TOOL_DETAILS=1` are enabled

794

795#### Compaction event

796

797Logged when conversation compaction completes.

798

799**Event Name**: `claude_code.compaction`

800

801**Attributes**:

802

803* All [standard attributes](#standard-attributes)

804* `event.name`: `"compaction"`

805* `event.timestamp`: ISO 8601 timestamp

806* `event.sequence`: monotonically increasing counter for ordering events within a session

807* `trigger`: `"auto"` or `"manual"`

808* `success`: `"true"` or `"false"`

809* `duration_ms`: Compaction duration

810* `pre_tokens`: Approximate token count before compaction

811* `post_tokens`: Approximate token count after compaction

812* `error`: Error message when compaction failed

504 813

505## Interpret metrics and events data814## Interpret metrics and events data

506 815

606* User prompt content is not collected by default. Only prompt length is recorded. To include prompt content, set `OTEL_LOG_USER_PROMPTS=1`915* User prompt content is not collected by default. Only prompt length is recorded. To include prompt content, set `OTEL_LOG_USER_PROMPTS=1`

607* Tool input arguments and parameters are not logged by default. To include them, set `OTEL_LOG_TOOL_DETAILS=1`. When enabled, `tool_result` events include a `tool_parameters` attribute with Bash commands, MCP server and tool names, and skill names, plus a `tool_input` attribute with file paths, URLs, search patterns, and other arguments. Trace spans include the same `tool_input` attribute and input-derived attributes such as `file_path`. Individual values over 512 characters are truncated and the total is bounded to \~4 K characters, but the arguments may still contain sensitive values. Configure your telemetry backend to filter or redact these attributes as needed916* Tool input arguments and parameters are not logged by default. To include them, set `OTEL_LOG_TOOL_DETAILS=1`. When enabled, `tool_result` events include a `tool_parameters` attribute with Bash commands, MCP server and tool names, and skill names, plus a `tool_input` attribute with file paths, URLs, search patterns, and other arguments. Trace spans include the same `tool_input` attribute and input-derived attributes such as `file_path`. Individual values over 512 characters are truncated and the total is bounded to \~4 K characters, but the arguments may still contain sensitive values. Configure your telemetry backend to filter or redact these attributes as needed

608* Tool input and output content is not logged in trace spans by default. To include it, set `OTEL_LOG_TOOL_CONTENT=1`. When enabled, span events include full tool input and output content truncated at 60 KB per span. This can include raw file contents from Read tool results and Bash command output. Configure your telemetry backend to filter or redact these attributes as needed917* Tool input and output content is not logged in trace spans by default. To include it, set `OTEL_LOG_TOOL_CONTENT=1`. When enabled, span events include full tool input and output content truncated at 60 KB per span. This can include raw file contents from Read tool results and Bash command output. Configure your telemetry backend to filter or redact these attributes as needed

918* Raw Anthropic Messages API request and response bodies are not logged by default. To include them, set `OTEL_LOG_RAW_API_BODIES`. With `=1`, each API call emits `api_request_body` and `api_response_body` log events whose `body` attribute is the JSON-serialized payload, truncated at 60 KB. With `=file:<dir>`, untruncated bodies are written to `.request.json` and `.response.json` files under that directory and the events carry a `body_ref` path instead of the inline body. Ship the directory with a log collector or sidecar rather than through the telemetry stream. In both modes, bodies contain the full conversation history (system prompt, every prior user and assistant turn, tool results), so enabling this implies consent to everything the other `OTEL_LOG_*` content flags would reveal. Claude's extended-thinking content is always redacted from these bodies regardless of other settings

609 919

610## Monitor Claude Code on Amazon Bedrock920## Monitor Claude Code on Amazon Bedrock

611 921

network-config.md +5 −3

Details

112 112

113Ensure these URLs are allowlisted in your proxy configuration and firewall rules. This is especially important when using Claude Code in containerized or restricted network environments.113Ensure these URLs are allowlisted in your proxy configuration and firewall rules. This is especially important when using Claude Code in containerized or restricted network environments.

114 114

115The native installer and update checks also require the following URLs. Allowlist both, since the installer and auto-updater fetch from `storage.googleapis.com` while plugin downloads use `downloads.claude.ai`. If you install Claude Code through npm or manage your own binary distribution, end users may not need access:115When using [Bedrock](/en/amazon-bedrock), [Vertex AI](/en/google-vertex-ai), or [Foundry](/en/microsoft-foundry), model traffic goes to your provider instead of `api.anthropic.com`. The WebFetch tool still calls `api.anthropic.com` for its [domain safety check](/en/data-usage#webfetch-domain-safety-check) unless you set `skipWebFetchPreflight: true` in [settings](/en/settings).

116 116

117* `storage.googleapis.com`: download bucket for the Claude Code binary and auto-updater117The native installer and update checks also require the following URLs. Allowlist both, since clients running older Claude Code versions fetch from `storage.googleapis.com`. If you install Claude Code through npm or manage your own binary distribution, end users may not need access:

118* `downloads.claude.ai`: CDN hosting the install script, version pointers, manifests, signing keys, and plugin executables118

119* `downloads.claude.ai`: download host for the Claude Code binary, auto-updater, version pointers, manifests, install script, signing keys, and plugin executables

120* `storage.googleapis.com`: legacy download host used by older clients

119 121

120The [Chrome integration](/en/chrome) connects to the browser extension over a WebSocket bridge. If you use Claude in Chrome, allowlist `bridge.claudeusercontent.com` for outbound WebSocket connections.122The [Chrome integration](/en/chrome) connects to the browser extension over a WebSocket bridge. If you use Claude in Chrome, allowlist `bridge.claudeusercontent.com` for outbound WebSocket connections.

121 123

overview.md +0 −0

Details

No textual changes.

permission-modes.md +13 −14

Details

33 <Tab title="CLI">33 <Tab title="CLI">

34 **During a session**: press `Shift+Tab` to cycle `default` → `acceptEdits` → `plan`. The current mode appears in the status bar. Not every mode is in the default cycle:34 **During a session**: press `Shift+Tab` to cycle `default` → `acceptEdits` → `plan`. The current mode appears in the status bar. Not every mode is in the default cycle:

35 35

~~36 * `auto`: appears after you opt in with `--enable-auto-mode` or the persisted equivalent in settings~~36 * `auto`: appears when your account meets the [auto mode requirements](#eliminate-prompts-with-auto-mode)

37 * `bypassPermissions`: appears after you start with `--permission-mode bypassPermissions`, `--dangerously-skip-permissions`, or `--allow-dangerously-skip-permissions`; the `--allow-` variant adds the mode to the cycle without activating it37 * `bypassPermissions`: appears after you start with `--permission-mode bypassPermissions`, `--dangerously-skip-permissions`, or `--allow-dangerously-skip-permissions`; the `--allow-` variant adds the mode to the cycle without activating it

38 * `dontAsk`: never appears in the cycle; set it with `--permission-mode dontAsk`38 * `dontAsk`: never appears in the cycle; set it with `--permission-mode dontAsk`

39 39

150 150

151Auto mode is available only when your account meets all of these requirements:151Auto mode is available only when your account meets all of these requirements:

152 152

153* **Plan**: Team, Enterprise, or API. Not available on Pro or Max.153* **Plan**: Max, Team, Enterprise, or API. Not available on Pro.

154* **Admin**: on Team and Enterprise, an admin must enable it in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code) before users can turn it on. Admins can also lock it off by setting `permissions.disableAutoMode` to `"disable"` in [managed settings](/en/permissions#managed-settings).154* **Admin**: on Team and Enterprise, an admin must enable it in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code) before users can turn it on. Admins can also lock it off by setting `permissions.disableAutoMode` to `"disable"` in [managed settings](/en/permissions#managed-settings).

155* **Model**: Claude Sonnet 4.6 or Opus 4.6. Not available on Haiku or claude-3 models.155* **Model**: Claude Sonnet 4.6, Opus 4.6, or Opus 4.7 on Team, Enterprise, and API plans; Claude Opus 4.7 only on Max plans. Other models, including Haiku and claude-3 models, are not supported.

156* **Provider**: Anthropic API only. Not available on Bedrock, Vertex, or Foundry.156* **Provider**: Anthropic API only. Not available on Bedrock, Vertex, or Foundry.

157 157

158If Claude Code reports auto mode as unavailable, one of these requirements is unmet; this is not a transient outage.158If Claude Code reports auto mode as unavailable, one of these requirements is unmet; this is not a transient outage. A separate message that names a model and says auto mode "cannot determine the safety" of an action is a transient classifier outage; see the [error reference](/en/errors#auto-mode-cannot-determine-the-safety-of-an-action).

~~159~~

160Once enabled, start with the flag and `auto` joins the `Shift+Tab` cycle:

~~161~~

162```bash theme={null}

163claude --enable-auto-mode

164```

165 159

166### What the classifier blocks by default160### What the classifier blocks by default

167 161

185* Reading `.env` and sending credentials to their matching API179* Reading `.env` and sending credentials to their matching API

186* Read-only HTTP requests180* Read-only HTTP requests

187* Pushing to the branch you started on or one Claude created181* Pushing to the branch you started on or one Claude created

188* Sandbox network access requests

189 182

190Run `claude auto-mode defaults` to see the full rule lists. If routine actions get blocked, an administrator can add trusted repos, buckets, and services via the `autoMode.environment` setting: see [Configure the auto mode classifier](/en/permissions#configure-the-auto-mode-classifier).183Sandbox network access requests are routed through the classifier rather than allowed by default. Run `claude auto-mode defaults` to see the full rule lists. If routine actions get blocked, an administrator can add trusted repos, buckets, and services via the `autoMode.environment` setting: see [Configure the auto mode classifier](/en/permissions#configure-the-auto-mode-classifier).

184

185### Boundaries you state in conversation

186

187The classifier treats boundaries you state in the conversation as a block signal. If you tell Claude "don't push" or "wait until I review before deploying", the classifier blocks matching actions even when the default rules would allow them. A boundary stays in force until you lift it in a later message. Claude's own judgment that a condition was met does not lift it.

188

189Boundaries are not stored as rules. The classifier re-reads them from the transcript on each check, so a boundary can be lost if [context compaction](/en/costs#reduce-token-usage) removes the message that stated it. For a hard guarantee, add a [deny rule](/en/permissions#permission-rule-syntax) instead.

191 190

192### When auto mode falls back191### When auto mode falls back

193 192

229 </Accordion>228 </Accordion>

230 229

231 <Accordion title="Cost and latency">230 <Accordion title="Cost and latency">

232 The classifier currently runs on Claude Sonnet 4.6 regardless of your main session model. Classifier calls count toward your token usage. Each check sends a portion of the transcript plus the pending action, adding a round-trip before execution. Reads and working-directory edits outside protected paths skip the classifier, so the overhead comes mainly from shell commands and network operations.231 The classifier runs on a server-configured model that is independent of your `/model` selection, so switching models does not change classifier availability. Classifier calls count toward your token usage. Each check sends a portion of the transcript plus the pending action, adding a round-trip before execution. Reads and working-directory edits outside protected paths skip the classifier, so the overhead comes mainly from shell commands and network operations.

233 </Accordion>232 </Accordion>

234</AccordionGroup>233</AccordionGroup>

235 234

236## Allow only pre-approved tools with dontAsk mode235## Allow only pre-approved tools with dontAsk mode

237 236

238`dontAsk` mode auto-denies every tool that is not explicitly allowed. Only actions matching your `permissions.allow` rules can execute; explicit `ask` rules are also denied rather than prompting. This makes the mode fully non-interactive for CI pipelines or restricted environments where you pre-define exactly what Claude may do.237`dontAsk` mode auto-denies every tool call that would otherwise prompt. Only actions matching your `permissions.allow` rules and [read-only Bash commands](/en/permissions#read-only-commands) can execute; explicit `ask` rules are denied rather than prompting. This makes the mode fully non-interactive for CI pipelines or restricted environments where you pre-define exactly what Claude may do.

239 238

240Set it at startup with the flag:239Set it at startup with the flag:

241 240

permissions.md +25 −6

Details

96 96

97The space before `*` matters: `Bash(ls *)` matches `ls -la` but not `lsof`, while `Bash(ls*)` matches both. The `:*` suffix is an equivalent way to write a trailing wildcard, so `Bash(ls:*)` matches the same commands as `Bash(ls *)`.97The space before `*` matters: `Bash(ls *)` matches `ls -la` but not `lsof`, while `Bash(ls*)` matches both. The `:*` suffix is an equivalent way to write a trailing wildcard, so `Bash(ls:*)` matches the same commands as `Bash(ls *)`.

98 98

99The permission dialog writes the `:*` form when you select "Yes, don't ask again" for a command prefix. This form is only recognized at the end of a pattern. In a pattern like `Bash(git:* push)`, the colon is treated as a literal character and won't match git commands.99The permission dialog writes the space-separated form when you select "Yes, don't ask again" for a command prefix. The `:*` form is only recognized at the end of a pattern. In a pattern like `Bash(git:* push)`, the colon is treated as a literal character and won't match git commands.

100 100

101## Tool-specific permission rules101## Tool-specific permission rules

102 102

110* `Bash(* install)` matches any command ending with ` install`110* `Bash(* install)` matches any command ending with ` install`

111* `Bash(git * main)` matches commands like `git checkout main` and `git log --oneline main`111* `Bash(git * main)` matches commands like `git checkout main` and `git log --oneline main`

112 112

113A single `*` matches any sequence of characters including spaces, so one wildcard can span multiple arguments. `Bash(git:*)` matches `git log --oneline --all`, and `Bash(git * main)` matches `git push origin main` as well as `git merge main`.113A single `*` matches any sequence of characters including spaces, so one wildcard can span multiple arguments. `Bash(git *)` matches `git log --oneline --all`, and `Bash(git * main)` matches `git push origin main` as well as `git merge main`.

114 114

115When `*` appears at the end with a space before it (like `Bash(ls *)`), it enforces a word boundary, requiring the prefix to be followed by a space or end-of-string. For example, `Bash(ls *)` matches `ls -la` but not `lsof`. In contrast, `Bash(ls*)` without a space matches both `ls -la` and `lsof` because there's no word boundary constraint.115When `*` appears at the end with a space before it (like `Bash(ls *)`), it enforces a word boundary, requiring the prefix to be followed by a space or end-of-string. For example, `Bash(ls *)` matches `ls -la` but not `lsof`. In contrast, `Bash(ls*)` without a space matches both `ls -la` and `lsof` because there's no word boundary constraint.

116 116

130 130

131This wrapper list is built in and is not configurable. Development environment runners such as `direnv exec`, `devbox run`, `mise exec`, `npx`, and `docker exec` are not in the list. Because these tools execute their arguments as a command, a rule like `Bash(devbox run *)` matches whatever comes after `run`, including `devbox run rm -rf .`. To approve work inside an environment runner, write a specific rule that includes both the runner and the inner command, such as `Bash(devbox run npm test)`. Add one rule per inner command you want to allow.131This wrapper list is built in and is not configurable. Development environment runners such as `direnv exec`, `devbox run`, `mise exec`, `npx`, and `docker exec` are not in the list. Because these tools execute their arguments as a command, a rule like `Bash(devbox run *)` matches whatever comes after `run`, including `devbox run rm -rf .`. To approve work inside an environment runner, write a specific rule that includes both the runner and the inner command, such as `Bash(devbox run npm test)`. Add one rule per inner command you want to allow.

132 132

133Exec wrappers such as `watch`, `setsid`, `ionice`, and `flock` always prompt and cannot be auto-approved by a prefix rule like `Bash(watch *)`. The same applies to `find` with `-exec` or `-delete`: a `Bash(find *)` rule does not cover these forms. To approve a specific invocation, write an exact-match rule for the full command string.

134

135#### Read-only commands

136

137Claude Code recognizes a built-in set of Bash commands as read-only and runs them without a permission prompt in every mode. These include `ls`, `cat`, `head`, `tail`, `grep`, `find`, `wc`, `diff`, `stat`, `du`, `cd`, and read-only forms of `git`. The set is not configurable; to require a prompt for one of these commands, add an `ask` or `deny` rule for it.

138

139Unquoted glob patterns are permitted for commands whose every flag is read-only, so `ls *.ts` and `wc -l src/*.py` run without a prompt. Commands with write-capable or exec-capable flags, such as `find`, `sort`, `sed`, and `git`, still prompt when an unquoted glob is present because the glob could expand to a flag like `-delete`.

140

141A `cd` into a path inside your working directory or an [additional directory](#working-directories) is also read-only. A compound command like `cd packages/api && ls` runs without a prompt when each part qualifies on its own. Combining `cd` with `git` in one compound command always prompts, regardless of the target directory.

142

133<Warning>143<Warning>

134 Bash permission patterns that try to constrain command arguments are fragile. For example, `Bash(curl http://github.com/ *)` intends to restrict curl to GitHub URLs, but won't match variations like:144 Bash permission patterns that try to constrain command arguments are fragile. For example, `Bash(curl http://github.com/ *)` intends to restrict curl to GitHub URLs, but won't match variations like:

135 145

182 In gitignore patterns, `*` matches files in a single directory while `**` matches recursively across directories. To allow all file access, use just the tool name without parentheses: `Read`, `Edit`, or `Write`.192 In gitignore patterns, `*` matches files in a single directory while `**` matches recursively across directories. To allow all file access, use just the tool name without parentheses: `Read`, `Edit`, or `Write`.

183</Note>193</Note>

184 194

195When Claude accesses a symlink, permission rules check two paths: the symlink itself and the file it resolves to. Allow and deny rules treat that pair differently: allow rules fall back to prompting you, while deny rules block outright.

196

197* **Allow rules**: apply only when both the symlink path and its target match. A symlink inside an allowed directory that points outside it still prompts you.

198* **Deny rules**: apply when either the symlink path or its target matches. A symlink that points to a denied file is itself denied.

199

200For example, with `Read(./project/**)` allowed and `Read(~/.ssh/**)` denied, a symlink at `./project/key` pointing to `~/.ssh/id_rsa` is blocked: the target fails the allow rule and matches the deny rule.

201

185### WebFetch202### WebFetch

186 203

187* `WebFetch(domain:example.com)` matches fetch requests to example.com204* `WebFetch(domain:example.com)` matches fetch requests to example.com

258* Permission deny rules block Claude from even attempting to access restricted resources275* Permission deny rules block Claude from even attempting to access restricted resources

259* Sandbox restrictions prevent Bash commands from reaching resources outside defined boundaries, even if a prompt injection bypasses Claude's decision-making276* Sandbox restrictions prevent Bash commands from reaching resources outside defined boundaries, even if a prompt injection bypasses Claude's decision-making

260* Filesystem restrictions in the sandbox use Read and Edit deny rules, not separate sandbox configuration277* Filesystem restrictions in the sandbox use Read and Edit deny rules, not separate sandbox configuration

261* Network restrictions combine WebFetch permission rules with the sandbox's `allowedDomains` list278* Network restrictions combine WebFetch permission rules with the sandbox's `allowedDomains` and `deniedDomains` lists

262 279

263When sandboxing is enabled with `autoAllowBashIfSandboxed: true`, which is the default, sandboxed Bash commands run without prompting even if your permissions include `ask: Bash(*)`. The sandbox boundary substitutes for the per-command prompt. See [sandbox modes](/en/sandboxing#sandbox-modes) to change this behavior.280When sandboxing is enabled with `autoAllowBashIfSandboxed: true`, which is the default, sandboxed Bash commands run without prompting even if your permissions include `ask: Bash(*)`. The sandbox boundary substitutes for the per-command prompt. Explicit deny rules still apply, and `rm` or `rmdir` commands that target `/`, your home directory, or other critical system paths still trigger a prompt. See [sandbox modes](/en/sandboxing#sandbox-modes) to change this behavior.

264 281

265## Managed settings282## Managed settings

266 283

298 315

299## Configure the auto mode classifier316## Configure the auto mode classifier

300 317

301[Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) uses a classifier model to decide whether each action is safe to run without prompting. Out of the box it trusts only the working directory and, if present, the current repo's remotes. Actions like pushing to your company's source control org or writing to a team cloud bucket will be blocked as potential data exfiltration. The `autoMode` settings block lets you tell the classifier which infrastructure your organization trusts.318[Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) uses a classifier model to decide whether each action is safe to run without prompting. Out of the box it trusts only the working directory and, if present, the current repo's remotes. Actions like pushing to your company's source control org or writing to a team cloud bucket will be blocked as potential data exfiltration.

319

320To adjust what the classifier allows or blocks, add instructions to your [CLAUDE.md](/en/memory) file. The classifier reads CLAUDE.md from trusted directories alongside the conversation, so an instruction like "never force push" steers both Claude and the classifier at the same time. Start here for project conventions and behavioral rules.

302 321

303The classifier reads `autoMode` from user settings, `.claude/settings.local.json`, and managed settings. It does not read from shared project settings in `.claude/settings.json`, because a checked-in repo could otherwise inject its own allow rules.322For rules that apply across projects, such as trusted infrastructure or organization-wide deny rules, use the `autoMode` settings block. The classifier reads `autoMode` from user settings, `.claude/settings.local.json`, and managed settings. It does not read from shared project settings in `.claude/settings.json`, because a checked-in repo could otherwise inject its own allow rules.

304 323

306| :------------------------- | :---------------------------- | :-------------------------------------------------- |325| :------------------------- | :---------------------------- | :-------------------------------------------------- |

plugin-dependencies.md +131 −0 added

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Constrain plugin dependency versions

7> Declare version constraints on plugin dependencies so your plugin keeps working when an upstream plugin ships a breaking change.

9A plugin can depend on other plugins by listing them in `plugin.json` or in its marketplace entry. By default, a dependency tracks the latest available version, so an upstream release can change the dependency under your plugin without warning. Version constraints let you hold a dependency at a tested version range until you choose to move.

11When you install a plugin that declares dependencies, Claude Code resolves and installs them automatically and lists which dependencies were added at the end of the install output. If a dependency later goes missing, `/reload-plugins` and the background plugin auto-update install it automatically, provided its marketplace is already in your configured marketplaces. Dependencies from a marketplace you have not added are left unresolved.

13This guide is for plugin authors who declare dependencies in `plugin.json` and for marketplace maintainers who tag releases. To install plugins that have dependencies, see [Discover and install plugins](/en/discover-plugins). For the full manifest schema, see the [Plugins reference](/en/plugins-reference).

15<Note>

16 Dependency version constraints require Claude Code v2.1.110 or later.

17</Note>

19## Why constrain dependency versions

21Consider an internal marketplace where two teams publish plugins. The platform team maintains `secrets-vault`, an MCP server that wraps a secrets backend. The deploy team maintains `deploy-kit`, which calls `secrets-vault` to fetch credentials during deploys.

23`deploy-kit` is tested against `secrets-vault` v2.1.0. Without a version constraint, the next time the platform team tags a release that renames an MCP tool, auto-update moves every engineer's `secrets-vault` to the new version and `deploy-kit` breaks.

25With a version constraint, `deploy-kit` declares that it needs `secrets-vault` in the `~2.1.0` range. Engineers with `deploy-kit` installed stay on the highest matching `2.1.x` patch. The deploy team upgrades on their own schedule by publishing a new `deploy-kit` version with a wider constraint.

27## Declare a dependency with a version constraint

29List dependencies in the `dependencies` array of your plugin's `.claude-plugin/plugin.json`. Each entry is either a plugin name or an object with a version constraint.

31The following manifest declares one unversioned dependency and one constrained dependency:

33```json .claude-plugin/plugin.json theme={null}

34{

35 "name": "deploy-kit",

36 "version": "3.1.0",

37 "dependencies": [

38 "audit-logger",

39 { "name": "secrets-vault", "version": "~2.1.0" }

40 ]

41}

42```

44An entry can be a bare string with only the plugin name, like `"audit-logger"` in the example above, which depends on whatever version that plugin's marketplace provides. For more control, use an object with these fields:

46| Field | Type | Description |

47| :------------ | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

48| `name` | string | Plugin name. Resolves within the same marketplace as the declaring plugin. Required. |

49| `version` | string | A [semver range](https://github.com/npm/node-semver#ranges) such as `~2.1.0`, `^2.0`, `>=1.4`, or `=2.1.0`. The dependency is fetched at the highest tagged version that satisfies this range. |

50| `marketplace` | string | A different marketplace to resolve `name` in. Cross-marketplace dependencies are blocked unless the target marketplace is listed in [`allowCrossMarketplaceDependenciesOn`](#depend-on-a-plugin-from-another-marketplace) in the root marketplace's `marketplace.json`. |

52The `version` field accepts any expression supported by Node's `semver` package, including caret, tilde, hyphen, and comparator ranges. Pre-release versions such as `2.0.0-beta.1` are excluded unless your range opts in with a pre-release suffix like `^2.0.0-0`.

54## Depend on a plugin from another marketplace

56By default, Claude Code refuses to auto-install a dependency that lives in a different marketplace than the plugin declaring it. This prevents one marketplace from silently pulling in plugins from a source you have not reviewed.

58To allow it, the maintainer of the root marketplace adds the target marketplace name to `allowCrossMarketplaceDependenciesOn` in `marketplace.json`. The root marketplace is the one that hosts the plugin the user is installing; only its allowlist is consulted, so trust does not chain through intermediate marketplaces.

60The following `marketplace.json` allows `deploy-kit` to depend on a plugin from `acme-shared`:

62```json .claude-plugin/marketplace.json theme={null}

63{

64 "name": "acme-tools",

65 "owner": { "name": "Acme" },

66 "allowCrossMarketplaceDependenciesOn": ["acme-shared"],

67 "plugins": [

68 {

69 "name": "deploy-kit",

70 "source": "./deploy-kit",

71 "dependencies": [

72 { "name": "audit-logger", "marketplace": "acme-shared" }

73 ]

74 }

75 ]

76}

77```

79If the field is missing or does not include the target marketplace, install fails with a `cross-marketplace` error naming the field to set. Users can still install the dependency manually first, which satisfies the constraint without changing the allowlist.

81## Tag plugin releases for version resolution

83Version constraints resolve against git tags on the marketplace repository. For Claude Code to find a dependency's available versions, the upstream plugin's releases must be tagged using a specific naming convention.

85Tag each release as `{plugin-name}--v{version}`, where `{version}` matches the `version` field in that commit's `plugin.json`.

87```bash theme={null}

88git tag secrets-vault--v2.1.0

89git push origin secrets-vault--v2.1.0

90```

92The plugin name prefix lets one marketplace repository host multiple plugins with independent version lines. The `--v` separator is parsed as a prefix match on the full plugin name, so plugin names that contain hyphens are handled correctly.

94When you install a plugin that declares `{ "name": "secrets-vault", "version": "~2.1.0" }`, Claude Code lists the marketplace's tags, filters to those starting with `secrets-vault--v`, and fetches the highest version satisfying `~2.1.0`. If no matching tag exists, the dependent plugin is disabled with an error listing the available versions.

96<Note>

97 For `npm` marketplace sources, the constraint does not control which version is fetched, since tag-based resolution applies only to git-backed sources. The constraint is still checked at load time, and the dependent plugin is disabled with `dependency-version-unsatisfied` if the installed version does not satisfy it.

98</Note>

100## How constraints interact

101

102When several installed plugins constrain the same dependency, Claude Code intersects their ranges and resolves the dependency to the highest version that satisfies all of them. The table below shows how common combinations resolve.

103

104| Plugin A requires | Plugin B requires | Result |

105| :---------------- | :---------------- | :---------------------------------------------------------------------------------------------- |

106| `^2.0` | `>=2.1` | One install at the highest `2.x` tag at or above `2.1.0`. Both plugins load. |

107| `~2.1` | `~3.0` | Install of plugin B fails with `range-conflict`. Plugin A and the dependency stay as they were. |

108| `=2.1.0` | none | The dependency stays at `2.1.0`. Auto-update skips newer versions while plugin A is installed. |

109

110Auto-update checks each constrained dependency against every installed plugin's range before applying an update. If the marketplace moves a dependency to a version outside any range, the update is skipped and the skip message names the constraining plugin.

111

112When you uninstall the last plugin that constrains a dependency, the dependency is no longer held and resumes tracking its marketplace entry on the next update.

113

114## Resolve dependency errors

115

116Dependency problems surface in `claude plugin list`, in the `/plugin` interface, and in `/doctor`. The affected plugin is disabled until you resolve the error. The most common errors and their fixes are listed below.

117

118| Error | Meaning | How to resolve |

119| :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

120| `range-conflict` | The version requirements for a dependency cannot be combined. The error message names the cause: no version satisfies all of the ranges, a range is not valid semver syntax, or the combined ranges are too complex to intersect. | Uninstall or update one of the conflicting plugins, fix any invalid `version` string, simplify long `\|\|` chains, or ask the upstream author to widen its constraint. |

121| `dependency-version-unsatisfied` | The installed dependency's version is outside this plugin's declared range. | Run `claude plugin install <dependency>@<marketplace>` to re-resolve the dependency against all current constraints. |

122| `no-matching-tag` | The dependency's repository has no `{name}--v*` tag satisfying the range. | Check that the upstream has tagged releases using the convention above, or relax your range. |

123

124To check for these errors programmatically, run `claude plugin list --json` and read the `errors` field on each plugin.

125

126## See also

127

128* [Create plugins](/en/plugins): build plugins with skills, agents, and hooks

129* [Create and distribute a plugin marketplace](/en/plugin-marketplaces): host plugins for your team

130* [Plugins reference](/en/plugins-reference#plugin-manifest-schema): the full `plugin.json` schema

131* [Version management](/en/plugins-reference#version-management): semantic versioning guidance for plugin releases

plugin-marketplaces.md +4 −3

Details

169 169

170### Optional metadata170### Optional fields

171 171

173| :--------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |173| :------------------------------------ | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

176| `metadata.pluginRoot` | string | Base directory prepended to relative plugin source paths (for example, `"./plugins"` lets you write `"source": "formatter"` instead of `"source": "./plugins/formatter"`) |176| `metadata.pluginRoot` | string | Base directory prepended to relative plugin source paths (for example, `"./plugins"` lets you write `"source": "formatter"` instead of `"source": "./plugins/formatter"`) |

177| `allowCrossMarketplaceDependenciesOn` | array | Other marketplaces that plugins in this marketplace may depend on. Dependencies from a marketplace not listed here are blocked at install. See [Depend on a plugin from another marketplace](/en/plugin-dependencies#depend-on-a-plugin-from-another-marketplace). |

177 178

178## Plugin entries179## Plugin entries

179 180

497 498

498### Private repositories499### Private repositories

499 500

500Claude Code supports installing plugins from private repositories. For manual installation and updates, Claude Code uses your existing git credential helpers. If `git clone` works for a private repository in your terminal, it works in Claude Code too. Common credential helpers include `gh auth login` for GitHub, macOS Keychain, and `git-credential-store`.501Claude Code supports installing plugins from private repositories. For manual installation and updates, Claude Code uses your existing git credential helpers, so HTTPS access via `gh auth login`, macOS Keychain, or `git-credential-store` works the same as in your terminal. SSH access works as long as the host is already in your `known_hosts` file and the key is loaded in `ssh-agent`, since Claude Code suppresses interactive SSH prompts for the host fingerprint and key passphrase.

501 502

502Background auto-updates run at startup without credential helpers, since interactive prompts would block Claude Code from starting. To enable auto-updates for private marketplaces, set the appropriate authentication token in your environment:503Background auto-updates run at startup without credential helpers, since interactive prompts would block Claude Code from starting. To enable auto-updates for private marketplaces, set the appropriate authentication token in your environment:

503 504

plugins.md +22 −1

Details

173 173

174## Plugin structure overview174## Plugin structure overview

175 175

176You've created a plugin with a skill, but plugins can include much more: custom agents, hooks, MCP servers, and LSP servers.176You've created a plugin with a skill, but plugins can include much more: custom agents, hooks, MCP servers, LSP servers, and background monitors.

177 177

178<Warning>178<Warning>

179 **Common mistake**: Don't put `commands/`, `agents/`, `skills/`, or `hooks/` inside the `.claude-plugin/` directory. Only `plugin.json` goes inside `.claude-plugin/`. All other directories must be at the plugin root level.179 **Common mistake**: Don't put `commands/`, `agents/`, `skills/`, or `hooks/` inside the `.claude-plugin/` directory. Only `plugin.json` goes inside `.claude-plugin/`. All other directories must be at the plugin root level.

191| `monitors/` | Plugin root | Background monitor configurations in `monitors.json` |

191| `bin/` | Plugin root | Executables added to the Bash tool's `PATH` while the plugin is enabled |192| `bin/` | Plugin root | Executables added to the Bash tool's `PATH` while the plugin is enabled |

193 194

254 255

255For complete LSP configuration options, see [LSP servers](/en/plugins-reference#lsp-servers).256For complete LSP configuration options, see [LSP servers](/en/plugins-reference#lsp-servers).

256 257

258### Add background monitors to your plugin

259

260Background monitors let your plugin watch logs, files, or external status in the background and notify Claude as events arrive. Claude Code starts each monitor automatically when the plugin is active, so you don't need to instruct Claude to start the watch.

261

262Add a `monitors/monitors.json` file at the plugin root with an array of monitor entries:

263

264```json monitors/monitors.json theme={null}

265[

266 {

267 "name": "error-log",

268 "command": "tail -F ./logs/error.log",

269 "description": "Application error log"

270 }

271]

272```

273

274Each stdout line from `command` is delivered to Claude as a notification during the session. For the full schema, including the `when` trigger and variable substitution, see [Monitors](/en/plugins-reference#monitors).

275

257### Ship default settings with your plugin276### Ship default settings with your plugin

258 277

259Plugins can include a `settings.json` file at the plugin root to apply default configuration when the plugin is enabled. Currently, only the `agent` and `subagentStatusLine` keys are supported.278Plugins can include a `settings.json` file at the plugin root to apply default configuration when the plugin is enabled. Currently, only the `agent` and `subagentStatusLine` keys are supported.

322* **Claude.ai**: [claude.ai/settings/plugins/submit](https://claude.ai/settings/plugins/submit)341* **Claude.ai**: [claude.ai/settings/plugins/submit](https://claude.ai/settings/plugins/submit)

323* **Console**: [platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit)342* **Console**: [platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit)

324 343

344Once your plugin is listed, you can have your own CLI prompt Claude Code users to install it. See [Recommend your plugin from your CLI](/en/plugin-hints).

345

325<Note>346<Note>

326 For complete technical specifications, debugging techniques, and distribution strategies, see [Plugins reference](/en/plugins-reference).347 For complete technical specifications, debugging techniques, and distribution strategies, see [Plugins reference](/en/plugins-reference).

327</Note>348</Note>

plugins-reference.md +112 −11

Details

12 12

13This reference provides complete technical specifications for the Claude Code plugin system, including component schemas, CLI commands, and development tools.13This reference provides complete technical specifications for the Claude Code plugin system, including component schemas, CLI commands, and development tools.

14 14

~~15A **plugin** is a self-contained directory of components that extends Claude Code with custom functionality. Plugin components include skills, agents, hooks, MCP servers, and LSP servers.~~15A **plugin** is a self-contained directory of components that extends Claude Code with custom functionality. Plugin components include skills, agents, hooks, MCP servers, LSP servers, and monitors.

16 16

17## Plugin components reference17## Plugin components reference

18 18

109Plugin hooks respond to the same lifecycle events as [user-defined hooks](/en/hooks):109Plugin hooks respond to the same lifecycle events as [user-defined hooks](/en/hooks):

110 110

111| Event | When it fires |111| Event | When it fires |

112| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |112| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

115| `UserPromptExpansion` | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion |

117| `PermissionDenied` | When a tool call is denied by the auto mode classifier. Return `{retry: true}` to tell the model it may retry the denied tool call |118| `PermissionDenied` | When a tool call is denied by the auto mode classifier. Return `{retry: true}` to tell the model it may retry the denied tool call |

265 266

266Install the language server first, then install the plugin from the marketplace.267Install the language server first, then install the plugin from the marketplace.

267 268

269### Monitors

270

271Plugins can declare background monitors that Claude Code starts automatically when the plugin is active. Each monitor runs a shell command for the lifetime of the session and delivers every stdout line to Claude as a notification, so Claude can react to log entries, status changes, or polled events without being asked to start the watch itself.

272

273Plugin monitors use the same mechanism as the [Monitor tool](/en/tools-reference#monitor-tool) and share its availability constraints. They run only in interactive CLI sessions, run unsandboxed at the same trust level as [hooks](#hooks), and are skipped on hosts where the Monitor tool is unavailable.

274

275<Note>

276 Plugin monitors require Claude Code v2.1.105 or later.

277</Note>

278

279**Location**: `monitors/monitors.json` in the plugin root, or inline in `plugin.json`

280

281**Format**: JSON array of monitor entries

282

283The following `monitors/monitors.json` watches a deployment status endpoint and a local error log:

284

285```json theme={null}

286[

287 {

288 "name": "deploy-status",

289 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/poll-deploy.sh ${user_config.api_endpoint}",

290 "description": "Deployment status changes"

291 },

292 {

293 "name": "error-log",

294 "command": "tail -F ./logs/error.log",

295 "description": "Application error log",

296 "when": "on-skill-invoke:debug"

297 }

298]

299```

300

301To declare monitors inline, set the `monitors` key in `plugin.json` to the same array. To load from a non-default path, set `monitors` to a relative path string such as `"./config/monitors.json"`.

302

303**Required fields:**

304

305| Field | Description |

306| :------------ | :-------------------------------------------------------------------------------------------------------------------- |

307| `name` | Identifier unique within the plugin. Prevents duplicate processes when the plugin reloads or a skill is invoked again |

308| `command` | Shell command run as a persistent background process in the session working directory |

309| `description` | Short summary of what is being watched. Shown in the task panel and in notification summaries |

310

311**Optional fields:**

312

313| Field | Description |

314| :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

315| `when` | Controls when the monitor starts. `"always"` starts it at session start and on plugin reload, and is the default. `"on-skill-invoke:<skill-name>"` starts it the first time the named skill in this plugin is dispatched |

316

317The `command` value supports the same [variable substitutions](#environment-variables) as MCP and LSP server configs: `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}`, `${user_config.*}`, and any `${ENV_VAR}` from the environment. Prefix the command with `cd "${CLAUDE_PLUGIN_ROOT}" && ` if the script needs to run from the plugin's own directory.

318

319Disabling a plugin mid-session does not stop monitors that are already running. They stop when the session ends.

320

268***321***

269 322

270## Plugin installation scopes323## Plugin installation scopes

311 "mcpServers": "./mcp-config.json",364 "mcpServers": "./mcp-config.json",

312 "outputStyles": "./styles/",365 "outputStyles": "./styles/",

313 "lspServers": "./.lsp.json",366 "lspServers": "./.lsp.json",

314 "monitors": "./monitors.json"367 "monitors": "./monitors.json",

368 "dependencies": [

369 "helper-lib",

370 { "name": "secrets-vault", "version": "~2.1.0" }

371 ]

315}372}

316```373```

317 374

342### Component path fields399### Component path fields

343 400

345| :------------- | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------- |402| :------------- | :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |

413| `dependencies` | array | Other plugins this plugin requires, optionally with semver version constraints. See [Constrain plugin dependency versions](/en/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |

356 414

357### User configuration415### User configuration

358 416

362{420{

363 "userConfig": {421 "userConfig": {

364 "api_endpoint": {422 "api_endpoint": {

365 "description": "Your team's API endpoint",423 "type": "string",

366 "sensitive": false424 "title": "API endpoint",

425 "description": "Your team's API endpoint"

367 },426 },

368 "api_token": {427 "api_token": {

428 "type": "string",

429 "title": "API token",

369 "description": "API authentication token",430 "description": "API authentication token",

370 "sensitive": true431 "sensitive": true

371 }432 }

373}434}

374```435```

375 436

376Keys must be valid identifiers. Each value is available for substitution as `${user_config.KEY}` in MCP and LSP server configs, hook commands, and (for non-sensitive values only) skill and agent content. Values are also exported to plugin subprocesses as `CLAUDE_PLUGIN_OPTION_<KEY>` environment variables.437Keys must be valid identifiers. Each option supports these fields:

438

439| Field | Required | Description |

440| :------------ | :------- | :--------------------------------------------------------------------------------------- |

441| `type` | Yes | One of `string`, `number`, `boolean`, `directory`, or `file` |

442| `title` | Yes | Label shown in the configuration dialog |

443| `description` | Yes | Help text shown beneath the field |

444| `sensitive` | No | If `true`, masks input and stores the value in secure storage instead of `settings.json` |

445| `required` | No | If `true`, validation fails when the field is empty |

446| `default` | No | Value used when the user provides nothing |

447| `multiple` | No | For `string` type, allow an array of strings |

448| `min` / `max` | No | Bounds for `number` type |

449

450Each value is available for substitution as `${user_config.KEY}` in MCP and LSP server configs, hook commands, and monitor commands. Non-sensitive values can also be substituted in skill and agent content. All values are exported to plugin subprocesses as `CLAUDE_PLUGIN_OPTION_<KEY>` environment variables.

377 451

378Non-sensitive values are stored in `settings.json` under `pluginConfigs[<plugin-id>].options`. Sensitive values go to the system keychain (or `~/.claude/.credentials.json` where the keychain is unavailable). Keychain storage is shared with OAuth tokens and has an approximately 2 KB total limit, so keep sensitive values small.452Non-sensitive values are stored in `settings.json` under `pluginConfigs[<plugin-id>].options`. Sensitive values go to the system keychain (or `~/.claude/.credentials.json` where the keychain is unavailable). Keychain storage is shared with OAuth tokens and has an approximately 2 KB total limit, so keep sensitive values small.

379 453

387 {461 {

388 "server": "telegram",462 "server": "telegram",

389 "userConfig": {463 "userConfig": {

390 "bot_token": { "description": "Telegram bot token", "sensitive": true },464 "bot_token": {

391 "owner_id": { "description": "Your Telegram user ID", "sensitive": false }465 "type": "string",

466 "title": "Bot token",

467 "description": "Telegram bot token",

468 "sensitive": true

469 },

470 "owner_id": {

471 "type": "string",

472 "title": "Owner ID",

473 "description": "Your Telegram user ID"

474 }

392 }475 }

393 }476 }

394 ]477 ]

424 507

425### Environment variables508### Environment variables

426 509

427Claude Code provides two variables for referencing plugin paths. Both are substituted inline anywhere they appear in skill content, agent content, hook commands, and MCP or LSP server configs. Both are also exported as environment variables to hook processes and MCP or LSP server subprocesses.510Claude Code provides two variables for referencing plugin paths. Both are substituted inline anywhere they appear in skill content, agent content, hook commands, monitor commands, and MCP or LSP server configs. Both are also exported as environment variables to hook processes and MCP or LSP server subprocesses.

428 511

429**`${CLAUDE_PLUGIN_ROOT}`**: the absolute path to your plugin's installation directory. Use this to reference scripts, binaries, and config files bundled with the plugin. This path changes when the plugin updates, so files you write here do not survive an update.512**`${CLAUDE_PLUGIN_ROOT}`**: the absolute path to your plugin's installation directory. Use this to reference scripts, binaries, and config files bundled with the plugin. This path changes when the plugin updates, so files you write here do not survive an update.

430 513

709 792

710***793***

711 794

795### plugin list

796

797List installed plugins with their version, source marketplace, and enable status.

798

799```bash theme={null}

800claude plugin list [options]

801```

802

803**Options:**

804

805| Option | Description | Default |

806| :------------ | :------------------------------------------------------------- | :------ |

807| `--json` | Output as JSON | |

808| `--available` | Include available plugins from marketplaces. Requires `--json` | |

809| `-h, --help` | Display help for command | |

810

811***

812

712## Debugging and development tools813## Debugging and development tools

713 814

714### Debugging commands815### Debugging commands

quickstart.md +1 −2

Details

7> Welcome to Claude Code!7> Welcome to Claude Code!

8 8

9 9

11This quickstart guide will have you using AI-powered coding assistance in a few minutes. By the end, you'll understand how to use Claude Code for common development tasks.10This quickstart guide will have you using AI-powered coding assistance in a few minutes. By the end, you'll understand how to use Claude Code for common development tasks.

12 11

~~13<Experiment flag="quickstart-install-configurator" treatment={<InstallConfigurator />} />~~12

14 13

15## Before you begin14## Before you begin

16 15

remote-control.md +38 −1

Details

14 14

15When you start a Remote Control session on your machine, Claude keeps running locally the entire time, so nothing moves to the cloud. With Remote Control you can:15When you start a Remote Control session on your machine, Claude keeps running locally the entire time, so nothing moves to the cloud. With Remote Control you can:

16 16

~~17* **Use your full local environment remotely**: your filesystem, [MCP servers](/en/mcp), tools, and project configuration all stay available~~17* **Use your full local environment remotely**: your filesystem, [MCP servers](/en/mcp), tools, and project configuration all stay available, and typing `@` autocompletes file paths from your local project

18* **Work from both surfaces at once**: the conversation stays in sync across all connected devices, so you can send messages from your terminal, browser, and phone interchangeably18* **Work from both surfaces at once**: the conversation stays in sync across all connected devices, so you can send messages from your terminal, browser, and phone interchangeably

19* **Survive interruptions**: if your laptop sleeps or your network drops, the session reconnects automatically when your machine comes back online19* **Survive interruptions**: if your laptop sleeps or your network drops, the session reconnects automatically when your machine comes back online

20 20

146 146

147Use Remote Control when you're in the middle of local work and want to keep going from another device. Use Claude Code on the web when you want to kick off a task without any local setup, work on a repo you don't have cloned, or run multiple tasks in parallel.147Use Remote Control when you're in the middle of local work and want to keep going from another device. Use Claude Code on the web when you want to kick off a task without any local setup, work on a repo you don't have cloned, or run multiple tasks in parallel.

148 148

149## Mobile push notifications

150

151When Remote Control is active, Claude can send push notifications to your phone.

152

153Claude decides when to push. It typically sends one when a long-running task finishes or when it needs a decision from you to continue. You can also request a push in your prompt, for example `notify me when the tests finish`. Beyond the on/off toggle below, there is no per-event configuration.

154

155<Note>

156 Mobile push notifications require Claude Code v2.1.110 or later.

157</Note>

158

159To set up mobile push notifications:

160

161<Steps>

162 <Step title="Install the Claude mobile app">

163 Download the Claude app for [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) or [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude).

164 </Step>

165

166 <Step title="Sign in with your Claude Code account">

167 Use the same account and organization you use for Claude Code in the terminal.

168 </Step>

169

170 <Step title="Allow notifications">

171 Accept the notification permission prompt from the operating system.

172 </Step>

173

174 <Step title="Enable push in Claude Code">

175 In your terminal, run `/config` and enable **Push when Claude decides**.

176 </Step>

177</Steps>

178

179If notifications don't arrive:

180

181* If `/config` shows **No mobile registered**, open the Claude app on your phone so it can refresh its push token. The warning clears the next time Remote Control connects.

182* On iOS, Focus modes and notification summaries can suppress or delay pushes. Check Settings → Notifications → Claude.

183* On Android, aggressive battery optimization can delay delivery. Exempt the Claude app from battery optimization in system settings.

184

149## Limitations185## Limitations

150 186

151* **One remote session per interactive process**: outside of server mode, each Claude Code instance supports one remote session at a time. Use [server mode](#start-a-remote-control-session) to run multiple concurrent sessions from a single process.187* **One remote session per interactive process**: outside of server mode, each Claude Code instance supports one remote session at a time. Use [server mode](#start-a-remote-control-session) to run multiple concurrent sessions from a single process.

152* **Local process must keep running**: Remote Control runs as a local process. If you close the terminal, quit VS Code, or otherwise stop the `claude` process, the session ends.188* **Local process must keep running**: Remote Control runs as a local process. If you close the terminal, quit VS Code, or otherwise stop the `claude` process, the session ends.

153* **Extended network outage**: if your machine is awake but unable to reach the network for more than roughly 10 minutes, the session times out and the process exits. Run `claude remote-control` again to start a new session.189* **Extended network outage**: if your machine is awake but unable to reach the network for more than roughly 10 minutes, the session times out and the process exits. Run `claude remote-control` again to start a new session.

154* **Ultraplan disconnects Remote Control**: starting an [ultraplan](/en/ultraplan) session disconnects any active Remote Control session because both features occupy the claude.ai/code interface and only one can be connected at a time.190* **Ultraplan disconnects Remote Control**: starting an [ultraplan](/en/ultraplan) session disconnects any active Remote Control session because both features occupy the claude.ai/code interface and only one can be connected at a time.

191* **Some commands are local-only**: commands that open an interactive picker in the terminal, such as `/mcp`, `/plugin`, or `/resume`, work only from the local CLI. Commands that produce text output, including `/compact`, `/clear`, `/context`, `/cost`, `/exit`, `/extra-usage`, `/recap`, and `/reload-plugins`, work from mobile and web.

155 192

156## Troubleshooting193## Troubleshooting

157 194

routines.md +9 −23

Details

16 16

17* **Scheduled**: run on a recurring cadence like hourly, nightly, or weekly17* **Scheduled**: run on a recurring cadence like hourly, nightly, or weekly

18* **API**: trigger on demand by sending an HTTP POST to a per-routine endpoint with a bearer token18* **API**: trigger on demand by sending an HTTP POST to a per-routine endpoint with a bearer token

~~19* **GitHub**: run automatically in response to repository events such as pull requests, pushes, issues, or workflow runs~~19* **GitHub**: run automatically in response to repository events such as pull requests or releases

20 20

21A single routine can combine triggers. For example, a PR review routine can run nightly, trigger from a deploy script, and also react to every new PR.21A single routine can combine triggers. For example, a PR review routine can run nightly, trigger from a deploy script, and also react to every new PR.

22 22

74 74

75 * **Network access**: set the level of internet access available during each run75 * **Network access**: set the level of internet access available during each run

76 * **Environment variables**: provide API keys, tokens, or other secrets Claude can use76 * **Environment variables**: provide API keys, tokens, or other secrets Claude can use

~~77 * **Setup script**: run install commands before each session starts, like installing dependencies or configuring tools~~77 * **Setup script**: install dependencies and tools the routine needs. The result is [cached](/en/claude-code-on-the-web#environment-caching), so the script doesn't re-run on every session

78 78

79 A **Default** environment is provided. To use a custom environment, [create one](/en/claude-code-on-the-web#the-cloud-environment) before creating the routine.79 A **Default** environment is provided. To use a custom environment, [create one](/en/claude-code-on-the-web#the-cloud-environment) before creating the routine.

80 </Step>80 </Step>

229 229

230#### Supported events230#### Supported events

231 231

232GitHub triggers can subscribe to any of the following event categories. Within each category you can pick a specific action, such as `pull_request.opened`, or react to all actions in the category.232GitHub triggers can subscribe to either of the following event categories. Within each category you can pick a specific action, such as `pull_request.opened`, or react to all actions in the category.

233 233

234| Event | Triggers when |234| Event | Triggers when |

235| :-------------------------- | :---------------------------------------------------------------------------- |235| :----------- | :---------------------------------------------------------------------------- |

236| Pull request | A PR is opened, closed, assigned, labeled, synchronized, or otherwise updated |236| Pull request | A PR is opened, closed, assigned, labeled, synchronized, or otherwise updated |

237| Pull request review | A PR review is submitted, edited, or dismissed |

238| Pull request review comment | A comment on a PR diff is created, edited, or deleted |

239| Push | Commits are pushed to a branch |

240| Release | A release is created, published, edited, or deleted |237| Release | A release is created, published, edited, or deleted |

241| Issues | An issue is opened, edited, closed, labeled, or otherwise updated |

242| Issue comment | A comment on an issue or PR is created, edited, or deleted |

243| Sub issues | A sub-issue or parent issue is added or removed |

244| Commit comment | A commit or diff is commented on |

245| Discussion | A discussion is created, edited, answered, or otherwise updated |

246| Discussion comment | A discussion comment is created, edited, or deleted |

247| Check run | A check run is created, requested, rerequested, or completed |

248| Check suite | A check suite completes or is requested |

249| Merge queue entry | A PR enters or leaves the merge queue |

250| Workflow run | A GitHub Actions workflow run starts or completes |

251| Workflow job | A GitHub Actions job is queued or completes |

252| Workflow dispatch | A workflow is manually triggered |

253| Repository dispatch | A custom repository\_dispatch event is sent |

254 238

255#### Filter pull requests239#### Filter pull requests

256 240

266| Labels | Labels applied to the PR |250| Labels | Labels applied to the PR |

267| Is draft | Whether the PR is in draft state |251| Is draft | Whether the PR is in draft state |

268| Is merged | Whether the PR has been merged |252| Is merged | Whether the PR has been merged |

269| From fork | Whether the PR comes from a fork |253

254Each filter pairs a field with an operator: equals, contains, starts with, is one of, is not one of, or matches regex.

255

256The `matches regex` operator tests the entire field value, not a substring within it. To match any title containing `hotfix`, write `.*hotfix.*`. Without the surrounding `.*`, the filter matches only a title that is exactly `hotfix` with nothing before or after. For literal substring matching without regex syntax, use the `contains` operator instead.

270 257

271A few example filter combinations:258A few example filter combinations:

272 259

273* **Auth module review**: base branch `main`, head branch contains `auth-provider`. Sends any PR that touches authentication to a focused reviewer.260* **Auth module review**: base branch `main`, head branch contains `auth-provider`. Sends any PR that touches authentication to a focused reviewer.

274* **External contributor triage**: from fork is `true`. Routes every fork-based PR through an extra security and style review before a human looks at it.

275* **Ready-for-review only**: is draft is `false`. Skips drafts so the routine only runs when the PR is ready for review.261* **Ready-for-review only**: is draft is `false`. Skips drafts so the routine only runs when the PR is ready for review.

276* **Label-gated backport**: labels include `needs-backport`. Triggers a port-to-another-branch routine only when a maintainer tags the PR.262* **Label-gated backport**: labels include `needs-backport`. Triggers a port-to-another-branch routine only when a maintainer tags the PR.

277 263

278#### How sessions map to events264#### How sessions map to events

279 265

280Each matching GitHub event starts a new session. Session reuse across events is not available for GitHub-triggered routines, so two pushes or two PR updates produce two independent sessions.266Each matching GitHub event starts a new session. Session reuse across events is not available for GitHub-triggered routines, so two PR updates produce two independent sessions.

281 267

282## Manage routines268## Manage routines

283 269

sandboxing.md +3 −2

Details

97 97

98This opens a menu where you can choose between sandbox modes. If required dependencies are missing (such as `bubblewrap` or `socat` on Linux), the menu displays installation instructions for your platform.98This opens a menu where you can choose between sandbox modes. If required dependencies are missing (such as `bubblewrap` or `socat` on Linux), the menu displays installation instructions for your platform.

99 99

100By default, if the sandbox cannot start (missing dependencies, unsupported platform, or platform restrictions), Claude Code shows a warning and runs commands without sandboxing. To make this a hard failure instead, set [`sandbox.failIfUnavailable`](/en/settings#sandbox-settings) to `true`. This is intended for managed deployments that require sandboxing as a security gate.100By default, if the sandbox cannot start (missing dependencies or unsupported platform), Claude Code shows a warning and runs commands without sandboxing. To make this a hard failure instead, set [`sandbox.failIfUnavailable`](/en/settings#sandbox-settings) to `true`. This is intended for managed deployments that require sandboxing as a security gate.

101 101

102### Sandbox modes102### Sandbox modes

103 103

104Claude Code offers two sandbox modes:104Claude Code offers two sandbox modes:

105 105

106**Auto-allow mode**: Bash commands will attempt to run inside the sandbox and are automatically allowed without requiring permission. Commands that cannot be sandboxed (such as those needing network access to non-allowed hosts) fall back to the regular permission flow. Explicit deny rules are always respected. Ask rules apply only to commands that fall back to the regular permission flow.106**Auto-allow mode**: Bash commands will attempt to run inside the sandbox and are automatically allowed without requiring permission. Commands that cannot be sandboxed (such as those needing network access to non-allowed hosts) fall back to the regular permission flow. Explicit deny rules are always respected, and `rm` or `rmdir` commands that target `/`, your home directory, or other critical system paths still trigger a permission prompt. Ask rules apply only to commands that fall back to the regular permission flow.

107 107

108**Regular permissions mode**: All bash commands go through the standard permission flow, even when sandboxed. This provides more control but requires more approvals.108**Regular permissions mode**: All bash commands go through the standard permission flow, even when sandboxed. This provides more control but requires more approvals.

109 109

250* Use `Read` and `Edit` deny rules to block access to specific files or directories250* Use `Read` and `Edit` deny rules to block access to specific files or directories

251* Use `WebFetch` allow/deny rules to control domain access251* Use `WebFetch` allow/deny rules to control domain access

252* Use sandbox `allowedDomains` to control which domains Bash commands can reach252* Use sandbox `allowedDomains` to control which domains Bash commands can reach

253* Use sandbox `deniedDomains` to block specific domains even when a broader `allowedDomains` wildcard would otherwise permit them

253 254

254Paths from both `sandbox.filesystem` settings and permission rules are merged together into the final sandbox configuration.255Paths from both `sandbox.filesystem` settings and permission rules are merged together into the final sandbox configuration.

255 256

scheduled-tasks.md +9 −5

Details

12 12

13Scheduled tasks let Claude re-run a prompt automatically on an interval. Use them to poll a deployment, babysit a PR, check back on a long-running build, or remind yourself to do something later in the session. To react to events as they happen instead of polling, see [Channels](/en/channels): your CI can push the failure into the session directly.13Scheduled tasks let Claude re-run a prompt automatically on an interval. Use them to poll a deployment, babysit a PR, check back on a long-running build, or remind yourself to do something later in the session. To react to events as they happen instead of polling, see [Channels](/en/channels): your CI can push the failure into the session directly.

14 14

15Tasks are session-scoped: they live in the current Claude Code process and are gone when you exit. For durable scheduling that survives restarts, use [Routines](/en/routines), [Desktop scheduled tasks](/en/desktop-scheduled-tasks), or [GitHub Actions](/en/github-actions).15Tasks are session-scoped: they live in the current conversation and stop when you start a new one. Resuming with `--resume` or `--continue` brings back any task that hasn't [expired](#seven-day-expiry): a recurring task created within the last 7 days, or a one-shot whose scheduled time hasn't passed yet. For scheduling that survives independently of any session, use [Routines](/en/routines), [Desktop scheduled tasks](/en/desktop-scheduled-tasks), or [GitHub Actions](/en/github-actions).

16 16

17## Compare scheduling options17## Compare scheduling options

18 18

19Claude Code offers three ways to schedule recurring work:19Claude Code offers three ways to schedule recurring work:

20 20

~~22| :------------------------- | :----------------------------- | :------------------------------------- | :----------------------------- |~~22| :------------------------- | :----------------------------- | :------------------------------------- | :---------------------------------- |

24| Requires machine on | No | Yes | Yes |24| Requires machine on | No | Yes | Yes |

25| Requires open session | No | No | Yes |25| Requires open session | No | No | Yes |

~~26| Persistent across restarts | Yes | Yes | No (session-scoped) |~~26| Persistent across restarts | Yes | Yes | Restored on `--resume` if unexpired |

27| Access to local files | No (fresh clone) | Yes | Yes |27| Access to local files | No (fresh clone) | Yes | Yes |

118 118

119Edits to `loop.md` take effect on the next iteration, so you can refine the instructions while a loop is running. When no `loop.md` exists in either location, the loop falls back to the built-in maintenance prompt. Keep the file concise: content beyond 25,000 bytes is truncated.119Edits to `loop.md` take effect on the next iteration, so you can refine the instructions while a loop is running. When no `loop.md` exists in either location, the loop falls back to the built-in maintenance prompt. Keep the file concise: content beyond 25,000 bytes is truncated.

120 120

121### Stop a loop

122

123To stop a `/loop` while it is waiting for the next iteration, press `Esc`. This clears the pending wakeup so the loop does not fire again. Tasks you scheduled by [asking Claude directly](#manage-scheduled-tasks) are not affected by `Esc` and stay in place until you delete them.

124

121## Set a one-time reminder125## Set a one-time reminder

122 126

123For one-shot reminders, describe what you want in natural language instead of using `/loop`. Claude schedules a single-fire task that deletes itself after running.127For one-shot reminders, describe what you want in natural language instead of using `/loop`. Claude schedules a single-fire task that deletes itself after running.

198 202

199Session-scoped scheduling has inherent constraints:203Session-scoped scheduling has inherent constraints:

200 204

201* Tasks only fire while Claude Code is running and idle. Closing the terminal or letting the session exit cancels everything.205* Tasks only fire while Claude Code is running and idle. Closing the terminal or letting the session exit stops them firing.

202* No catch-up for missed fires. If a task's scheduled time passes while Claude is busy on a long-running request, it fires once when Claude becomes idle, not once per missed interval.206* No catch-up for missed fires. If a task's scheduled time passes while Claude is busy on a long-running request, it fires once when Claude becomes idle, not once per missed interval.

203* No persistence across restarts. Restarting Claude Code clears all session-scoped tasks.207* Starting a fresh conversation clears all session-scoped tasks. Resuming with `claude --resume` or `claude --continue` restores tasks that have not expired: recurring tasks within seven days of creation, and one-shot tasks whose scheduled time has not yet passed. Background Bash and monitor tasks are never restored on resume.

204 208

205For cron-driven automation that needs to run unattended:209For cron-driven automation that needs to run unattended:

206 210

settings.md +21 −10

Details

87 87

88 * **Server-managed settings**: delivered from Anthropic's servers via the Claude.ai admin console. See [server-managed settings](/en/server-managed-settings).88 * **Server-managed settings**: delivered from Anthropic's servers via the Claude.ai admin console. See [server-managed settings](/en/server-managed-settings).

89 * **MDM/OS-level policies**: delivered through native device management on macOS and Windows:89 * **MDM/OS-level policies**: delivered through native device management on macOS and Windows:

~~90 * macOS: `com.anthropic.claudecode` managed preferences domain (deployed via configuration profiles in Jamf, Iru (Kandji), or other MDM tools)~~90 * macOS: `com.anthropic.claudecode` managed preferences domain. The plist's top-level keys mirror `managed-settings.json`, with nested settings as dictionaries and arrays as plist arrays. Deploy via configuration profiles in Jamf, Iru (Kandji), or similar MDM tools.

91 * Windows: `HKLM\SOFTWARE\Policies\ClaudeCode` registry key with a `Settings` value (REG\_SZ or REG\_EXPAND\_SZ) containing JSON (deployed via Group Policy or Intune)91 * Windows: `HKLM\SOFTWARE\Policies\ClaudeCode` registry key with a `Settings` value (REG\_SZ or REG\_EXPAND\_SZ) containing JSON (deployed via Group Policy or Intune)

92 * Windows (user-level): `HKCU\SOFTWARE\Policies\ClaudeCode` (lowest policy priority, only used when no admin-level source exists)92 * Windows (user-level): `HKCU\SOFTWARE\Policies\ClaudeCode` (lowest policy priority, only used when no admin-level source exists)

93 * **File-based**: `managed-settings.json` and `managed-mcp.json` deployed to system directories:93 * **File-based**: `managed-settings.json` and `managed-mcp.json` deployed to system directories:

150 150

151The `$schema` line in the example above points to the [official JSON schema](https://json.schemastore.org/claude-code-settings.json) for Claude Code settings. Adding it to your `settings.json` enables autocomplete and inline validation in VS Code, Cursor, and any other editor that supports JSON schema validation.151The `$schema` line in the example above points to the [official JSON schema](https://json.schemastore.org/claude-code-settings.json) for Claude Code settings. Adding it to your `settings.json` enables autocomplete and inline validation in VS Code, Cursor, and any other editor that supports JSON schema validation.

152 152

153The published schema is updated periodically and may not include settings added in the most recent CLI releases, so a validation warning on a recently documented field does not necessarily mean your configuration is invalid.

154

153### Available settings155### Available settings

154 156

155`settings.json` supports a number of options:157`settings.json` supports a number of options:

170| `autoMode` | Customize what the [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) classifier blocks and allows. Contains `environment`, `allow`, and `soft_deny` arrays of prose rules. See [Configure the auto mode classifier](/en/permissions#configure-the-auto-mode-classifier). Not read from shared project settings | `{"environment": ["Trusted repo: github.example.com/acme"]}` |172| `autoMode` | Customize what the [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) classifier blocks and allows. Contains `environment`, `allow`, and `soft_deny` arrays of prose rules. See [Configure the auto mode classifier](/en/permissions#configure-the-auto-mode-classifier). Not read from shared project settings | `{"environment": ["Trusted repo: github.example.com/acme"]}` |

171| `autoUpdatesChannel` | Release channel to follow for updates. Use `"stable"` for a version that is typically about one week old and skips versions with major regressions, or `"latest"` (default) for the most recent release | `"stable"` |173| `autoUpdatesChannel` | Release channel to follow for updates. Use `"stable"` for a version that is typically about one week old and skips versions with major regressions, or `"latest"` (default) for the most recent release | `"stable"` |

172| `availableModels` | Restrict which models users can select via `/model`, `--model`, Config tool, or `ANTHROPIC_MODEL`. Does not affect the Default option. See [Restrict model selection](/en/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |174| `availableModels` | Restrict which models users can select via `/model`, `--model`, Config tool, or `ANTHROPIC_MODEL`. Does not affect the Default option. See [Restrict model selection](/en/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |

175| `awaySummaryEnabled` | Show a one-line session recap when you return to the terminal after a few minutes away. Set to `false` or turn off Session recap in `/config` to disable. Same as [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](/en/env-vars) | `true` |

173| `awsAuthRefresh` | Custom script that modifies the `.aws` directory (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |176| `awsAuthRefresh` | Custom script that modifies the `.aws` directory (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |

174| `awsCredentialExport` | Custom script that outputs JSON with AWS credentials (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |177| `awsCredentialExport` | Custom script that outputs JSON with AWS credentials (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |

175| `blockedMarketplaces` | (Managed settings only) Blocklist of marketplace sources. Blocked sources are checked before downloading, so they never touch the filesystem. See [Managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |178| `blockedMarketplaces` | (Managed settings only) Blocklist of marketplace sources. Blocked sources are checked before downloading, so they never touch the filesystem. See [Managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |

183| `disableDeepLinkRegistration` | Set to `"disable"` to prevent Claude Code from registering the `claude-cli://` protocol handler with the operating system on startup. Deep links let external tools open a Claude Code session with a pre-filled prompt via `claude-cli://open?q=...`. The `q` parameter supports multi-line prompts using URL-encoded newlines (`%0A`). Useful in environments where protocol handler registration is restricted or managed separately | `"disable"` |186| `disableDeepLinkRegistration` | Set to `"disable"` to prevent Claude Code from registering the `claude-cli://` protocol handler with the operating system on startup. Deep links let external tools open a Claude Code session with a pre-filled prompt via `claude-cli://open?q=...`. The `q` parameter supports multi-line prompts using URL-encoded newlines (`%0A`). Useful in environments where protocol handler registration is restricted or managed separately | `"disable"` |

185| `disableSkillShellExecution` | Disable inline shell execution for `` !`...` `` and ` ```! ` blocks in [skills](/en/skills) and custom commands from user, project, plugin, or additional-directory sources. Commands are replaced with `[shell command execution disabled by policy]` instead of being run. Bundled and managed skills are not affected. Most useful in [managed settings](/en/permissions#managed-settings) where users cannot override it | `true` |188| `disableSkillShellExecution` | Disable inline shell execution for `` !`...` `` and ` ```! ` blocks in [skills](/en/skills) and custom commands from user, project, plugin, or additional-directory sources. Commands are replaced with `[shell command execution disabled by policy]` instead of being run. Bundled and managed skills are not affected. Most useful in [managed settings](/en/permissions#managed-settings) where users cannot override it | `true` |

186| `effortLevel` | Persist the [effort level](/en/model-config#adjust-effort-level) across sessions. Accepts `"low"`, `"medium"`, or `"high"`. Written automatically when you run `/effort low`, `/effort medium`, or `/effort high`. Supported on Opus 4.6 and Sonnet 4.6 | `"medium"` |189| `effortLevel` | Persist the [effort level](/en/model-config#adjust-effort-level) across sessions. Accepts `"low"`, `"medium"`, `"high"`, or `"xhigh"`. Written automatically when you run `/effort` with one of those values. See [Adjust effort level](/en/model-config#adjust-effort-level) for supported models | `"xhigh"` |

189| `env` | Environment variables that will be applied to every session | `{"FOO": "bar"}` |192| `env` | Environment variables that will be applied to every session | `{"FOO": "bar"}` |

198| `includeCoAuthoredBy` | **Deprecated**: Use `attribution` instead. Whether to include the `co-authored-by Claude` byline in git commits and pull requests (default: `true`) | `false` |201| `includeCoAuthoredBy` | **Deprecated**: Use `attribution` instead. Whether to include the `co-authored-by Claude` byline in git commits and pull requests (default: `true`) | `false` |

199| `includeGitInstructions` | Include built-in commit and PR workflow instructions and the git status snapshot in Claude's system prompt (default: `true`). Set to `false` to remove both, for example when using your own git workflow skills. The `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` environment variable takes precedence over this setting when set | `false` |202| `includeGitInstructions` | Include built-in commit and PR workflow instructions and the git status snapshot in Claude's system prompt (default: `true`). Set to `false` to remove both, for example when using your own git workflow skills. The `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` environment variable takes precedence over this setting when set | `false` |

200| `language` | Configure Claude's preferred response language (e.g., `"japanese"`, `"spanish"`, `"french"`). Claude will respond in this language by default. Also sets the [voice dictation](/en/voice-dictation#change-the-dictation-language) language | `"japanese"` |203| `language` | Configure Claude's preferred response language (e.g., `"japanese"`, `"spanish"`, `"french"`). Claude will respond in this language by default. Also sets the [voice dictation](/en/voice-dictation#change-the-dictation-language) language | `"japanese"` |

201| `minimumVersion` | Prevent the auto-updater from downgrading below a specific version. Automatically set when switching to the stable channel and choosing to stay on the current version until stable catches up. Used with `autoUpdatesChannel` | `"2.1.85"` |204| `minimumVersion` | Floor that prevents background auto-updates and `claude update` from installing a version below this one. Switching from the `"latest"` channel to `"stable"` via `/config` prompts you to stay on the current version or allow the downgrade. Choosing to stay sets this value. Also useful in [managed settings](/en/permissions#managed-settings) to pin an organization-wide minimum | `"2.1.100"` |

203| `modelOverrides` | Map Anthropic model IDs to provider-specific model IDs such as Bedrock inference profile ARNs. Each model picker entry uses its mapped value when calling the provider API. See [Override model IDs per version](/en/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |206| `modelOverrides` | Map Anthropic model IDs to provider-specific model IDs such as Bedrock inference profile ARNs. Each model picker entry uses its mapped value when calling the provider API. See [Override model IDs per version](/en/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |

204| `otelHeadersHelper` | Script to generate dynamic OpenTelemetry headers. Runs at startup and periodically (see [Dynamic headers](/en/monitoring-usage#dynamic-headers)) | `/bin/generate_otel_headers.sh` |207| `otelHeadersHelper` | Script to generate dynamic OpenTelemetry headers. Runs at startup and periodically (see [Dynamic headers](/en/monitoring-usage#dynamic-headers)) | `/bin/generate_otel_headers.sh` |

210| `respectGitignore` | Control whether the `@` file picker respects `.gitignore` patterns. When `true` (default), files matching `.gitignore` patterns are excluded from suggestions | `false` |213| `respectGitignore` | Control whether the `@` file picker respects `.gitignore` patterns. When `true` (default), files matching `.gitignore` patterns are excluded from suggestions | `false` |

212| `showThinkingSummaries` | Show [extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) summaries in interactive sessions. When unset or `false` (default in interactive mode), thinking blocks are redacted by the API and shown as a collapsed stub. Redaction only changes what you see, not what the model generates: to reduce thinking spend, [lower the budget or disable thinking](/en/common-workflows#use-extended-thinking-thinking-mode) instead. Non-interactive mode (`-p`) and SDK callers always receive summaries regardless of this setting | `true` |215| `showThinkingSummaries` | Show [extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) summaries in interactive sessions. When unset or `false` (default in interactive mode), thinking blocks are redacted by the API and shown as a collapsed stub. Redaction only changes what you see, not what the model generates: to reduce thinking spend, [lower the budget or disable thinking](/en/common-workflows#use-extended-thinking-thinking-mode) instead. Non-interactive mode (`-p`) and SDK callers always receive summaries regardless of this setting | `true` |

216| `skipWebFetchPreflight` | Skip the [WebFetch domain safety check](/en/data-usage#webfetch-domain-safety-check) that sends each requested hostname to `api.anthropic.com` before fetching. Set to `true` in environments that block traffic to Anthropic, such as Bedrock, Vertex AI, or Foundry deployments with restrictive egress. When skipped, WebFetch attempts any URL without consulting the blocklist | `true` |

214| `spinnerTipsOverride` | Override spinner tips with custom strings. `tips`: array of tip strings. `excludeDefault`: if `true`, only show custom tips; if `false` or absent, custom tips are merged with built-in tips | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |218| `spinnerTipsOverride` | Override spinner tips with custom strings. `tips`: array of tip strings. `excludeDefault`: if `true`, only show custom tips; if `false` or absent, custom tips are merged with built-in tips | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |

215| `spinnerVerbs` | Customize the action verbs shown in the spinner and turn duration messages. Set `mode` to `"replace"` to use only your verbs, or `"append"` to add them to the defaults | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |219| `spinnerVerbs` | Customize the action verbs shown in the spinner and turn duration messages. Set `mode` to `"replace"` to use only your verbs, or `"append"` to add them to the defaults | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |

220| `sshConfigs` | SSH connections to show in the [Desktop](/en/desktop#pre-configure-ssh-connections-for-your-team) environment dropdown. Each entry requires `id`, `name`, and `sshHost`; `sshPort`, `sshIdentityFile`, and `startDirectory` are optional. When set in managed settings, connections are read-only for users. Read from managed and user settings only | `[{"id": "dev-vm", "name": "Dev VM", "sshHost": "user@dev.example.com"}]` |

216| `statusLine` | Configure a custom status line to display context. See [`statusLine` documentation](/en/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |221| `statusLine` | Configure a custom status line to display context. See [`statusLine` documentation](/en/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |

217| `strictKnownMarketplaces` | (Managed settings only) Allowlist of plugin marketplaces users can add. Undefined = no restrictions, empty array = lockdown. Applies to marketplace additions only. See [Managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |222| `strictKnownMarketplaces` | (Managed settings only) Allowlist of plugin marketplaces users can add. Undefined = no restrictions, empty array = lockdown. Applies to marketplace additions only. See [Managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |

223| `tui` | Terminal UI renderer. Use `"fullscreen"` for the flicker-free [alt-screen renderer](/en/fullscreen) with virtualized scrollback. Use `"default"` for the classic main-screen renderer. Set via `/tui` | `"fullscreen"` |

218| `useAutoModeDuringPlan` | Whether plan mode uses auto mode semantics when auto mode is available. Default: `true`. Not read from shared project settings. Appears in `/config` as "Use auto mode during plan" | `false` |224| `useAutoModeDuringPlan` | Whether plan mode uses auto mode semantics when auto mode is available. Default: `true`. Not read from shared project settings. Appears in `/config` as "Use auto mode during plan" | `false` |

221 227

222### Global config settings228### Global config settings

227| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |233| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |

228| `autoConnectIde` | Automatically connect to a running IDE when Claude Code starts from an external terminal. Default: `false`. Appears in `/config` as **Auto-connect to IDE (external terminal)** when running outside a VS Code or JetBrains terminal | `true` |234| `autoConnectIde` | Automatically connect to a running IDE when Claude Code starts from an external terminal. Default: `false`. Appears in `/config` as **Auto-connect to IDE (external terminal)** when running outside a VS Code or JetBrains terminal | `true` |

229| `autoInstallIdeExtension` | Automatically install the Claude Code IDE extension when running from a VS Code terminal. Default: `true`. Appears in `/config` as **Auto-install IDE extension** when running inside a VS Code or JetBrains terminal. You can also set the [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/en/env-vars) environment variable | `false` |235| `autoInstallIdeExtension` | Automatically install the Claude Code IDE extension when running from a VS Code terminal. Default: `true`. Appears in `/config` as **Auto-install IDE extension** when running inside a VS Code or JetBrains terminal. You can also set the [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/en/env-vars) environment variable | `false` |

236| `autoScrollEnabled` | In [fullscreen rendering](/en/fullscreen), follow new output to the bottom of the conversation. Default: `true`. Appears in `/config` as **Auto-scroll**. Permission prompts still scroll into view when this is off | `false` |

230| `editorMode` | Key binding mode for the input prompt: `"normal"` or `"vim"`. Default: `"normal"`. Appears in `/config` as **Editor mode** | `"vim"` |237| `editorMode` | Key binding mode for the input prompt: `"normal"` or `"vim"`. Default: `"normal"`. Appears in `/config` as **Editor mode** | `"vim"` |

238| `externalEditorContext` | Prepend Claude's previous response as `#`-commented context when you open the external editor with `Ctrl+G`. Default: `false`. Appears in `/config` as **Show last response in external editor** | `true` |

231| `showTurnDuration` | Show turn duration messages after responses, e.g. "Cooked for 1m 6s". Default: `true`. Appears in `/config` as **Show turn duration** | `false` |239| `showTurnDuration` | Show turn duration messages after responses, e.g. "Cooked for 1m 6s". Default: `true`. Appears in `/config` as **Show turn duration** | `false` |

232| `terminalProgressBarEnabled` | Show the terminal progress bar in supported terminals: ConEmu, Ghostty 1.2.0+, and iTerm2 3.6.6+. Default: `true`. Appears in `/config` as **Terminal progress bar** | `false` |240| `terminalProgressBarEnabled` | Show the terminal progress bar in supported terminals: ConEmu, Ghostty 1.2.0+, and iTerm2 3.6.6+. Default: `true`. Appears in `/config` as **Terminal progress bar** | `false` |

233| `teammateMode` | How [agent team](/en/agent-teams) teammates display: `auto` (picks split panes in tmux or iTerm2, in-process otherwise), `in-process`, or `tmux`. See [choose a display mode](/en/agent-teams#choose-a-display-mode) | `"in-process"` |241| `teammateMode` | How [agent team](/en/agent-teams) teammates display: `auto` (picks split panes in tmux or iTerm2, in-process otherwise), `in-process`, or `tmux`. See [choose a display mode](/en/agent-teams#choose-a-display-mode) | `"in-process"` |

275Configure advanced sandboxing behavior. Sandboxing isolates bash commands from your filesystem and network. See [Sandboxing](/en/sandboxing) for details.283Configure advanced sandboxing behavior. Sandboxing isolates bash commands from your filesystem and network. See [Sandboxing](/en/sandboxing) for details.

276 284

278| :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ |286| :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------- |

280| `failIfUnavailable` | Exit with an error at startup if `sandbox.enabled` is true but the sandbox cannot start (missing dependencies, unsupported platform, or platform restrictions). When false (default), a warning is shown and commands run unsandboxed. Intended for managed settings deployments that require sandboxing as a hard gate | `true` |288| `failIfUnavailable` | Exit with an error at startup if `sandbox.enabled` is true but the sandbox cannot start (missing dependencies or unsupported platform). When false (default), a warning is shown and commands run unsandboxed. Intended for managed settings deployments that require sandboxing as a hard gate | `true` |

283| `allowUnsandboxedCommands` | Allow commands to run outside the sandbox via the `dangerouslyDisableSandbox` parameter. When set to `false`, the `dangerouslyDisableSandbox` escape hatch is completely disabled and all commands must run sandboxed (or be in `excludedCommands`). Useful for enterprise policies that require strict sandboxing. Default: true | `false` |291| `allowUnsandboxedCommands` | Allow commands to run outside the sandbox via the `dangerouslyDisableSandbox` parameter. When set to `false`, the `dangerouslyDisableSandbox` escape hatch is completely disabled and all commands must run sandboxed (or be in `excludedCommands`). Useful for enterprise policies that require strict sandboxing. Default: true | `false` |

286| `filesystem.denyRead` | Paths where sandboxed commands cannot read. Arrays are merged across all settings scopes. Also merged with paths from `Read(...)` deny permission rules. | `["~/.aws/credentials"]` |294| `filesystem.denyRead` | Paths where sandboxed commands cannot read. Arrays are merged across all settings scopes. Also merged with paths from `Read(...)` deny permission rules. | `["~/.aws/credentials"]` |

287| `filesystem.allowRead` | Paths to re-allow reading within `denyRead` regions. Takes precedence over `denyRead`. Arrays are merged across all settings scopes. Use this to create workspace-only read access patterns. | `["."]` |295| `filesystem.allowRead` | Paths to re-allow reading within `denyRead` regions. Takes precedence over `denyRead`. Arrays are merged across all settings scopes. Use this to create workspace-only read access patterns. | `["."]` |

288| `filesystem.allowManagedReadPathsOnly` | (Managed settings only) Only `filesystem.allowRead` paths from managed settings are respected. `denyRead` still merges from all sources. Default: false | `true` |296| `filesystem.allowManagedReadPathsOnly` | (Managed settings only) Only `filesystem.allowRead` paths from managed settings are respected. `denyRead` still merges from all sources. Default: false | `true` |

289| `network.allowUnixSockets` | Unix socket paths accessible in sandbox (for SSH agents, etc.) | `["~/.ssh/agent-socket"]` |297| `network.allowUnixSockets` | (macOS only) Unix socket paths accessible in sandbox. Ignored on Linux and WSL2, where the seccomp filter cannot inspect socket paths; use `allowAllUnixSockets` instead. | `["~/.ssh/agent-socket"]` |

290| `network.allowAllUnixSockets` | Allow all Unix socket connections in sandbox. Default: false | `true` |298| `network.allowAllUnixSockets` | Allow all Unix socket connections in sandbox. On Linux and WSL2 this is the only way to permit Unix sockets, since it skips the seccomp filter that otherwise blocks `socket(AF_UNIX, ...)` calls. Default: false | `true` |

292| `network.allowMachLookup` | Additional XPC/Mach service names the sandbox may look up (macOS only). Supports a single trailing `*` for prefix matching. Needed for tools that communicate via XPC such as the iOS Simulator or Playwright. | `["com.apple.coresimulator.*"]` |300| `network.allowMachLookup` | Additional XPC/Mach service names the sandbox may look up (macOS only). Supports a single trailing `*` for prefix matching. Needed for tools that communicate via XPC such as the iOS Simulator or Playwright. | `["com.apple.coresimulator.*"]` |

302| `network.deniedDomains` | Array of domains to block for outbound network traffic. Supports the same wildcard syntax as `allowedDomains`. Takes precedence over `allowedDomains` when both match. Merged from all settings sources regardless of `allowManagedDomainsOnly`. | `["sensitive.cloud.example.com"]` |

294| `network.allowManagedDomainsOnly` | (Managed settings only) Only `allowedDomains` and `WebFetch(domain:...)` allow rules from managed settings are respected. Domains from user, project, and local settings are ignored. Non-allowed domains are blocked automatically without prompting the user. Denied domains are still respected from all sources. Default: false | `true` |303| `network.allowManagedDomainsOnly` | (Managed settings only) Only `allowedDomains` and `WebFetch(domain:...)` allow rules from managed settings are respected. Domains from user, project, and local settings are ignored. Non-allowed domains are blocked automatically without prompting the user. Denied domains are still respected from all sources. Default: false | `true` |

295| `network.httpProxyPort` | HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8080` |304| `network.httpProxyPort` | HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8080` |

296| `network.socksProxyPort` | SOCKS5 proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8081` |305| `network.socksProxyPort` | SOCKS5 proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8081` |

323 },332 },

324 "network": {333 "network": {

325 "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],334 "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],

335 "deniedDomains": ["uploads.github.com"],

326 "allowUnixSockets": [336 "allowUnixSockets": [

327 "/var/run/docker.sock"337 "/var/run/docker.sock"

328 ],338 ],

474 484

475### Verify active settings485### Verify active settings

476 486

477Run `/status` inside Claude Code to see which settings sources are active and where they come from. The output shows each configuration layer (managed, user, project) along with its origin, such as `Enterprise managed settings (remote)`, `Enterprise managed settings (plist)`, `Enterprise managed settings (HKLM)`, or `Enterprise managed settings (file)`. If a settings file contains errors, `/status` reports the issue so you can fix it.487Run `/status` inside Claude Code to see which settings sources are active and where they come from. The output shows each configuration layer (managed, user, project) along with its origin, such as `Enterprise managed settings (remote)`, `Enterprise managed settings (plist)`, `Enterprise managed settings (HKLM)`, `Enterprise managed settings (HKCU)`, or `Enterprise managed settings (file)`. If a settings file contains errors, `/status` reports the issue so you can fix it.

478 488

479### Key points about the configuration system489### Key points about the configuration system

480 490

895 905

896* [Permissions](/en/permissions): permission system, rule syntax, tool-specific patterns, and managed policies906* [Permissions](/en/permissions): permission system, rule syntax, tool-specific patterns, and managed policies

897* [Authentication](/en/authentication): set up user access to Claude Code907* [Authentication](/en/authentication): set up user access to Claude Code

898* [Troubleshooting](/en/troubleshooting): solutions for common configuration issues908* [Debug your configuration](/en/debug-your-config): diagnose why a setting, hook, or MCP server isn't taking effect

909* [Troubleshooting](/en/troubleshooting): installation, authentication, and platform issues

setup.md +26 −21

Details

123}123}

124```124```

125 125

126Claude Code can also run PowerShell natively on Windows as an opt-in preview. See [PowerShell tool](/en/tools-reference#powershell-tool) for setup and limitations.126Claude Code can also run PowerShell natively on Windows. The PowerShell tool is rolling out progressively; set `CLAUDE_CODE_USE_POWERSHELL_TOOL=1` to opt in or `0` to opt out. See [PowerShell tool](/en/tools-reference#powershell-tool) for setup and limitations.

127 127

128**Option 2: WSL**128**Option 2: WSL**

129 129

204 204

205Homebrew installations choose a channel by cask name instead of this setting: `claude-code` tracks stable and `claude-code@latest` tracks latest.205Homebrew installations choose a channel by cask name instead of this setting: `claude-code` tracks stable and `claude-code@latest` tracks latest.

206 206

207### Pin a minimum version

208

209The `minimumVersion` setting establishes a floor. Background auto-updates and `claude update` refuse to install any version below this value, so moving to the `"stable"` channel does not downgrade you if you are already on a newer `"latest"` build.

210

211Switching from `"latest"` to `"stable"` via `/config` prompts you to either stay on the current version or allow the downgrade. Choosing to stay sets `minimumVersion` to that version. Switching back to `"latest"` clears it.

212

213Add it to your [settings.json file](/en/settings) to pin a floor explicitly:

214

215```json theme={null}

216{

217 "autoUpdatesChannel": "stable",

218 "minimumVersion": "2.1.100"

219}

220```

221

222In [managed settings](/en/permissions#managed-settings), this enforces an organization-wide minimum that user and project settings cannot override.

223

207### Disable auto-updates224### Disable auto-updates

208 225

209Set `DISABLE_AUTOUPDATER` to `"1"` in the `env` key of your [`settings.json`](/en/settings#available-settings) file:226Set `DISABLE_AUTOUPDATER` to `"1"` in the `env` key of your [`settings.json`](/en/settings#available-settings) file:

298 </Tab>315 </Tab>

299</Tabs>316</Tabs>

300 317

301### Deprecated npm installation318### Install with npm

~~302~~

303npm installation is deprecated. The native installer is faster, requires no dependencies, and auto-updates in the background. Use the [native installation](#install-claude-code) method when possible.

304 319

305#### Migrate from npm to native320You can also install Claude Code as a global npm package. The package requires [Node.js 18 or later](https://nodejs.org/en/download).

~~306~~

307If you previously installed Claude Code with npm, switch to the native installer:

308 321

309```bash theme={null}322```bash theme={null}

310# Install the native binary323npm install -g @anthropic-ai/claude-code

311curl -fsSL https://claude.ai/install.sh | bash

~~312~~

313# Remove the old npm installation

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

315```324```

316 325

317You can also run `claude install` from an existing npm installation to install the native binary alongside it, then remove the npm version.326The npm package installs the same native binary as the standalone installer. npm pulls the binary in through a per-platform optional dependency such as `@anthropic-ai/claude-code-darwin-arm64`, and a postinstall step links it into place. The installed `claude` binary does not itself invoke Node.

~~318~~

319#### Install with npm

320 327

321If you need npm installation for compatibility reasons, you must have [Node.js 18+](https://nodejs.org/en/download) installed. Install the package globally:328Supported npm install platforms are `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64`, and `win32-arm64`. Your package manager must allow optional dependencies. See [troubleshooting](/en/troubleshooting#native-binary-not-found-after-npm-install) if the binary is missing after install.

~~322~~

323```bash theme={null}

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

325```

326 329

327<Warning>330<Warning>

328 Do NOT use `sudo npm install -g` as this can lead to permission issues and security risks. If you encounter permission errors, see [troubleshooting permission errors](/en/troubleshooting#permission-errors-during-installation).331 Do NOT use `sudo npm install -g` as this can lead to permission issues and security risks. If you encounter permission errors, see [troubleshooting permission errors](/en/troubleshooting#permission-errors-during-installation).

361 Set `VERSION` to the release you want to verify.364 Set `VERSION` to the release you want to verify.

362 365

363 ```bash theme={null}366 ```bash theme={null}

364 REPO=https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases367 REPO=https://downloads.claude.ai/claude-code-releases

365 VERSION=2.1.89368 VERSION=2.1.89

366 curl -fsSLO "$REPO/$VERSION/manifest.json"369 curl -fsSLO "$REPO/$VERSION/manifest.json"

367 curl -fsSLO "$REPO/$VERSION/manifest.json.sig"370 curl -fsSLO "$REPO/$VERSION/manifest.json.sig"

477 Removing configuration files will delete all your settings, allowed tools, MCP server configurations, and session history.480 Removing configuration files will delete all your settings, allowed tools, MCP server configurations, and session history.

478</Warning>481</Warning>

479 482

483The VS Code extension, the JetBrains plugin, and the Desktop app also write to `~/.claude/`. If any of them is still installed, the directory is recreated the next time it runs. To remove Claude Code completely, uninstall the [VS Code extension](/en/vs-code#uninstall-the-extension), the JetBrains plugin, and the Desktop app before deleting these files.

484

480To remove Claude Code settings and cached data:485To remove Claude Code settings and cached data:

481 486

482<Tabs>487<Tabs>

skills.md +8 −5

Details

20 20

21## Bundled skills21## Bundled skills

22 22

23Claude Code includes a set of bundled skills that are available in every session, including `/simplify`, `/batch`, `/debug`, `/loop`, and `/claude-api`. Unlike built-in commands, which execute fixed logic directly, bundled skills are prompt-based: they give Claude a detailed playbook and let it orchestrate the work using its tools. You invoke them the same way as any other skill, by typing `/` followed by the skill name.23Claude Code includes a set of bundled skills that are available in every session, including `/simplify`, `/batch`, `/debug`, `/loop`, and `/claude-api`. Unlike most built-in commands, which execute fixed logic directly, bundled skills are prompt-based: they give Claude a detailed playbook and let it orchestrate the work using its tools. You invoke them the same way as any other skill, by typing `/` followed by the skill name.

24 24

25Bundled skills are listed alongside built-in commands in the [commands reference](/en/commands), marked **Skill** in the Purpose column.25Bundled skills are listed alongside built-in commands in the [commands reference](/en/commands), marked **Skill** in the Purpose column.

26 26

192| `description` | Recommended | What the skill does and when to use it. Claude uses this to decide when to apply the skill. If omitted, uses the first paragraph of markdown content. Front-load the key use case: the combined `description` and `when_to_use` text is truncated at 1,536 characters in the skill listing to reduce context usage. |192| `description` | Recommended | What the skill does and when to use it. Claude uses this to decide when to apply the skill. If omitted, uses the first paragraph of markdown content. Front-load the key use case: the combined `description` and `when_to_use` text is truncated at 1,536 characters in the skill listing to reduce context usage. |

193| `when_to_use` | No | Additional context for when Claude should invoke the skill, such as trigger phrases or example requests. Appended to `description` in the skill listing and counts toward the 1,536-character cap. |193| `when_to_use` | No | Additional context for when Claude should invoke the skill, such as trigger phrases or example requests. Appended to `description` in the skill listing and counts toward the 1,536-character cap. |

194| `argument-hint` | No | Hint shown during autocomplete to indicate expected arguments. Example: `[issue-number]` or `[filename] [format]`. |194| `argument-hint` | No | Hint shown during autocomplete to indicate expected arguments. Example: `[issue-number]` or `[filename] [format]`. |

195| `disable-model-invocation` | No | Set to `true` to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually with `/name`. Default: `false`. |195| `arguments` | No | Named positional arguments for [`$name` substitution](#available-string-substitutions) in the skill content. Accepts a space-separated string or a YAML list. Names map to argument positions in order. |

196| `disable-model-invocation` | No | Set to `true` to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually with `/name`. Also prevents the skill from being [preloaded into subagents](/en/sub-agents#preload-skills-into-subagents). Default: `false`. |

196| `user-invocable` | No | Set to `false` to hide from the `/` menu. Use for background knowledge users shouldn't invoke directly. Default: `true`. |197| `user-invocable` | No | Set to `false` to hide from the `/` menu. Use for background knowledge users shouldn't invoke directly. Default: `true`. |

197| `allowed-tools` | No | Tools Claude can use without asking permission when this skill is active. Accepts a space-separated string or a YAML list. |198| `allowed-tools` | No | Tools Claude can use without asking permission when this skill is active. Accepts a space-separated string or a YAML list. |

198| `model` | No | Model to use when this skill is active. |199| `model` | No | Model to use when this skill is active. The override applies for the rest of the current turn and is not saved to settings; the session model resumes on your next prompt. Accepts the same values as [`/model`](/en/model-config), or `inherit` to keep the active model. |

199| `effort` | No | [Effort level](/en/model-config#adjust-effort-level) when this skill is active. Overrides the session effort level. Default: inherits from session. Options: `low`, `medium`, `high`, `max` (Opus 4.6 only). |200| `effort` | No | [Effort level](/en/model-config#adjust-effort-level) when this skill is active. Overrides the session effort level. Default: inherits from session. Options: `low`, `medium`, `high`, `xhigh`, `max`; available levels depend on the model. |

200| `context` | No | Set to `fork` to run in a forked subagent context. |201| `context` | No | Set to `fork` to run in a forked subagent context. |

201| `agent` | No | Which subagent type to use when `context: fork` is set. |202| `agent` | No | Which subagent type to use when `context: fork` is set. |

202| `hooks` | No | Hooks scoped to this skill's lifecycle. See [Hooks in skills and agents](/en/hooks#hooks-in-skills-and-agents) for configuration format. |203| `hooks` | No | Hooks scoped to this skill's lifecycle. See [Hooks in skills and agents](/en/hooks#hooks-in-skills-and-agents) for configuration format. |

212| `$ARGUMENTS` | All arguments passed when invoking the skill. If `$ARGUMENTS` is not present in the content, arguments are appended as `ARGUMENTS: <value>`. |213| `$ARGUMENTS` | All arguments passed when invoking the skill. If `$ARGUMENTS` is not present in the content, arguments are appended as `ARGUMENTS: <value>`. |

214| `$N` | Shorthand for `$ARGUMENTS[N]`, such as `$0` for the first argument or `$1` for the second. |215| `$N` | Shorthand for `$ARGUMENTS[N]`, such as `$0` for the first argument or `$1` for the second. |

216| `$name` | Named argument declared in the [`arguments`](#frontmatter-reference) frontmatter list. Names map to positions in order, so with `arguments: [issue, branch]` the placeholder `$issue` expands to the first argument and `$branch` to the second. |

215| `${CLAUDE_SESSION_ID}` | The current session ID. Useful for logging, creating session-specific files, or correlating skill output with sessions. |217| `${CLAUDE_SESSION_ID}` | The current session ID. Useful for logging, creating session-specific files, or correlating skill output with sessions. |

216| `${CLAUDE_SKILL_DIR}` | The directory containing the skill's `SKILL.md` file. For plugin skills, this is the skill's subdirectory within the plugin, not the plugin root. Use this in bash injection commands to reference scripts or files bundled with the skill, regardless of the current working directory. |218| `${CLAUDE_SKILL_DIR}` | The directory containing the skill's `SKILL.md` file. For plugin skills, this is the skill's subdirectory within the plugin, not the plugin root. Use this in bash injection commands to reference scripts or files bundled with the skill, regardless of the current working directory. |

217 219

464 466

465### Restrict Claude's skill access467### Restrict Claude's skill access

466 468

467By default, Claude can invoke any skill that doesn't have `disable-model-invocation: true` set. Skills that define `allowed-tools` grant Claude access to those tools without per-use approval when the skill is active. Your [permission settings](/en/permissions) still govern baseline approval behavior for all other tools. Built-in commands like `/compact` and `/init` are not available through the Skill tool.469By default, Claude can invoke any skill that doesn't have `disable-model-invocation: true` set. Skills that define `allowed-tools` grant Claude access to those tools without per-use approval when the skill is active. Your [permission settings](/en/permissions) still govern baseline approval behavior for all other tools. A few built-in commands are also available through the Skill tool, including `/init`, `/review`, and `/security-review`. Other built-in commands such as `/compact` are not.

468 470

469Three ways to control which skills Claude can invoke:471Three ways to control which skills Claude can invoke:

470 472

717 719

718## Related resources720## Related resources

719 721

722* **[Debug your configuration](/en/debug-your-config)**: diagnose why a skill isn't appearing or triggering

720* **[Subagents](/en/sub-agents)**: delegate tasks to specialized agents723* **[Subagents](/en/sub-agents)**: delegate tasks to specialized agents

721* **[Plugins](/en/plugins)**: package and distribute skills with other extensions724* **[Plugins](/en/plugins)**: package and distribute skills with other extensions

722* **[Hooks](/en/hooks)**: automate workflows around tool events725* **[Hooks](/en/hooks)**: automate workflows around tool events

statusline.md +5 −5

Details

25 25

26## Set up a status line26## Set up a status line

27 27

28Use the [`/statusline` command](#use-the-statusline-command) to have Claude Code generate a script for you, or [manually create a script](#manually-configure-a-status-line) and add it to your settings.28Use the [`/statusline` command](#use-the-%2Fstatusline-command) to have Claude Code generate a script for you, or [manually create a script](#manually-configure-a-status-line) and add it to your settings.

29 29

30### Use the /statusline command30### Use the /statusline command

31 31

72 72

73This walkthrough shows what's happening under the hood by manually creating a status line that displays the current model, working directory, and context window usage percentage.73This walkthrough shows what's happening under the hood by manually creating a status line that displays the current model, working directory, and context window usage percentage.

74 74

~~75<Note>Running [`/statusline`](#use-the-statusline-command) with a description of what you want configures all of this for you automatically.</Note>~~75<Note>Running [`/statusline`](#use-the-%2Fstatusline-command) with a description of what you want configures all of this for you automatically.</Note>

76 76

77These examples use Bash scripts, which work on macOS and Linux. On Windows, see [Windows configuration](#windows-configuration) for PowerShell and Git Bash examples.77These examples use Bash scripts, which work on macOS and Linux. On Windows, see [Windows configuration](#windows-configuration) for PowerShell and Git Bash examples.

78 78

155| `workspace.project_dir` | Directory where Claude Code was launched, which may differ from `cwd` if the working directory changes during a session |155| `workspace.project_dir` | Directory where Claude Code was launched, which may differ from `cwd` if the working directory changes during a session |

156| `workspace.added_dirs` | Additional directories added via `/add-dir` or `--add-dir`. Empty array if none have been added |156| `workspace.added_dirs` | Additional directories added via `/add-dir` or `--add-dir`. Empty array if none have been added |

157| `workspace.git_worktree` | Git worktree name when the current directory is inside a linked worktree created with `git worktree add`. Absent in the main working tree. Populated for any git worktree, unlike `worktree.*` which applies only to `--worktree` sessions |157| `workspace.git_worktree` | Git worktree name when the current directory is inside a linked worktree created with `git worktree add`. Absent in the main working tree. Populated for any git worktree, unlike `worktree.*` which applies only to `--worktree` sessions |

190 "session_name": "my-session",190 "session_name": "my-session",

191 "transcript_path": "/path/to/transcript.jsonl",191 "transcript_path": "/path/to/transcript.jsonl",

192 "model": {192 "model": {

193 "id": "claude-opus-4-6",193 "id": "claude-opus-4-7",

194 "display_name": "Opus"194 "display_name": "Opus"

195 },195 },

196 "workspace": {196 "workspace": {

460 460

461### Cost and duration tracking461### Cost and duration tracking

462 462

463Track your session's API costs and elapsed time. The `cost.total_cost_usd` field accumulates the cost of all API calls in the current session. The `cost.total_duration_ms` field measures total elapsed time since the session started, while `cost.total_api_duration_ms` tracks only the time spent waiting for API responses.463Track your session's API costs and elapsed time. The `cost.total_cost_usd` field accumulates the estimated cost of all API calls in the current session. The `cost.total_duration_ms` field measures total elapsed time since the session started, while `cost.total_api_duration_ms` tracks only the time spent waiting for API responses.

464 464

465Each script formats cost as currency and converts milliseconds to minutes and seconds:465Each script formats cost as currency and converts milliseconds to minutes and seconds:

466 466

sub-agents.md +9 −7

Details

234| `description` | Yes | When Claude should delegate to this subagent |234| `description` | Yes | When Claude should delegate to this subagent |

235| `tools` | No | [Tools](#available-tools) the subagent can use. Inherits all tools if omitted |235| `tools` | No | [Tools](#available-tools) the subagent can use. Inherits all tools if omitted |

236| `disallowedTools` | No | Tools to deny, removed from inherited or specified list |236| `disallowedTools` | No | Tools to deny, removed from inherited or specified list |

237| `model` | No | [Model](#choose-a-model) to use: `sonnet`, `opus`, `haiku`, a full model ID (for example, `claude-opus-4-6`), or `inherit`. Defaults to `inherit` |237| `model` | No | [Model](#choose-a-model) to use: `sonnet`, `opus`, `haiku`, a full model ID (for example, `claude-opus-4-7`), or `inherit`. Defaults to `inherit` |

238| `permissionMode` | No | [Permission mode](#permission-modes): `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, or `plan` |238| `permissionMode` | No | [Permission mode](#permission-modes): `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, or `plan` |

239| `maxTurns` | No | Maximum number of agentic turns before the subagent stops |239| `maxTurns` | No | Maximum number of agentic turns before the subagent stops |

240| `skills` | No | [Skills](/en/skills) to load into the subagent's context at startup. The full skill content is injected, not just made available for invocation. Subagents don't inherit skills from the parent conversation |240| `skills` | No | [Skills](/en/skills) to load into the subagent's context at startup. The full skill content is injected, not just made available for invocation. Subagents don't inherit skills from the parent conversation |

242| `hooks` | No | [Lifecycle hooks](#define-hooks-for-subagents) scoped to this subagent |242| `hooks` | No | [Lifecycle hooks](#define-hooks-for-subagents) scoped to this subagent |

243| `memory` | No | [Persistent memory scope](#enable-persistent-memory): `user`, `project`, or `local`. Enables cross-session learning |243| `memory` | No | [Persistent memory scope](#enable-persistent-memory): `user`, `project`, or `local`. Enables cross-session learning |

244| `background` | No | Set to `true` to always run this subagent as a [background task](#run-subagents-in-foreground-or-background). Default: `false` |244| `background` | No | Set to `true` to always run this subagent as a [background task](#run-subagents-in-foreground-or-background). Default: `false` |

245| `effort` | No | Effort level when this subagent is active. Overrides the session effort level. Default: inherits from session. Options: `low`, `medium`, `high`, `max` (Opus 4.6 only) |245| `effort` | No | Effort level when this subagent is active. Overrides the session effort level. Default: inherits from session. Options: `low`, `medium`, `high`, `xhigh`, `max`; available levels depend on the model |

246| `isolation` | No | Set to `worktree` to run the subagent in a temporary [git worktree](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), giving it an isolated copy of the repository. The worktree is automatically cleaned up if the subagent makes no changes |246| `isolation` | No | Set to `worktree` to run the subagent in a temporary [git worktree](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), giving it an isolated copy of the repository. The worktree is automatically cleaned up if the subagent makes no changes |

247| `color` | No | Display color for the subagent in the task list and transcript. Accepts `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, or `cyan` |247| `color` | No | Display color for the subagent in the task list and transcript. Accepts `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, or `cyan` |

248| `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main session agent (via `--agent` or the `agent` setting). [Commands](/en/commands) and [skills](/en/skills) are processed. Prepended to any user-provided prompt |248| `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main session agent (via `--agent` or the `agent` setting). [Commands](/en/commands) and [skills](/en/skills) are processed. Prepended to any user-provided prompt |

252The `model` field controls which [AI model](/en/model-config) the subagent uses:252The `model` field controls which [AI model](/en/model-config) the subagent uses:

253 253

254* **Model alias**: Use one of the available aliases: `sonnet`, `opus`, or `haiku`254* **Model alias**: Use one of the available aliases: `sonnet`, `opus`, or `haiku`

255* **Full model ID**: Use a full model ID such as `claude-opus-4-6` or `claude-sonnet-4-6`. Accepts the same values as the `--model` flag255* **Full model ID**: Use a full model ID such as `claude-opus-4-7` or `claude-sonnet-4-6`. Accepts the same values as the `--model` flag

256* **inherit**: Use the same model as the main conversation256* **inherit**: Use the same model as the main conversation

257* **Omitted**: If not specified, defaults to `inherit` (uses the same model as the main conversation)257* **Omitted**: If not specified, defaults to `inherit` (uses the same model as the main conversation)

258 258

361 Use `bypassPermissions` with caution. It skips permission prompts, allowing the subagent to execute operations without approval. Writes to `.git`, `.claude`, `.vscode`, `.idea`, and `.husky` directories still prompt for confirmation, except for `.claude/commands`, `.claude/agents`, and `.claude/skills`. See [permission modes](/en/permission-modes#skip-all-checks-with-bypasspermissions-mode) for details.361 Use `bypassPermissions` with caution. It skips permission prompts, allowing the subagent to execute operations without approval. Writes to `.git`, `.claude`, `.vscode`, `.idea`, and `.husky` directories still prompt for confirmation, except for `.claude/commands`, `.claude/agents`, and `.claude/skills`. See [permission modes](/en/permission-modes#skip-all-checks-with-bypasspermissions-mode) for details.

362</Warning>362</Warning>

363 363

364If the parent uses `bypassPermissions`, this takes precedence and cannot be overridden. If the parent uses [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode), the subagent inherits auto mode and any `permissionMode` in its frontmatter is ignored: the classifier evaluates the subagent's tool calls with the same block and allow rules as the parent session.364If the parent uses `bypassPermissions` or `acceptEdits`, this takes precedence and cannot be overridden. If the parent uses [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode), the subagent inherits auto mode and any `permissionMode` in its frontmatter is ignored: the classifier evaluates the subagent's tool calls with the same block and allow rules as the parent session.

365 365

366#### Preload skills into subagents366#### Preload skills into subagents

367 367

381 381

382The full content of each skill is injected into the subagent's context, not just made available for invocation. Subagents don't inherit skills from the parent conversation; you must list them explicitly.382The full content of each skill is injected into the subagent's context, not just made available for invocation. Subagents don't inherit skills from the parent conversation; you must list them explicitly.

383 383

384You cannot preload skills that set [`disable-model-invocation: true`](/en/skills#control-who-invokes-a-skill), since preloading draws from the same set of skills Claude can invoke. If a listed skill is missing or disabled, Claude Code skips it and logs a warning to the debug log.

385

384<Note>386<Note>

385 This is the inverse of [running a skill in a subagent](/en/skills#run-skills-in-a-subagent). With `skills` in a subagent, the subagent controls the system prompt and loads skill content. With `context: fork` in a skill, the skill content is injected into the agent you specify. Both use the same underlying system.387 This is the inverse of [running a skill in a subagent](/en/skills#run-skills-in-a-subagent). With `skills` in a subagent, the subagent controls the system prompt and loads skill content. With `context: fork` in a skill, the skill content is injected into the agent you specify. Both use the same underlying system.

386</Note>388</Note>

500Define hooks directly in the subagent's markdown file. These hooks only run while that specific subagent is active and are cleaned up when it finishes.502Define hooks directly in the subagent's markdown file. These hooks only run while that specific subagent is active and are cleaned up when it finishes.

501 503

502<Note>504<Note>

503 Frontmatter hooks fire when the agent is spawned as a subagent through the Agent tool or an @-mention. They do not fire when the agent runs as the main session via [`--agent`](#invoke-subagents-explicitly) or the `agent` setting. For session-wide hooks, configure them in [`settings.json`](/en/hooks).505 Frontmatter hooks fire when the agent is spawned as a subagent through the Agent tool or an @-mention, and when the agent runs as the main session via [`--agent`](#invoke-subagents-explicitly) or the `agent` setting. In the main-session case they run alongside any hooks defined in [`settings.json`](/en/hooks).

504</Note>506</Note>

505 507

506All [hook events](/en/hooks#hook-events) are supported. The most common events for subagents are:508All [hook events](/en/hooks#hook-events) are supported. The most common events for subagents are:

531---533---

532```534```

533 535

534`Stop` hooks in frontmatter are automatically converted to `SubagentStop` events.536When the agent is invoked as a subagent, `Stop` hooks in frontmatter are automatically converted to `SubagentStop` events.

535 537

536#### Project-level hooks for subagent events538#### Project-level hooks for subagent events

537 539

688 690

689Consider [Skills](/en/skills) instead when you want reusable prompts or workflows that run in the main conversation context rather than isolated subagent context.691Consider [Skills](/en/skills) instead when you want reusable prompts or workflows that run in the main conversation context rather than isolated subagent context.

690 692

691For a quick question about something already in your conversation, use [`/btw`](/en/interactive-mode#side-questions-with-btw) instead of a subagent. It sees your full context but has no tool access, and the answer is discarded rather than added to history.693For a quick question about something already in your conversation, use [`/btw`](/en/interactive-mode#side-questions-with-%2Fbtw) instead of a subagent. It sees your full context but has no tool access, and the answer is discarded rather than added to history.

692 694

693<Note>695<Note>

694 Subagents cannot spawn other subagents. If your workflow requires nested delegation, use [Skills](/en/skills) or [chain subagents](#chain-subagents) from the main conversation.696 Subagents cannot spawn other subagents. If your workflow requires nested delegation, use [Skills](/en/skills) or [chain subagents](#chain-subagents) from the main conversation.

terminal-config.md +106 −65

Details

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.

4 4

~~5# Optimize your terminal setup~~5# Configure your terminal for Claude Code

6 6

~~7> Claude Code works best when your terminal is properly configured. Follow these guidelines to optimize your experience.~~7> Fix Shift+Enter for newlines, get a terminal bell when Claude finishes, configure tmux, match the color theme, and enable Vim mode in the Claude Code CLI.

8 8

~~9### Themes and appearance~~9Claude Code works in any terminal without configuration. This page is for when something specific is not behaving the way you expect. Find your symptom below. If everything already feels right, you do not need this page.

10 10

~~11Claude cannot control the theme of your terminal. That's handled by your terminal application. You can match Claude Code's theme to your terminal any time via the `/config` command.~~11* [Shift+Enter submits instead of inserting a newline](#enter-multiline-prompts)

12* [Option-key shortcuts do nothing on macOS](#enable-option-key-shortcuts-on-macos)

13* [No sound or alert when Claude finishes](#get-a-terminal-bell-or-notification)

14* [You run Claude Code inside tmux](#configure-tmux)

15* [Display flickers or scrollback jumps](#switch-to-fullscreen-rendering)

16* [You want Vim keys in the prompt](#edit-prompts-with-vim-keybindings)

12 17

13For additional customization of the Claude Code interface itself, you can configure a [custom status line](/en/statusline) to display contextual information like the current model, working directory, or git branch at the bottom of your terminal.18This page is about getting your terminal to send the right signals to Claude Code. To change which keys Claude Code itself responds to, see [keybindings](/en/keybindings) instead.

14 19

~~15### Line breaks~~20## Enter multiline prompts

16 21

~~17You have several options for entering line breaks into Claude Code:~~22Pressing Enter submits your message. To add a line break without submitting, press Ctrl+J, or type `\` and then press Enter. Both work in every terminal with no setup.

18 23

~~19* **Quick escape**: Type `\` followed by Enter to create a newline~~24In most terminals you can also press Shift+Enter, but support varies by terminal emulator:

~~20* **Ctrl+J**: Sends a line feed character, which works as a newline in any terminal without configuration~~

~~21* **Shift+Enter**: Works out of the box in iTerm2, WezTerm, Ghostty, and Kitty~~

~~22* **Keyboard shortcut**: Set up a keybinding to insert a newline in other terminals~~

23 25

~~24#### Set up Shift+Enter with /terminal-setup~~26| Terminal | Shift+Enter for newline |

27| :---------------------------------------------------------------------------------- | :------------------------------------------ |

28| Ghostty, Kitty, iTerm2, WezTerm, Warp, Apple Terminal | Works without setup |

29| VS Code, Cursor, Windsurf, Alacritty, Zed | Run `/terminal-setup` once |

30| Windows Terminal, gnome-terminal, JetBrains IDEs such as PyCharm and Android Studio | Not available; use Ctrl+J or `\` then Enter |

25 31

~~26Run `/terminal-setup` within Claude Code to automatically configure Shift+Enter for VS Code, Alacritty, Zed, and Warp.~~32For VS Code, Cursor, Windsurf, Alacritty, and Zed, `/terminal-setup` writes Shift+Enter and other keybindings into the terminal's configuration file. In VS Code, Cursor, and Windsurf it also sets `terminal.integrated.mouseWheelScrollSensitivity` in the editor settings for smoother scrolling in [fullscreen mode](/en/fullscreen). Existing bindings and settings are left in place; if you see a message such as `VSCode terminal Shift+Enter key binding already configured`, no change was made. Run `/terminal-setup` directly in the host terminal rather than inside tmux or screen, since it needs to write to the host terminal's configuration.

27 33

~~28<Note>~~34If you are running inside tmux, Shift+Enter also requires the [tmux configuration below](#configure-tmux) even when the outer terminal supports it.

29 The `/terminal-setup` command is only visible in terminals that require manual configuration. If you're using iTerm2, WezTerm, Ghostty, or Kitty, you won't see this command because Shift+Enter already works natively.

~~30</Note>~~

31 35

~~32#### Set up Shift+Enter in tmux~~36To bind newline to a different key, or to swap behavior so Enter inserts a newline and Shift+Enter submits, map the `chat:newline` and `chat:submit` actions in your [keybindings file](/en/keybindings).

33 37

34Inside tmux, `Shift+Enter` submits instead of inserting a newline unless extended key reporting is enabled. Add these lines to `~/.tmux.conf`, then run `tmux source-file ~/.tmux.conf` to reload your configuration:38## Enable Option key shortcuts on macOS

35 39

~~36```text theme={null}~~40Some Claude Code shortcuts use the Option key, such as Option+Enter for a newline or Option+P to switch models. On macOS, most terminals do not send Option as a modifier by default, so these shortcuts do nothing until you enable it. The terminal setting for this is usually labeled "Use Option as Meta Key"; Meta is the historical Unix name for the key now labeled Option or Alt.

~~37set -s extended-keys on~~

~~38set -as terminal-features 'xterm*:extkeys'~~

~~39```~~

41Claude Code requests extended keys at startup, but tmux ignores the request unless `extended-keys` is set to `on`. The `terminal-features` line tells tmux that your outer terminal can send these sequences.

~~43#### Set up Option+Enter on macOS~~

~~45On macOS, you can use Option+Enter as the newline keybinding in Terminal.app, iTerm2, and the VS Code terminal after enabling the Option-as-Meta setting.~~

46 41

47<Tabs>42<Tabs>

~~48 <Tab title="Terminal.app">~~43 <Tab title="Apple Terminal">

~~49 1. Open Settings → Profiles → Keyboard~~44 Open Settings → Profiles → Keyboard and check "Use Option as Meta Key".

~~50 2. Check "Use Option as Meta Key"~~45

46 If you accepted Claude Code's first-run prompt that offered "Option+Enter for newlines and visual bell", this is already done. That prompt runs `/terminal-setup` for you, which enables Option as Meta and switches the audio bell to a visual screen flash in your Apple Terminal profile.

51 </Tab>47 </Tab>

52 48

53 <Tab title="iTerm2">49 <Tab title="iTerm2">

~~54 1. Open Settings → Profiles → Keys~~50 Open Settings → Profiles → Keys → General and set Left Option key and Right Option key to "Esc+".

~~55 2. Under General, set Left/Right Option key to "Esc+"~~

56 </Tab>51 </Tab>

57 52

58 <Tab title="VS Code">53 <Tab title="VS Code">

~~59 Set `"terminal.integrated.macOptionIsMeta": true` in VS Code settings.~~54 Add `"terminal.integrated.macOptionIsMeta": true` to your VS Code settings.

60 </Tab>55 </Tab>

61</Tabs>56</Tabs>

62 57

~~63### Notification setup~~58For Ghostty, Kitty, and other terminals, look for an Option-as-Alt or Option-as-Meta setting in the terminal's configuration file.

60## Get a terminal bell or notification

62When Claude finishes a task or pauses for a permission prompt, it fires a notification event. Surfacing this as a terminal bell or desktop notification lets you switch to other work while a long task runs.

64Claude Code sends a desktop notification only in Ghostty, Kitty, and iTerm2; every other terminal needs a [Notification hook](#play-a-sound-with-a-notification-hook) instead. The notification also reaches your local machine over SSH, so a remote session can still alert you. Ghostty and Kitty forward it to your OS notification center without further setup. iTerm2 requires you to enable forwarding:

64 65

65When Claude finishes working and is waiting for your input, it fires a notification event. You can surface this event as a desktop notification through your terminal or run custom logic with [notification hooks](/en/hooks#notification).66<Steps>

67 <Step title="Open iTerm2 notification settings">

68 Go to Settings → Profiles → Terminal.

69 </Step>

66 70

~~67#### Terminal notifications~~71 <Step title="Enable alerts">

72 Check "Notification Center Alerts", then click "Filter Alerts" and enable "Send escape sequence-generated alerts".

73 </Step>

74</Steps>

68 75

~~69Kitty and Ghostty support desktop notifications without additional configuration. iTerm 2 requires setup:~~76If notifications still do not appear, confirm that your terminal application has notification permission in your OS settings, and if you are running inside tmux, [enable passthrough](#configure-tmux).

70 77

~~711. Open iTerm 2 Settings → Profiles → Terminal~~78### Play a sound with a Notification hook

~~722. Enable "Notification Center Alerts"~~

~~733. Click "Filter Alerts" and check "Send escape sequence-generated alerts"~~

74 79

~~75If notifications aren't appearing, verify that your terminal app has notification permissions in your OS settings.~~80In any terminal you can configure a [Notification hook](/en/hooks-guide#get-notified-when-claude-needs-input) to play a sound or run a custom command when Claude needs your attention. Hooks run alongside the desktop notification rather than replacing it. Terminals such as Warp or Apple Terminal rely on a hook alone since Claude Code does not send them a desktop notification.

76 81

77When running Claude Code inside tmux, notifications and the [terminal progress bar](/en/settings#global-config-settings) only reach the outer terminal, such as iTerm2, Kitty, or Ghostty, if you enable passthrough in your tmux configuration:82The example below plays a system sound on macOS. The linked guide has desktop notification commands for macOS, Linux, and Windows.

78 83

84```json ~/.claude/settings.json theme={null}

85{

86 "hooks": {

87 "Notification": [

88 {

89 "hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }]

90 }

91 ]

92 }

93}

79```94```

96## Configure tmux

98When Claude Code runs inside tmux, two things break by default: Shift+Enter submits instead of inserting a newline, and desktop notifications and the [progress bar](/en/settings#global-config-settings) never reach the outer terminal. Add these lines to `~/.tmux.conf`, then run `tmux source-file ~/.tmux.conf` to apply them to the running server:

100```bash ~/.tmux.conf theme={null}

80set -g allow-passthrough on101set -g allow-passthrough on

102set -s extended-keys on

103set -as terminal-features 'xterm*:extkeys'

81```104```

82 105

~~83Without this setting, tmux intercepts the escape sequences and they do not reach the terminal application.~~106The `allow-passthrough` line lets notifications and progress updates reach iTerm2, Ghostty, or Kitty instead of being swallowed by tmux. The `extended-keys` lines let tmux distinguish Shift+Enter from plain Enter so the newline shortcut works.

107

108## Match the color theme

109

110Use the `/theme` command, or the theme picker in `/config`, to choose a Claude Code theme that matches your terminal. Selecting the auto option detects your terminal's light or dark background, so the theme follows OS appearance changes whenever your terminal does. The available themes are built in; there is no custom theme file. Claude Code does not control the terminal's own color scheme, which is set by the terminal application.

111

112To customize what appears at the bottom of the interface, configure a [custom status line](/en/statusline) that shows the current model, working directory, git branch, or other context.

113

114## Switch to fullscreen rendering

115

116If the display flickers or the scroll position jumps while Claude is working, switch to [fullscreen rendering mode](/en/fullscreen). It draws to a separate screen the terminal reserves for full-screen apps instead of appending to your normal scrollback, which keeps memory usage flat and adds mouse support for scrolling and selection. In this mode you scroll with the mouse or PageUp inside Claude Code rather than with your terminal's native scrollback; see the [fullscreen page](/en/fullscreen#search-and-review-the-conversation) for how to search and copy.

84 117

~~85Other terminals, including the default macOS Terminal, do not support native notifications. Use [notification hooks](/en/hooks#notification) instead.~~118Run `/tui fullscreen` to switch in the current session with your conversation intact. To make it the default, set the `CLAUDE_CODE_NO_FLICKER` environment variable before starting Claude Code:

86 119

~~87#### Notification hooks~~120<CodeGroup>

121 ```bash Bash and Zsh theme={null}

122 CLAUDE_CODE_NO_FLICKER=1 claude

123 ```

88 124

89To add custom behavior when notifications fire, such as playing a sound or sending a message, configure a [notification hook](/en/hooks#notification). Hooks run alongside terminal notifications, not as a replacement.125 ```powershell PowerShell theme={null}

126 $env:CLAUDE_CODE_NO_FLICKER = "1"; claude

127 ```

90 128

~~91### Reduce flicker and memory usage~~129 ```json ~/.claude/settings.json theme={null}

130 {

131 "env": {

132 "CLAUDE_CODE_NO_FLICKER": "1"

133 }

134 }

135 ```

136</CodeGroup>

92 137

93If you see flicker during long sessions, or your terminal scroll position jumps to the top while Claude is working, try [fullscreen rendering](/en/fullscreen). It uses an alternate rendering path that keeps memory flat and adds mouse support. Enable it with `CLAUDE_CODE_NO_FLICKER=1`.138## Paste large content

94 139

~~95### Handling large inputs~~140When you paste more than 10,000 characters into the prompt, Claude Code collapses the input to a `[Pasted text]` placeholder so the input box stays usable. The full content is still sent to Claude when you submit.

96 141

~~97When working with extensive code or long instructions:~~142The VS Code integrated terminal can drop characters from very large pastes before they reach Claude Code, so prefer file-based workflows there. For very large inputs such as entire files or long logs, write the content to a file and ask Claude to read it instead of pasting. This keeps the conversation transcript readable and lets Claude reference the file by path in later turns.

98 143

~~99* **Avoid direct pasting**: Claude Code may struggle with very long pasted content~~144## Edit prompts with Vim keybindings

100* **Use file-based workflows**: Write content to a file and ask Claude to read it

101* **Be aware of VS Code limitations**: The VS Code terminal is particularly prone to truncating long pastes

102 145

103### Vim Mode146Claude Code includes a Vim-style editing mode for the prompt input. Enable it through `/config` → Editor mode, or by setting the [`editorMode`](/en/settings#global-config-settings) global config key to `"vim"` in `~/.claude.json`. Set Editor mode back to `normal` to turn it off.

104 147

105Claude Code supports a subset of Vim keybindings that can be enabled via `/config` → Editor mode. To set the mode directly in your config file, set the [`editorMode`](/en/settings#global-config-settings) global config key to `"vim"` in `~/.claude.json`.148Vim mode supports a subset of NORMAL-mode motions and operators, such as `hjkl` navigation and `d`/`c`/`y` with text objects. See the [Vim editor mode reference](/en/interactive-mode#vim-editor-mode) for the full key table. Vim motions are not remappable through the keybindings file.

106 149

107The supported subset includes:150Pressing Enter still submits your prompt in INSERT mode, unlike standard Vim. Use `o` or `O` in NORMAL mode, or Ctrl+J, to insert a newline instead.

108 151

109* Mode switching: `Esc` (to NORMAL), `i`/`I`, `a`/`A`, `o`/`O` (to INSERT)152## Related resources

110* Navigation: `h`/`j`/`k`/`l`, `w`/`e`/`b`, `0`/`$`/`^`, `gg`/`G`, `f`/`F`/`t`/`T` with `;`/`,` repeat

111* Editing: `x`, `dw`/`de`/`db`/`dd`/`D`, `cw`/`ce`/`cb`/`cc`/`C`, `.` (repeat)

112* Yank/paste: `yy`/`Y`, `yw`/`ye`/`yb`, `p`/`P`

113* Text objects: `iw`/`aw`, `iW`/`aW`, `i"`/`a"`, `i'`/`a'`, `i(`/`a(`, `i[`/`a[`, `i{`/`a{`

114* Indentation: `>>`/`<<`

115* Line operations: `J` (join lines)

116 153

117See [Interactive mode](/en/interactive-mode#vim-editor-mode) for the complete reference.154* [Interactive mode](/en/interactive-mode): full keyboard shortcut reference and the Vim key table

155* [Keybindings](/en/keybindings): remap any Claude Code shortcut, including Enter and Shift+Enter

156* [Fullscreen rendering](/en/fullscreen): details on scrolling, search, and copy in fullscreen mode

157* [Hooks guide](/en/hooks-guide): more Notification hook examples for Linux and Windows

158* [Troubleshooting](/en/troubleshooting): fixes for issues outside terminal configuration

tools-reference.md +13 −10

Details

11To add custom tools, connect an [MCP server](/en/mcp). To extend Claude with reusable prompt-based workflows, write a [skill](/en/skills), which runs through the existing `Skill` tool rather than adding a new tool entry.11To add custom tools, connect an [MCP server](/en/mcp). To extend Claude with reusable prompt-based workflows, write a [skill](/en/skills), which runs through the existing `Skill` tool rather than adding a new tool entry.

12 12

14| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------ |14| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------ |

15| `Agent` | Spawns a [subagent](/en/sub-agents) with its own context window to handle a task | No |15| `Agent` | Spawns a [subagent](/en/sub-agents) with its own context window to handle a task | No |

16| `AskUserQuestion` | Asks multiple-choice questions to gather requirements or clarify ambiguity | No |16| `AskUserQuestion` | Asks multiple-choice questions to gather requirements or clarify ambiguity | No |

17| `Bash` | Executes shell commands in your environment. See [Bash tool behavior](#bash-tool-behavior) | Yes |17| `Bash` | Executes shell commands in your environment. See [Bash tool behavior](#bash-tool-behavior) | Yes |

18| `CronCreate` | Schedules a recurring or one-shot prompt within the current session (gone when Claude exits). See [scheduled tasks](/en/scheduled-tasks) | No |18| `CronCreate` | Schedules a recurring or one-shot prompt within the current session. Tasks are session-scoped and restored on `--resume` or `--continue` if unexpired. See [scheduled tasks](/en/scheduled-tasks) | No |

19| `CronDelete` | Cancels a scheduled task by ID | No |19| `CronDelete` | Cancels a scheduled task by ID | No |

20| `CronList` | Lists all scheduled tasks in the session | No |20| `CronList` | Lists all scheduled tasks in the session | No |

21| `Edit` | Makes targeted edits to specific files | Yes |21| `Edit` | Makes targeted edits to specific files | Yes |

22| `EnterPlanMode` | Switches to plan mode to design an approach before coding | No |22| `EnterPlanMode` | Switches to plan mode to design an approach before coding | No |

23| `EnterWorktree` | Creates an isolated [git worktree](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) and switches into it. Pass a `path` to switch into an existing worktree of the current repository instead of creating a new one | No |23| `EnterWorktree` | Creates an isolated [git worktree](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) and switches into it. Pass a `path` to switch into an existing worktree of the current repository instead of creating a new one. Not available to subagents | No |

24| `ExitPlanMode` | Presents a plan for approval and exits plan mode | Yes |24| `ExitPlanMode` | Presents a plan for approval and exits plan mode | Yes |

25| `ExitWorktree` | Exits a worktree session and returns to the original directory | No |25| `ExitWorktree` | Exits a worktree session and returns to the original directory. Not available to subagents | No |

26| `Glob` | Finds files based on pattern matching | No |26| `Glob` | Finds files based on pattern matching | No |

27| `Grep` | Searches for patterns in file contents | No |27| `Grep` | Searches for patterns in file contents | No |

28| `ListMcpResourcesTool` | Lists resources exposed by connected [MCP servers](/en/mcp) | No |28| `ListMcpResourcesTool` | Lists resources exposed by connected [MCP servers](/en/mcp) | No |

29| `LSP` | Code intelligence via language servers: jump to definitions, find references, report type errors and warnings. See [LSP tool behavior](#lsp-tool-behavior) | No |29| `LSP` | Code intelligence via language servers: jump to definitions, find references, report type errors and warnings. See [LSP tool behavior](#lsp-tool-behavior) | No |

30| `Monitor` | Runs a command in the background and feeds each output line back to Claude, so it can react to log entries, file changes, or polled status mid-conversation. See [Monitor tool](#monitor-tool) | Yes |30| `Monitor` | Runs a command in the background and feeds each output line back to Claude, so it can react to log entries, file changes, or polled status mid-conversation. See [Monitor tool](#monitor-tool) | Yes |

31| `NotebookEdit` | Modifies Jupyter notebook cells | Yes |31| `NotebookEdit` | Modifies Jupyter notebook cells | Yes |

32| `PowerShell` | Executes PowerShell commands on Windows. Opt-in preview. See [PowerShell tool](#powershell-tool) | Yes |32| `PowerShell` | Executes PowerShell commands natively. See [PowerShell tool](#powershell-tool) for availability | Yes |

33| `Read` | Reads the contents of files | No |33| `Read` | Reads the contents of files | No |

34| `ReadMcpResourceTool` | Reads a specific MCP resource by URI | No |34| `ReadMcpResourceTool` | Reads a specific MCP resource by URI | No |

35| `SendMessage` | Sends a message to an [agent team](/en/agent-teams) teammate, or [resumes a subagent](/en/sub-agents#resume-subagents) by its agent ID. Stopped subagents auto-resume in the background. Only available when `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is set | No |35| `SendMessage` | Sends a message to an [agent team](/en/agent-teams) teammate, or [resumes a subagent](/en/sub-agents#resume-subagents) by its agent ID. Stopped subagents auto-resume in the background. Only available when `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is set | No |

91 91

92Monitor uses the same [permission rules as Bash](/en/permissions#tool-specific-permission-rules), so `allow` and `deny` patterns you have set for Bash apply here too. It is not available on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry. It is also not available when `DISABLE_TELEMETRY` or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` is set.92Monitor uses the same [permission rules as Bash](/en/permissions#tool-specific-permission-rules), so `allow` and `deny` patterns you have set for Bash apply here too. It is not available on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry. It is also not available when `DISABLE_TELEMETRY` or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` is set.

93 93

94Plugins can declare monitors that start automatically when the plugin is active, instead of asking Claude to start them. See [plugin monitors](/en/plugins-reference#monitors).

94## PowerShell tool96## PowerShell tool

95 97

~~96On Windows, Claude Code can run PowerShell commands natively instead of routing through Git Bash. This is an opt-in preview.~~98The PowerShell tool lets Claude run PowerShell commands natively. On Windows, this means commands run in PowerShell instead of routing through Git Bash. The tool is rolling out progressively on Windows and is opt-in on Linux, macOS, and WSL.

97 99

98### Enable the PowerShell tool100### Enable the PowerShell tool

99 101

107}109}

108```110```

109 111

110Claude Code auto-detects `pwsh.exe` (PowerShell 7+) with a fallback to `powershell.exe` (PowerShell 5.1). The Bash tool remains registered alongside the PowerShell tool, so you may need to ask Claude to use PowerShell.112On Windows, set the variable to `0` to opt out of the rollout. On Linux, macOS, and WSL, the tool requires PowerShell 7 or later: install `pwsh` and ensure it is on your `PATH`.

113

114On Windows, Claude Code auto-detects `pwsh.exe` for PowerShell 7+ with a fallback to `powershell.exe` for PowerShell 5.1. The Bash tool remains registered alongside the PowerShell tool, so you may need to ask Claude to use PowerShell.

111 115

112### Shell selection in settings, hooks, and skills116### Shell selection in settings, hooks, and skills

113 117

125 129

126* Auto mode does not work with the PowerShell tool yet130* Auto mode does not work with the PowerShell tool yet

127* PowerShell profiles are not loaded131* PowerShell profiles are not loaded

128* Sandboxing is not supported132* On Windows, sandboxing is not supported

129* Only supported on native Windows, not WSL133* On Windows, Git Bash is still required to start Claude Code

130* Git Bash is still required to start Claude Code

131 134

132## Check which tools are available135## Check which tools are available

133 136

troubleshooting.md +29 −15

Details

15Find the error message or symptom you're seeing:15Find the error message or symptom you're seeing:

16 16

17| What you see | Solution |17| What you see | Solution |

18| :---------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- |18| :-------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- |

20| `syntax error near unexpected token '<'` | [Install script returns HTML](#install-script-returns-html-instead-of-a-shell-script) |20| `syntax error near unexpected token '<'` | [Install script returns HTML](#install-script-returns-html-instead-of-a-shell-script) |

21| `curl: (56) Failure writing output to destination` | [Download script first, then run it](#curl-56-failure-writing-output-to-destination) |21| `curl: (56) Failure writing output to destination` | [Download script first, then run it](#curl-56-failure-writing-output-to-destination) |

33| `App unavailable in region` | Claude Code is not available in your country. See [supported countries](https://www.anthropic.com/supported-countries). |33| `App unavailable in region` | Claude Code is not available in your country. See [supported countries](https://www.anthropic.com/supported-countries). |

36| `API Error: 500`, `529 Overloaded`, `429`, or other 4xx and 5xx errors not listed above | See the [Error reference](/en/errors) |

36 37

37If your issue isn't listed, work through these diagnostic steps.38If your issue isn't listed, work through these diagnostic steps.

38 39

40 41

41### Check network connectivity42### Check network connectivity

42 43

~~43The installer downloads from `storage.googleapis.com`. Verify you can reach it:~~44The installer downloads from `downloads.claude.ai`. Verify you can reach it:

44 45

45```bash theme={null}46```bash theme={null}

~~46curl -sI https://storage.googleapis.com~~47curl -sI https://downloads.claude.ai

47```48```

48 49

49If this fails, your network may be blocking the connection. Common causes:50If this fails, your network may be blocking the connection. Common causes:

50 51

~~51* Corporate firewalls or proxies blocking Google Cloud Storage~~52* Corporate firewalls or proxies blocking `downloads.claude.ai`

52* Regional network restrictions: try a VPN or alternative network53* Regional network restrictions: try a VPN or alternative network

53* TLS/SSL issues: update your system's CA certificates, or check if `HTTPS_PROXY` is configured54* TLS/SSL issues: update your system's CA certificates, or check if `HTTPS_PROXY` is configured

54 55

278 279

279**Solutions:**280**Solutions:**

280 281

2811. **Check network stability**: Claude Code binaries are hosted on Google Cloud Storage. Test that you can reach it:2821. **Check network stability**: Claude Code binaries are hosted at `downloads.claude.ai`. Test that you can reach it:

282 ```bash theme={null}283 ```bash theme={null}

283 curl -fsSL https://storage.googleapis.com -o /dev/null284 curl -fsSL https://downloads.claude.ai -o /dev/null

284 ```285 ```

285 If the command completes silently, your connection is fine and the issue is likely intermittent. Retry the install command. If you see an error, your network may be blocking the download.286 If the command completes silently, your connection is fine and the issue is likely intermittent. Retry the install command. If you see an error, your network may be blocking the download.

286 287

336 ```337 ```

337 Alternatively, install with `winget install Anthropic.ClaudeCode`, which avoids curl entirely.338 Alternatively, install with `winget install Anthropic.ClaudeCode`, which avoids curl entirely.

338 339

339### `Failed to fetch version from storage.googleapis.com`340### `Failed to fetch version from downloads.claude.ai`

340 341

341The installer couldn't reach the download server. This typically means `storage.googleapis.com` is blocked on your network.342The installer couldn't reach the download server. This typically means `downloads.claude.ai` is blocked on your network.

342 343

343**Solutions:**344**Solutions:**

344 345

3451. **Test connectivity directly**:3461. **Test connectivity directly**:

346 ```bash theme={null}347 ```bash theme={null}

347 curl -sI https://storage.googleapis.com348 curl -sI https://downloads.claude.ai

348 ```349 ```

349 350

3502. **If behind a proxy**, set `HTTPS_PROXY` so the installer can route through it. See [proxy configuration](/en/network-config#proxy-configuration) for details.3512. **If behind a proxy**, set `HTTPS_PROXY` so the installer can route through it. See [proxy configuration](/en/network-config#proxy-configuration) for details.

501 ```502 ```

502 If it shows `linux-vdso.so` or references to `/lib/x86_64-linux-gnu/`, you're on glibc. If it shows `musl`, you're on musl.503 If it shows `linux-vdso.so` or references to `/lib/x86_64-linux-gnu/`, you're on glibc. If it shows `musl`, you're on musl.

503 504

5042. **If you're on glibc but got the musl binary**, remove the installation and reinstall. You can also manually download the correct binary from the GCS bucket at `https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/{VERSION}/manifest.json`. File a [GitHub issue](https://github.com/anthropics/claude-code/issues) with the output of `ldd /bin/ls` and `ls /lib/libc.musl*`.5052. **If you're on glibc but got the musl binary**, remove the installation and reinstall. You can also manually download the correct binary using the manifest at `https://downloads.claude.ai/claude-code-releases/{VERSION}/manifest.json`. File a [GitHub issue](https://github.com/anthropics/claude-code/issues) with the output of `ldd /bin/ls` and `ls /lib/libc.musl*`.

505 506

5063. **If you're actually on musl** (Alpine Linux), install the required packages:5073. **If you're actually on musl** (Alpine Linux), install the required packages:

507 ```bash theme={null}508 ```bash theme={null}

638curl -fsSL https://claude.ai/install.sh | bash639curl -fsSL https://claude.ai/install.sh | bash

639```640```

640 641

642### Native binary not found after npm install

643

644The `@anthropic-ai/claude-code` npm package pulls in the native binary through a per-platform optional dependency such as `@anthropic-ai/claude-code-darwin-arm64`. If running `claude` after install prints `Could not find native binary package "@anthropic-ai/claude-code-<platform>"`, check the following causes:

645

646* **Optional dependencies are disabled.** Remove `--omit=optional` from your npm install command, `--no-optional` from pnpm, or `--ignore-optional` from yarn, and check that `.npmrc` does not set `optional=false`. Then reinstall. The native binary is delivered only as an optional dependency, so there is no JavaScript fallback if it is skipped.

647* **Unsupported platform.** Prebuilt binaries are published for `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64`, and `win32-arm64`. Claude Code does not ship a binary for other platforms; see the [system requirements](/en/setup#system-requirements).

648* **Corporate npm mirror is missing the platform packages.** Ensure your registry mirrors all eight `@anthropic-ai/claude-code-*` platform packages in addition to the meta package.

649

650Installing with `--ignore-scripts` does not trigger this error. The postinstall step that links the binary into place is skipped, so Claude Code falls back to a wrapper that locates and spawns the platform binary on each launch. This works but starts more slowly; reinstall with scripts enabled for direct execution.

651

641## Permissions and authentication652## Permissions and authentication

642 653

643These sections address login failures, token issues, and permission prompt behavior.654These sections address login failures, token issues, and permission prompt behavior.

7792. Close and restart Claude Code between major tasks7902. Close and restart Claude Code between major tasks

7803. Consider adding large build directories to your `.gitignore` file7913. Consider adding large build directories to your `.gitignore` file

781 792

793If memory usage stays high after these steps, run `/heapdump` to write a JavaScript heap snapshot and a memory breakdown to `~/Desktop`. The breakdown shows resident set size, JS heap, array buffers, and unaccounted native memory, which helps identify whether the growth is in JavaScript objects or in native code. Open the `.heapsnapshot` file in Chrome DevTools under Memory → Load to inspect retainers. Attach both files when reporting a memory issue on [GitHub](https://github.com/anthropics/claude-code/issues).

794

782### Auto-compaction stops with a thrashing error795### Auto-compaction stops with a thrashing error

783 796

784If you see `Autocompact is thrashing: the context refilled to the limit...`, automatic compaction succeeded but a file or tool output immediately refilled the context window several times in a row. Claude Code stops retrying to avoid wasting API calls on a loop that isn't making progress.797If you see `Autocompact is thrashing: the context refilled to the limit...`, automatic compaction succeeded but a file or tool output immediately refilled the context window several times in a row. Claude Code stops retrying to avoid wasting API calls on a loop that isn't making progress.

963 976

964If you're experiencing issues not covered here:977If you're experiencing issues not covered here:

965 978

9661. Use the `/feedback` command within Claude Code to report problems directly to Anthropic9791. See the [Error reference](/en/errors) for `API Error: 5xx`, `529 Overloaded`, `429`, and request validation errors that appear during a session

9672. Check the [GitHub repository](https://github.com/anthropics/claude-code) for known issues9802. Use the `/feedback` command within Claude Code to report problems directly to Anthropic

9683. Run `/doctor` to diagnose issues. It checks:9813. Check the [GitHub repository](https://github.com/anthropics/claude-code) for known issues

9824. Run `/doctor` to diagnose issues. It checks:

969 * Installation type, version, and search functionality983 * Installation type, version, and search functionality

970 * Auto-update status and available versions984 * Auto-update status and available versions

971 * Invalid settings files (malformed JSON, incorrect types)985 * Invalid settings files (malformed JSON, incorrect types)

972 * MCP server configuration errors986 * MCP server configuration errors, including the same server name defined in multiple scopes with different endpoints

973 * Keybinding configuration problems987 * Keybinding configuration problems

974 * Context usage warnings (large CLAUDE.md files, high MCP token usage, unreachable permission rules)988 * Context usage warnings (large CLAUDE.md files, high MCP token usage, unreachable permission rules)

975 * Plugin and agent loading errors989 * Plugin and agent loading errors

9764. Ask Claude directly about its capabilities and features - Claude has built-in access to its documentation9905. Ask Claude directly about its capabilities and features - Claude has built-in access to its documentation

ultraplan.md +1 −0

Details

80 80

81* [Claude Code on the web](/en/claude-code-on-the-web): the cloud infrastructure ultraplan runs on81* [Claude Code on the web](/en/claude-code-on-the-web): the cloud infrastructure ultraplan runs on

82* [Plan mode](/en/permission-modes#analyze-before-you-edit-with-plan-mode): how planning works in a local session82* [Plan mode](/en/permission-modes#analyze-before-you-edit-with-plan-mode): how planning works in a local session

83* [Find bugs with ultrareview](/en/ultrareview): the code review counterpart to ultraplan for catching issues before merge

83* [Remote Control](/en/remote-control): use the claude.ai/code interface with a session running on your own machine84* [Remote Control](/en/remote-control): use the claude.ai/code interface with a session running on your own machine

ultrareview.md +85 −0 added

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Find bugs with ultrareview

7> Run a deep, multi-agent code review in the cloud with /ultrareview to find and verify bugs before you merge.

9<Note>

10 Ultrareview is a research preview feature available in Claude Code v2.1.86 and later. The feature, pricing, and availability may change based on feedback.

11</Note>

13Ultrareview is a deep code review that runs on Claude Code on the web infrastructure. When you run `/ultrareview`, Claude Code launches a fleet of reviewer agents in a remote sandbox to find bugs in your branch or pull request.

15Compared to a local `/review`, ultrareview offers:

17* **Higher signal**: every reported finding is independently reproduced and verified, so the results focus on real bugs rather than style suggestions

18* **Broader coverage**: many reviewer agents explore the change in parallel, which surfaces issues that a single-pass review can miss

19* **No local resource use**: the review runs entirely in a remote sandbox, so your terminal stays free for other work while it runs

21Ultrareview requires authentication with a Claude.ai account because it runs on Claude Code on the web infrastructure. If you are signed in with an API key only, run `/login` and authenticate with Claude.ai first. Ultrareview is not available when using Claude Code with Amazon Bedrock, Google Cloud Vertex AI, or Microsoft Foundry, and it is not available to organizations that have enabled Zero Data Retention.

23## Run ultrareview from the CLI

25Start a review from any git repository in the Claude Code CLI.

27```text theme={null}

28/ultrareview

29```

31Without arguments, ultrareview reviews the diff between your current branch and the default branch, including any uncommitted and staged changes in your working tree. Claude Code bundles the repository state and uploads it to a remote sandbox for the review.

33To review a GitHub pull request instead, pass the PR number.

35```text theme={null}

36/ultrareview 1234

37```

39In PR mode, the remote sandbox clones the pull request directly from GitHub rather than bundling your local working tree. PR mode requires a `github.com` remote on the repository.

41<Tip>

42 If your repository is too large to bundle, Claude Code prompts you to use PR mode instead. Push your branch and open a draft PR, then run `/ultrareview <PR-number>`.

43</Tip>

45Before launching, Claude Code shows a confirmation dialog with the review scope (including the file and line count when reviewing a branch), your remaining free runs, and the estimated cost. After you confirm, the review continues in the background and you can keep using your session. The command runs only when you invoke it with `/ultrareview`; Claude does not start an ultrareview on its own.

47## Pricing and free runs

49Ultrareview is a premium feature that bills against extra usage rather than your plan's included usage.

51| Plan | Included free runs | After free runs |

52| ------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------- |

53| Pro | 3 free runs through May 5, 2026 | billed as [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

54| Max | 3 free runs through May 5, 2026 | billed as [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

55| Team and Enterprise | none | billed as [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

57Pro and Max subscribers receive three free ultrareview runs to try the feature. These three runs are a one-time allotment per account, do not refresh, and expire on May 5, 2026. After you use all three, or after the free run period ends, each review is billed to extra usage and typically costs \$5 to \$20 depending on the size of the change.

59Because ultrareview always bills as extra usage outside the free runs, your account or organization must have extra usage enabled before you can launch a paid review. If extra usage is not enabled, Claude Code blocks the launch and links you to the billing settings where you can turn it on. You can also run `/extra-usage` to check or change your current setting.

61## Track a running review

63A review typically takes 5 to 10 minutes. The review runs as a background task, so you can keep working in your session, start other commands, or close the terminal entirely.

65Use `/tasks` to see running and completed reviews, open the detail view for a review, or stop a review that is in progress. Stopping a review archives the cloud session, and partial findings are not returned. When the review finishes, the verified findings appear as a notification in your session. Each finding includes the file location and an explanation of the issue so you can ask Claude to fix it directly.

67## How ultrareview compares to /review

69Both commands review code, but they target different stages of your workflow.

71| | `/review` | `/ultrareview` |

72| -------- | ------------------------------ | ------------------------------------------------------------- |

73| Runs | locally in your session | remotely in a cloud sandbox |

74| Depth | single-pass review | multi-agent fleet with independent verification |

75| Duration | seconds to a few minutes | roughly 5 to 10 minutes |

76| Cost | counts toward normal usage | free runs, then roughly \$5 to \$20 per review as extra usage |

77| Best for | quick feedback while iterating | pre-merge confidence on substantial changes |

79Use `/review` for fast feedback as you work. Use `/ultrareview` before merging a substantial change when you want a deeper pass that catches issues a single review might miss.

81## Related resources

83* [Claude Code on the web](/en/claude-code-on-the-web): learn how remote sessions and cloud sandboxes work

84* [Plan complex changes with ultraplan](/en/ultraplan): the planning counterpart to ultrareview for upfront design work

85* [Manage costs effectively](/en/costs): track usage and set spending limits

vs-code.md +5 −5

Details

76 </Step>76 </Step>

77 77

78 <Step title="Review changes">78 <Step title="Review changes">

~~79 When Claude wants to edit a file, it shows a side-by-side comparison of the original and proposed changes, then asks for permission. You can accept, reject, or tell Claude what to do instead.~~79 When Claude wants to edit a file, it shows a side-by-side comparison of the original and proposed changes, then asks for permission. You can accept, reject, or tell Claude what to do instead. If you edit the proposed content directly in the diff view before accepting, Claude is told that you modified it so it does not assume the file matches its original proposal.

80 80

81 <img src="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=e005f9b41c541c5c7c59c082f7c4841c" alt="VS Code showing a diff of Claude's proposed changes with a permission prompt asking whether to make the edit" width="3292" height="1876" data-path="images/vs-code-edits.png" />81 <img src="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=e005f9b41c541c5c7c59c082f7c4841c" alt="VS Code showing a diff of Claude's proposed changes with a permission prompt asking whether to make the edit" width="3292" height="1876" data-path="images/vs-code-edits.png" />

82 </Step>82 </Step>

95* **Permission modes**: click the mode indicator at the bottom of the prompt box to switch modes. In normal mode, Claude asks permission before each action. In Plan mode, Claude describes what it will do and waits for approval before making changes. VS Code automatically opens the plan as a full markdown document where you can add inline comments to give feedback before Claude begins. In auto-accept mode, Claude makes edits without asking. Set the default in VS Code settings under `claudeCode.initialPermissionMode`.95* **Permission modes**: click the mode indicator at the bottom of the prompt box to switch modes. In normal mode, Claude asks permission before each action. In Plan mode, Claude describes what it will do and waits for approval before making changes. VS Code automatically opens the plan as a full markdown document where you can add inline comments to give feedback before Claude begins. In auto-accept mode, Claude makes edits without asking. Set the default in VS Code settings under `claudeCode.initialPermissionMode`.

96* **Command menu**: click `/` or type `/` to open the command menu. Options include attaching files, switching models, toggling extended thinking, viewing plan usage (`/usage`), and starting a [Remote Control](/en/remote-control) session (`/remote-control`). The Customize section provides access to MCP servers, hooks, memory, permissions, and plugins. Items with a terminal icon open in the integrated terminal.96* **Command menu**: click `/` or type `/` to open the command menu. Options include attaching files, switching models, toggling extended thinking, viewing plan usage (`/usage`), and starting a [Remote Control](/en/remote-control) session (`/remote-control`). The Customize section provides access to MCP servers, hooks, memory, permissions, and plugins. Items with a terminal icon open in the integrated terminal.

97* **Context indicator**: the prompt box shows how much of Claude's context window you're using. Claude automatically compacts when needed, or you can run `/compact` manually.97* **Context indicator**: the prompt box shows how much of Claude's context window you're using. Claude automatically compacts when needed, or you can run `/compact` manually.

98* **Extended thinking**: lets Claude spend more time reasoning through complex problems. Toggle it on via the command menu (`/`). See [Extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) for details.98* **Extended thinking**: lets Claude spend more time reasoning through complex problems. Toggle it on via the command menu (`/`). Claude's reasoning appears in the conversation as collapsed blocks: click a block to read it, or press `Ctrl+O` to expand or collapse every thinking block in the session. See [Extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) for details.

99* **Multi-line input**: press `Shift+Enter` to add a new line without sending. This also works in the "Other" free-text input of question dialogs.99* **Multi-line input**: press `Shift+Enter` to add a new line without sending. This also works in the "Other" free-text input of question dialogs.

100 100

101### Reference files and folders101### Reference files and folders

115 115

116### Resume past conversations116### Resume past conversations

117 117

118Click the dropdown at the top of the Claude Code panel to access your conversation history. You can search by keyword or browse by time (Today, Yesterday, Last 7 days, etc.). Click any conversation to resume it with the full message history. New sessions receive AI-generated titles based on your first message. Hover over a session to reveal rename and remove actions: rename to give it a descriptive title, or remove to delete it from the list. For more on resuming sessions, see [Common workflows](/en/common-workflows#resume-previous-conversations).118Click the **Session history** button at the top of the Claude Code panel to access your conversation history. You can search by keyword or browse by time (Today, Yesterday, Last 7 days, etc.). Click any conversation to resume it with the full message history. New sessions receive AI-generated titles based on your first message. Hover over a session to reveal rename and remove actions: rename to give it a descriptive title, or remove to delete it from the list. For more on resuming sessions, see [Common workflows](/en/common-workflows#resume-previous-conversations).

119 119

120### Resume remote sessions from Claude.ai120### Resume remote sessions from Claude.ai

121 121

122If you use [Claude Code on the web](/en/claude-code-on-the-web), you can resume those remote sessions directly in VS Code. This requires signing in with **Claude.ai Subscription**, not Anthropic Console.122If you use [Claude Code on the web](/en/claude-code-on-the-web), you can resume those remote sessions directly in VS Code. This requires signing in with **Claude.ai Subscription**, not Anthropic Console.

123 123

124<Steps>124<Steps>

125 <Step title="Open Past Conversations">125 <Step title="Open session history">

126 Click the **Past Conversations** dropdown at the top of the Claude Code panel.126 Click the **Session history** button at the top of the Claude Code panel.

127 </Step>127 </Step>

128 128

129 <Step title="Select the Remote tab">129 <Step title="Select the Remote tab">

web-quickstart.md +18 −1

Details

71 * **Name**: a display label. Useful when you have multiple environments for different projects or access levels.71 * **Name**: a display label. Useful when you have multiple environments for different projects or access levels.

72 * **Network access**: controls what the session can reach on the internet. The default, `Trusted`, allows connections to [common package registries](/en/claude-code-on-the-web#default-allowed-domains) like npm, PyPI, and RubyGems while blocking general internet access.72 * **Network access**: controls what the session can reach on the internet. The default, `Trusted`, allows connections to [common package registries](/en/claude-code-on-the-web#default-allowed-domains) like npm, PyPI, and RubyGems while blocking general internet access.

73 * **Environment variables**: optional variables available in every session, in `.env` format. Don't wrap values in quotes, since quotes are stored as part of the value. These are visible to anyone who can edit this environment.73 * **Environment variables**: optional variables available in every session, in `.env` format. Don't wrap values in quotes, since quotes are stored as part of the value. These are visible to anyone who can edit this environment.

74 * **Setup script**: an optional Bash script that runs before Claude Code launches when a new session is created. Use it to install system tools the cloud VM doesn't include, like `apt install -y gh`, or to start services your project needs. See [Setup scripts](/en/claude-code-on-the-web#setup-scripts) for examples and debugging tips.74 * **Setup script**: an optional Bash script that runs before Claude Code launches. Use it to install system tools the cloud VM doesn't include, like `apt install -y gh`. The result is [cached](/en/claude-code-on-the-web#environment-caching), so the script doesn't re-run on every session. See [Setup scripts](/en/claude-code-on-the-web#setup-scripts) for examples and debugging tips.

75 75

76 For a first project, leave the defaults and click **Create environment**. You can [edit it later or create additional environments](/en/claude-code-on-the-web#configure-your-environment) for different projects.76 For a first project, leave the defaults and click **Create environment**. You can [edit it later or create additional environments](/en/claude-code-on-the-web#configure-your-environment) for different projects.

77 </Step>77 </Step>

133 </Step>133 </Step>

134</Steps>134</Steps>

135 135

136## Pre-fill sessions

137

138You can prefill the prompt, repositories, and environment for a new session by adding query parameters to the [claude.ai/code](https://claude.ai/code) URL. Use this to build integrations such as a button in your issue tracker that opens Claude Code with the issue description as the prompt.

139

140| Parameter | Description |

141| :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |

142| `prompt` | Prompt text to prefill in the input box. The alias `q` is also accepted. |

143| `prompt_url` | URL to fetch the prompt text from, for prompts too long to embed in a query string. The URL must allow cross-origin requests. Ignored when `prompt` is also set. |

144| `repositories` | Comma-separated list of `owner/repo` slugs to preselect. The alias `repo` is also accepted. |

145| `environment` | Name or ID of the [environment](#connect-github-and-create-an-environment) to preselect. |

146

147URL-encode each value. The example below opens the form with a prompt and a repository already selected:

148

149```text theme={null}

150https://claude.ai/code?prompt=Fix%20the%20login%20bug&repositories=acme/webapp

151```

152

136## Review and iterate153## Review and iterate

137 154

138When Claude finishes, review the changes, leave feedback on specific lines, and keep going until the diff looks right.155When Claude finishes, review the changes, leave feedback on specific lines, and keep going until the diff looks right.

whats-new/2026-w13.md +7 −7

Details

7> Auto mode for hands-off permissions, computer use built in, PR auto-fix in the cloud, transcript search, and a PowerShell tool for Windows.7> Auto mode for hands-off permissions, computer use built in, PR auto-fix in the cloud, transcript search, and a PowerShell tool for Windows.

8 8

9<div className="digest-meta">9<div className="digest-meta">

~~10 <span>Releases <a href="/en/changelog#2-1-83">v2.1.83 → v2.1.85</a></span>~~10 <span>Releases <a href="/docs/en/changelog#2-1-83">v2.1.83 → v2.1.85</a></span>

11 <span>6 features · March 23–27</span>11 <span>6 features · March 23–27</span>

12</div>12</div>

13 13

33 }33 }

34 ```34 ```

35 35

~~36 <a className="digest-feature-link" href="/en/permission-modes">Permission modes guide</a>~~36 <a className="digest-feature-link" href="/docs/en/permission-modes">Permission modes guide</a>

37</div>37</div>

38 38

39<div className="digest-feature">39<div className="digest-feature">

54 > Open the iOS simulator, tap through the onboarding flow, and screenshot each step54 > Open the iOS simulator, tap through the onboarding flow, and screenshot each step

55 ```55 ```

56 56

~~57 <a className="digest-feature-link" href="/en/desktop#let-claude-use-your-computer">Computer use guide</a>~~57 <a className="digest-feature-link" href="/docs/en/desktop#let-claude-use-your-computer">Computer use guide</a>

58</div>58</div>

59 59

60<div className="digest-feature">60<div className="digest-feature">

71 71

72 <p className="digest-feature-try">After creating a PR on Claude Code web, toggle Auto fix in the CI panel.</p>72 <p className="digest-feature-try">After creating a PR on Claude Code web, toggle Auto fix in the CI panel.</p>

73 73

~~74 <a className="digest-feature-link" href="/en/claude-code-on-the-web#auto-fix-pull-requests">Auto-fix pull requests</a>~~74 <a className="digest-feature-link" href="/docs/en/claude-code-on-the-web#auto-fix-pull-requests">Auto-fix pull requests</a>

75</div>75</div>

76 76

77<div className="digest-feature">77<div className="digest-feature">

91 N # previous match91 N # previous match

92 ```92 ```

93 93

~~94 <a className="digest-feature-link" href="/en/fullscreen#search-and-review-the-conversation">Fullscreen guide</a>~~94 <a className="digest-feature-link" href="/docs/en/fullscreen#search-and-review-the-conversation">Fullscreen guide</a>

95</div>95</div>

96 96

97<div className="digest-feature">97<div className="digest-feature">

113 }113 }

114 ```114 ```

115 115

116 <a className="digest-feature-link" href="/en/tools-reference#powershell-tool">PowerShell tool docs</a>116 <a className="digest-feature-link" href="/docs/en/tools-reference#powershell-tool">PowerShell tool docs</a>

117</div>117</div>

118 118

119<div className="digest-feature">119<div className="digest-feature">

140 }140 }

141 ```141 ```

142 142

143 <a className="digest-feature-link" href="/en/hooks">Hooks reference</a>143 <a className="digest-feature-link" href="/docs/en/hooks">Hooks reference</a>

144</div>144</div>

145 145

146<div className="digest-wins">146<div className="digest-wins">

whats-new/2026-w14.md +6 −6

Details

7> Computer use in the CLI, interactive in-product lessons, flicker-free rendering, per-tool MCP result-size overrides, and plugin executables on PATH.7> Computer use in the CLI, interactive in-product lessons, flicker-free rendering, per-tool MCP result-size overrides, and plugin executables on PATH.

8 8

9<div className="digest-meta">9<div className="digest-meta">

~~10 <span>Releases <a href="/en/changelog#2-1-86">v2.1.86 → v2.1.91</a></span>~~10 <span>Releases <a href="/docs/en/changelog#2-1-86">v2.1.86 → v2.1.91</a></span>

11 <span>5 features · March 30 – April 3</span>11 <span>5 features · March 30 – April 3</span>

12</div>12</div>

13 13

29 > Open the iOS simulator, tap through onboarding, and screenshot each step29 > Open the iOS simulator, tap through onboarding, and screenshot each step

30 ```30 ```

31 31

~~32 <a className="digest-feature-link" href="/en/computer-use">Computer use guide</a>~~32 <a className="digest-feature-link" href="/docs/en/computer-use">Computer use guide</a>

33</div>33</div>

34 34

35<div className="digest-feature">35<div className="digest-feature">

50 > /powerup50 > /powerup

51 ```51 ```

52 52

~~53 <a className="digest-feature-link" href="/en/commands">Commands reference</a>~~53 <a className="digest-feature-link" href="/docs/en/commands">Commands reference</a>

54</div>54</div>

55 55

56<div className="digest-feature">56<div className="digest-feature">

72 claude72 claude

73 ```73 ```

74 74

~~75 <a className="digest-feature-link" href="/en/fullscreen">Fullscreen rendering</a>~~75 <a className="digest-feature-link" href="/docs/en/fullscreen">Fullscreen rendering</a>

76</div>76</div>

77 77

78<div className="digest-feature">78<div className="digest-feature">

95 }95 }

96 ```96 ```

97 97

~~98 <a className="digest-feature-link" href="/en/mcp#raise-the-limit-for-a-specific-tool">MCP reference</a>~~98 <a className="digest-feature-link" href="/docs/en/mcp#raise-the-limit-for-a-specific-tool">MCP reference</a>

99</div>99</div>

100 100

101<div className="digest-feature">101<div className="digest-feature">

116 └── my-tool116 └── my-tool

117 ```117 ```

118 118

119 <a className="digest-feature-link" href="/en/plugins-reference#file-locations-reference">Plugins reference</a>119 <a className="digest-feature-link" href="/docs/en/plugins-reference#file-locations-reference">Plugins reference</a>

120</div>120</div>

121 121

122<div className="digest-wins">122<div className="digest-wins">

whats-new/2026-w15.md +6 −6

Details

7> Ultraplan cloud planning, the Monitor tool with self-pacing /loop, /team-onboarding for packaging your setup, and /autofix-pr from your terminal.7> Ultraplan cloud planning, the Monitor tool with self-pacing /loop, /team-onboarding for packaging your setup, and /autofix-pr from your terminal.

8 8

9<div className="digest-meta">9<div className="digest-meta">

~~10 <span>Releases <a href="/en/changelog#2-1-92">v2.1.92 → v2.1.101</a></span>~~10 <span>Releases <a href="/docs/en/changelog#2-1-92">v2.1.92 → v2.1.101</a></span>

11 <span>4 features · April 6–10</span>11 <span>4 features · April 6–10</span>

12</div>12</div>

13 13

29 > /ultraplan migrate the auth service from sessions to JWTs29 > /ultraplan migrate the auth service from sessions to JWTs

30 ```30 ```

31 31

~~32 <a className="digest-feature-link" href="/en/ultraplan">Ultraplan guide</a>~~32 <a className="digest-feature-link" href="/docs/en/ultraplan">Ultraplan guide</a>

33</div>33</div>

34 34

35<div className="digest-feature">35<div className="digest-feature">

56 > /loop check CI on my PR56 > /loop check CI on my PR

57 ```57 ```

58 58

~~59 <a className="digest-feature-link" href="/en/tools-reference#monitor-tool">Monitor tool reference</a>~~59 <a className="digest-feature-link" href="/docs/en/tools-reference#monitor-tool">Monitor tool reference</a>

60</div>60</div>

61 61

62<div className="digest-feature">62<div className="digest-feature">

77 > /autofix-pr77 > /autofix-pr

78 ```78 ```

79 79

~~80 <a className="digest-feature-link" href="/en/claude-code-on-the-web#auto-fix-pull-requests">Auto-fix pull requests</a>~~80 <a className="digest-feature-link" href="/docs/en/claude-code-on-the-web#auto-fix-pull-requests">Auto-fix pull requests</a>

81</div>81</div>

82 82

83<div className="digest-feature">83<div className="digest-feature">

94 > /team-onboarding94 > /team-onboarding

95 ```95 ```

96 96

~~97 <a className="digest-feature-link" href="/en/commands">Commands reference</a>~~97 <a className="digest-feature-link" href="/docs/en/commands">Commands reference</a>

98</div>98</div>

99 99

100<div className="digest-wins">100<div className="digest-wins">

102 102

103 <div className="digest-wins-grid">103 <div className="digest-wins-grid">

104 <div>Focus view: press <code>Ctrl+O</code> in flicker-free mode to collapse the view to your last prompt, a one-line tool summary with diffstats, and Claude's final response</div>104 <div>Focus view: press <code>Ctrl+O</code> in flicker-free mode to collapse the view to your last prompt, a one-line tool summary with diffstats, and Claude's final response</div>

105 <div>Guided <a href="/en/amazon-bedrock">Bedrock</a> and <a href="/en/google-vertex-ai">Vertex AI</a> setup wizards on the login screen: pick "3rd-party platform" for step-by-step auth, region, credential check, and model pinning</div>105 <div>Guided <a href="/docs/en/amazon-bedrock">Bedrock</a> and <a href="/docs/en/google-vertex-ai">Vertex AI</a> setup wizards on the login screen: pick "3rd-party platform" for step-by-step auth, region, credential check, and model pinning</div>

106 <div><code>/agents</code> gets a tabbed layout: a Running tab shows live subagents with a <code>● N running</code> count, plus Run agent and View running instance actions in the Library tab</div>106 <div><code>/agents</code> gets a tabbed layout: a Running tab shows live subagents with a <code>● N running</code> count, plus Run agent and View running instance actions in the Library tab</div>

107 <div>Default effort level is now <code>high</code> for API-key, Bedrock, Vertex, Foundry, Team, and Enterprise users (control with <code>/effort</code>)</div>107 <div>Default effort level is now <code>high</code> for API-key, Bedrock, Vertex, Foundry, Team, and Enterprise users (control with <code>/effort</code>)</div>

108 <div><code>/cost</code> shows a per-model and cache-hit breakdown for subscription users</div>108 <div><code>/cost</code> shows a per-model and cache-hit breakdown for subscription users</div>

zero-data-retention.md +1 −1

Details

61 61

62## Request ZDR62## Request ZDR

63 63

64To request ZDR for Claude Code on Claude for Enterprise, contact your Anthropic account team. Your account team will submit the request internally, and Anthropic will review and enable ZDR on your organization after confirming eligibility. All enablement actions are audit-logged.64To request ZDR for Claude Code on Claude for Enterprise, [contact sales](https://www.anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=zero_data_retention_request) or your Anthropic account team. Your account team will submit the request internally, and Anthropic will review and enable ZDR on your organization after confirming eligibility. All enablement actions are audit-logged.

65 65

66If you are currently using ZDR for Claude Code via pay-as-you-go API keys, you can transition to Claude for Enterprise to gain access to administrative features while maintaining ZDR for Claude Code. Contact your account team to coordinate the migration.66If you are currently using ZDR for Claude Code via pay-as-you-go API keys, you can transition to Claude for Enterprise to gain access to administrative features while maintaining ZDR for Claude Code. Contact your account team to coordinate the migration.

Anthropic - Claude Code Docs Changes 2026-04-15 04:00 UTC → 2026-04-22 04:00 UTC