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 +3 −3

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

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.

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.149Spans 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 150

151<Note>151<Note>

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

186 186

187## Control sensitive data in exports187## Control sensitive data in exports

188 188

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:189Telemetry 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. Three opt-in variables add content to the exported data:

190 190

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

192| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |192| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |

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 +39 −19

Details

788 plugins: list[SdkPluginConfig] = field(default_factory=list)788 plugins: list[SdkPluginConfig] = field(default_factory=list)

789 max_thinking_tokens: int | None = None # Deprecated: use thinking instead789 max_thinking_tokens: int | None = None # Deprecated: use thinking instead

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

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

792 enable_file_checkpointing: bool = False792 enable_file_checkpointing: bool = False

793```793```

794 794

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

797| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Tools configuration. Use `{"type": "preset", "preset": "claude_code"}` for Claude Code's default tools |797| `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) |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| `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 |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 |

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 |830| `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) |

834 834

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

836 836

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

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

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

861 exclude_dynamic_sections: NotRequired[bool]

861```862```

862 863

864| :------- | :------- | :------------------------------------------------------------ |865| :------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

865| `type` | Yes | Must be `"preset"` to use a preset system prompt |866| `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 |867| `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 |868| `append` | No | Additional instructions to append to the preset system prompt |

869| `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 870

869### `SettingSource`871### `SettingSource`

870 872

882 884

883#### Default behavior885#### Default behavior

884 886

885When `setting_sources` is **omitted** or **`None`**, the SDK does **not** load any filesystem settings. This provides isolation for SDK applications.887When `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 888

887#### Why use setting\_sources889#### Why use setting\_sources

888 890

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

890 892

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

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

893from claude_agent_sdk import query, ClaudeAgentOptions895from claude_agent_sdk import query, ClaudeAgentOptions

894 896

895async for message in query(897async for message in query(

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

897 options=ClaudeAgentOptions(899 options=ClaudeAgentOptions(

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

901 ),

902):

903 print(message)

904```

905

906<Note>

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

908</Note>

909

910**Load all filesystem settings explicitly:**

911

912```python theme={null}

913from claude_agent_sdk import query, ClaudeAgentOptions

914

915async for message in query(

916 prompt="Analyze this code",

917 options=ClaudeAgentOptions(

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

899 ),919 ),

900):920):

901 print(message)921 print(message)

931**SDK-only applications:**951**SDK-only applications:**

932 952

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

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

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

936async for message in query(956async for message in query(

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

938 options=ClaudeAgentOptions(958 options=ClaudeAgentOptions(

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

940 agents={...},960 agents={...},

941 mcp_servers={...},961 mcp_servers={...},

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

956 "type": "preset",976 "type": "preset",

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

958 },978 },

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

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

961 ),981 ),

962):982):

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

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

973 993

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

975 995

976### `AgentDefinition`996### `AgentDefinition`

977 997

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

1198 1218

1199<Warning>1219<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.1220 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>1221</Warning>

1202 1222

1203### `McpSdkServerConfig`1223### `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:1466The `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 1467

1448| Key | Type | Description |1468| Key | Type | Description |

1449| -------------------------- | ------- | ------------------------------------------ |1469| -------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |

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

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

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

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

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

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

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

1458 1478

2226{2246{

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

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

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

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

2231}2251}

2232```2252```

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/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/typescript.md +111 −18

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| `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 |366| `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 |367| `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 |369| `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 |420| `close()` | Close the query and terminate the underlying process. Forcefully ends the query and cleans up all resources |

379 421

422### `WarmQuery`

423

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

425

426```typescript theme={null}

427interface WarmQuery extends AsyncDisposable {

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

429 close(): void;

430}

431```

432

433#### Methods

434

435| Method | Description |

436| :-------------- | :------------------------------------------------------------------------------------------------------------------------ |

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

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

439

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

441

380### `SDKControlInitializeResponse`442### `SDKControlInitializeResponse`

381 443

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

449 511

450#### Default behavior512#### Default behavior

451 513

452When `settingSources` is **omitted** or **undefined**, the SDK does **not** load any filesystem settings. This provides isolation for SDK applications.514When `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 515

454#### Why use settingSources516#### Why use settingSources

455 517

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

519

520```typescript theme={null}

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

522const result = query({

523 prompt: "Analyze this code",

524 options: { settingSources: [] }

525});

526```

527

528**Load all filesystem settings explicitly:**

457 529

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

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

460const result = query({531const result = query({

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

462 options: {533 options: {

493**SDK-only applications:**564**SDK-only applications:**

494 565

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

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

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

498const result = query({569const result = query({

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

500 options: {571 options: {

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

502 agents: {573 agents: {

503 /* ... */574 /* ... */

504 },575 },

519 options: {590 options: {

520 systemPrompt: {591 systemPrompt: {

521 type: "preset",592 type: "preset",

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

523 },594 },

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

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

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

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

537 608

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

539 610

540### `PermissionMode`611### `PermissionMode`

541 612

723 | SDKHookStartedMessage794 | SDKHookStartedMessage

724 | SDKHookProgressMessage795 | SDKHookProgressMessage

725 | SDKHookResponseMessage796 | SDKHookResponseMessage

797 | SDKPluginInstallMessage

726 | SDKToolProgressMessage798 | SDKToolProgressMessage

727 | SDKAuthStatusMessage799 | SDKAuthStatusMessage

728 | SDKTaskNotificationMessage800 | SDKTaskNotificationMessage

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

766 parent_tool_use_id: string | null;838 parent_tool_use_id: string | null;

767 isSynthetic?: boolean;839 isSynthetic?: boolean;

840 shouldQuery?: boolean;

768 tool_use_result?: unknown;841 tool_use_result?: unknown;

769};842};

770```843```

771 844

845Set `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.

846

772### `SDKUserMessageReplay`847### `SDKUserMessageReplay`

773 848

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

891};966};

892```967```

893 968

969### `SDKPluginInstallMessage`

970

971Plugin 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`.

972

973```typescript theme={null}

974type SDKPluginInstallMessage = {

975 type: "system";

976 subtype: "plugin_install";

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

978 name?: string;

979 error?: string;

980 uuid: UUID;

981 session_id: string;

982};

983```

984

894### `SDKPermissionDenial`985### `SDKPermissionDenial`

895 986

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

2161```2252```

2162 2253

2163<Warning>2254<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.2255 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>2256</Warning>

2166 2257

2167### `SlashCommand`2258### `SlashCommand`

2186 displayName: string;2277 displayName: string;

2187 description: string;2278 description: string;

2188 supportsEffort?: boolean;2279 supportsEffort?: boolean;

2190 supportsAdaptiveThinking?: boolean;2281 supportsAdaptiveThinking?: boolean;

2191 supportsFastMode?: boolean;2282 supportsFastMode?: boolean;

2192};2283};

2268 2359

2269### `ModelUsage`2360### `ModelUsage`

2270 2361

2271Per-model usage statistics returned in result messages.2362Per-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 2363

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

2274type ModelUsage = {2365type ModelUsage = {

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

2718type SandboxNetworkConfig = {2809type SandboxNetworkConfig = {

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

2811 deniedDomains?: string[];

2720 allowManagedDomainsOnly?: boolean;2812 allowManagedDomainsOnly?: boolean;

2721 allowLocalBinding?: boolean;2813 allowLocalBinding?: boolean;

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

2727```2819```

2728 2820

2730| :------------------------ | :--------- | :---------- | :---------------------------------------------------------------- |2822| :------------------------ | :--------- | :---------- | :------------------------------------------------------------------------------------------ |

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

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

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 +17 −11

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

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-btw) 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, 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 +30 −20

Details

506 506

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

508 508

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`.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`. During extended thinking, progress hints appear below the indicator to show that Claude is actively working.

510 510

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.511Additionally, [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 512

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

514 514

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

522 522

524| ------------------------ | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |524| ------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

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) |525| **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 |526| **`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 |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 |

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

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` |529| **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 530

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

532 532

534 534

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

536 536

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.537On [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 538

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.539With 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 540

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).541On 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 542

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

556 556

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

558 558

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

560

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

562

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

564

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

566

567Sessions 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 568

561### Name your sessions569### Name your sessions

562 570

576 /rename auth-refactor584 /rename auth-refactor

577 ```585 ```

578 586

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

580 </Step>588 </Step>

581 589

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

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

602 610

603| Shortcut | Action |611| Shortcut | Action |

604| :-------- | :------------------------------------------------ |612| :------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------- |

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

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

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

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

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

611| `A` | Toggle between current directory and all projects |619| `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 |620| `Ctrl+W` | Show sessions from all worktrees of the current repository. Press again to restore the current worktree. Only shown in multi-worktree repositories |

621| `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 |622| `Esc` | Exit the picker or search mode |

614 623

615**Session organization:**624**Session organization:**

616 625

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

618 627

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

620* Time elapsed since last activity629* Time elapsed since last activity

621* Message count630* Message count

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

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

623 633

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

625 635

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

632 * Use `--resume` (without a name) when you need to browse and select642 * 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 mode643 * 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 it644 * 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 original645 * The resumed conversation starts with the same model and configuration as the original

636 646

637 How it works:647 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). |945| [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. |948| [`/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 949

940<Tip>950<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."951 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

desktop.md +19 −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

654 664

655## Troubleshooting665## Troubleshooting

656 666

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

668

657### Check your version669### Check your version

658 670

659To see which version of the desktop app you're running:671To see which version of the desktop app you're running:

707 719

708* **PATH not updated after install**: open a new terminal window. PATH updates only apply to new terminal sessions.720* **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.721* **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 722

716### "Branch doesn't exist yet" when opening in CLI723### "Branch doesn't exist yet" when opening in CLI

717 724

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 +17 −8

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

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) |141| `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 |142| `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 |143| `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_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) |148| `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'` |150| `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 |151| `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` |152| `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 |153| `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 |154| `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` |155| `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) |173| `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 |175| `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 |176| `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 |

177| `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) |178| `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 |179| `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` |180| `FORCE_AUTOUPDATE_PLUGINS` | Set to `1` to force plugin auto-updates even when the main auto-updater is disabled via `DISABLE_AUTOUPDATER` |

181| `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 |184| `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) |185| `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 |186| `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` |187| `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` |188| `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 |189| `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) |190| `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) |

196| `OTEL_LOG_RAW_API_BODIES` | Set to `1` to emit the full Anthropic Messages API request and response JSON as OpenTelemetry log events (`api_request_body`, `api_response_body`). Disabled by default; bodies include the entire conversation history. See [Monitoring](/en/monitoring-usage) |

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) |197| `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) |198| `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) |

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) |199| `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) |

216| `VERTEX_REGION_CLAUDE_4_7_OPUS` | {/* min-version: 2.1.111 */}Override region for Claude Opus 4.7 when using Vertex AI |

209 218

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.219Standard 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 +20 −10

Details

55 55

56### How a hook resolves56### How a hook resolves

57 57

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: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 Bash subcommands matching `rm *`, so `block-rm.sh` only spawns when both filters match:

59 59

60```json theme={null}60```json theme={null}

61{61{

116 </Step>116 </Step>

117 117

118 <Step title="If condition checks">118 <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.119 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>120 </Step>

121 121

122 <Step title="Hook handler runs">122 <Step title="Hook handler runs">

227 227

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

229 229

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.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 when any subcommand of the Bash input matches `git *` and `"Edit(*.ts)"` runs only for TypeScript files.

231 231

232#### Match MCP tools232#### Match MCP tools

233 233

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

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

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

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).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. Agent hooks are experimental and may change. See [Agent-based hooks](#agent-based-hooks).

284 284

285#### Common fields285#### Common fields

286 286

287These fields apply to all hook types:287These fields apply to all hook types:

288 288

290| :-------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |290| :-------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

291| `type` | yes | `"command"`, `"http"`, `"prompt"`, or `"agent"` |291| `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) |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, 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 |293| `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 |294| `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) |295| `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 |

296

297The `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 298

297#### Command hook fields299#### Command hook fields

298 300

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:1093`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 1094

1093| Field | Description |1095| Field | Description |

1094| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1096| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

1095| `behavior` | `"allow"` grants the permission, `"deny"` denies it |1097| `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 |1098| `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 |1099| `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 1129

1130<Note>

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

1132</Note>

1133

1128The `destination` field on every entry determines whether the change stays in memory or persists to a settings file.1134The `destination` field on every entry determines whether the change stays in memory or persists to a settings file.

1129 1135

2182 2188

2183## Agent-based hooks2189## Agent-based hooks

2184 2190

2191<Warning>

2192 Agent hooks are experimental. Behavior and configuration may change in future releases. For production workflows, prefer [command hooks](#command-hook-fields).

2193</Warning>

2194

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.2195Agent-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 2196

2187### How agent hooks work2197### How agent hooks work

hooks-guide.md +27 −7

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}

444 460

445* `"type": "http"`: POST event data to a URL. See [HTTP hooks](#http-hooks).461* `"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).462* `"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).463* `"type": "agent"`: multi-turn verification with tool access. Agent hooks are experimental and may change. See [Agent-based hooks](#agent-based-hooks).

448 464

449### Read input and return output465### Read input and return output

450 466

645 The `if` field requires Claude Code v2.1.85 or later. Earlier versions ignore it and run the hook on every matched call.661 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>662</Note>

647 663

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.664The `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 665

650For example, to run a hook only when Claude uses `git` commands rather than all Bash commands:666For example, to run a hook only when Claude uses `git` commands rather than all Bash commands:

651 667

668}684}

669```685```

670 686

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.687The 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 688

673`if` only works on tool events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, and `PermissionDenied`. Adding it to any other event prevents the hook from running.689`if` only works on tool events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, and `PermissionRequest`. Adding it to any other event prevents the hook from running.

674 690

675### Configure hook location691### Configure hook location

676 692

721 737

722## Agent-based hooks738## Agent-based hooks

723 739

740<Warning>

741 Agent hooks are experimental. Behavior and configuration may change in future releases. For production workflows, prefer [command hooks](/en/hooks#command-hook-fields).

742</Warning>

743

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.744When 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 745

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.746Agent 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 +30 −16

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)

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. To override the `/config` toggle, set [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](/en/env-vars) to `0` or `1`. 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 +30 −2

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

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 +44 −1

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 and are truncated at 60 KB. Enabling this implies consent to everything `OTEL_LOG_USER_PROMPTS`, `OTEL_LOG_TOOL_DETAILS`, and `OTEL_LOG_TOOL_CONTENT` would reveal | `1` to enable |

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

123### Dynamic headers126### Dynamic headers

124 127

125For enterprise environments that require dynamic authentication, you can configure a script to generate headers dynamically:128For enterprise environments that require dynamic authentication, you can configure a script to generate headers dynamically:

430* `output_tokens`: Number of output tokens433* `output_tokens`: Number of output tokens

431* `cache_read_tokens`: Number of tokens read from cache434* `cache_read_tokens`: Number of tokens read from cache

432* `cache_creation_tokens`: Number of tokens used for cache creation435* `cache_creation_tokens`: Number of tokens used for cache creation

436* `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 active437* `speed`: `"fast"` or `"normal"`, indicating whether fast mode was active

434 438

435#### API error event439#### API error event

449* `status_code`: HTTP status code as a string, or `"undefined"` for non-HTTP errors453* `status_code`: HTTP status code as a string, or `"undefined"` for non-HTTP errors

450* `duration_ms`: Request duration in milliseconds454* `duration_ms`: Request duration in milliseconds

451* `attempt`: Total number of attempts made, including the initial request (`1` means no retries occurred)455* `attempt`: Total number of attempts made, including the initial request (`1` means no retries occurred)

456* `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 active457* `speed`: `"fast"` or `"normal"`, indicating whether fast mode was active

453 458

459#### API request body event

460

461Logged for each API request attempt when `OTEL_LOG_RAW_API_BODIES=1`. One event is emitted per attempt, so retries with adjusted parameters each produce their own event.

462

463**Event Name**: `claude_code.api_request_body`

464

465**Attributes**:

466

467* All [standard attributes](#standard-attributes)

468* `event.name`: `"api_request_body"`

469* `event.timestamp`: ISO 8601 timestamp

470* `event.sequence`: monotonically increasing counter for ordering events within a session

471* `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.

472* `body_length`: Original (pre-truncation) JSON length in characters

473* `body_truncated`: `"true"` when truncation occurred (absent otherwise)

474* `model`: Model identifier from the request parameters

475* `query_source`: Subsystem that issued the request (for example, `"compact"`)

476

477#### API response body event

478

479Logged for each successful API response when `OTEL_LOG_RAW_API_BODIES=1`.

480

481**Event Name**: `claude_code.api_response_body`

482

483**Attributes**:

484

485* All [standard attributes](#standard-attributes)

486* `event.name`: `"api_response_body"`

487* `event.timestamp`: ISO 8601 timestamp

488* `event.sequence`: monotonically increasing counter for ordering events within a session

489* `body`: JSON-serialized Messages API response (id, content blocks, usage, stop reason), truncated at 60 KB. Extended-thinking content is redacted.

490* `body_length`: Original (pre-truncation) JSON length in characters

491* `body_truncated`: `"true"` when truncation occurred (absent otherwise)

492* `model`: Model identifier

493* `query_source`: Subsystem that issued the request

494* `request_id`: Anthropic API request ID from the response's `request-id` header, such as `"req_011..."`. Present only when the API returns one.

495

454#### Tool decision event496#### Tool decision event

455 497

456Logged when a tool permission decision is made (accept/reject).498Logged when a tool permission decision is made (accept/reject).

606* User prompt content is not collected by default. Only prompt length is recorded. To include prompt content, set `OTEL_LOG_USER_PROMPTS=1`648* 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 needed649* 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 needed650* 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

651* Raw Anthropic Messages API request and response bodies are not logged by default. To include them, set `OTEL_LOG_RAW_API_BODIES=1`. When enabled, 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. These 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 652

610## Monitor Claude Code on Amazon Bedrock653## Monitor Claude Code on Amazon Bedrock

611 654

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 +20 −3

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. See [sandbox modes](/en/sandboxing#sandbox-modes) to change this behavior.

264 281

plugin-dependencies.md +104 −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.

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 allowlisted 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## Tag plugin releases for version resolution

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

58Tag each release as `{plugin-name}--v{version}`, where `{version}` matches the `version` field in that commit's `plugin.json`.

60```bash theme={null}

61git tag secrets-vault--v2.1.0

62git push origin secrets-vault--v2.1.0

63```

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

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

69<Note>

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

71</Note>

73## How constraints interact

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

77| Plugin A requires | Plugin B requires | Result |

78| :---------------- | :---------------- | :---------------------------------------------------------------------------------------------- |

79| `^2.0` | `>=2.1` | One install at the highest `2.x` tag at or above `2.1.0`. Both plugins load. |

80| `~2.1` | `~3.0` | Install of plugin B fails with `range-conflict`. Plugin A and the dependency stay as they were. |

81| `=2.1.0` | none | The dependency stays at `2.1.0`. Auto-update skips newer versions while plugin A is installed. |

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

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

87## Resolve dependency errors

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

91| Error | Meaning | How to resolve |

92| :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

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

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

97To check for these errors programmatically, run `claude plugin list --json` and read the `errors` field on each plugin.

99## See also

100

101* [Create plugins](/en/plugins): build plugins with skills, agents, and hooks

102* [Create and distribute a plugin marketplace](/en/plugin-marketplaces): host plugins for your team

103* [Plugins reference](/en/plugins-reference#plugin-manifest-schema): the full `plugin.json` schema

104* [Version management](/en/plugins-reference#version-management): semantic versioning guidance for plugin releases

plugin-marketplaces.md +1 −1

Details

497 497

498### Private repositories498### Private repositories

499 499

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`.500Claude 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 501

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

503 503

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 +81 −6

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

265 265

266Install the language server first, then install the plugin from the marketplace.266Install the language server first, then install the plugin from the marketplace.

267 267

268### Monitors

269

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

271

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

273

274<Note>

275 Plugin monitors require Claude Code v2.1.105 or later.

276</Note>

277

278**Location**: `monitors/monitors.json` in the plugin root, or inline in `plugin.json`

279

280**Format**: JSON array of monitor entries

281

282The following `monitors/monitors.json` watches a deployment status endpoint and a local error log:

283

284```json theme={null}

285[

286 {

287 "name": "deploy-status",

288 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/poll-deploy.sh ${user_config.api_endpoint}",

289 "description": "Deployment status changes"

290 },

291 {

292 "name": "error-log",

293 "command": "tail -F ./logs/error.log",

294 "description": "Application error log",

295 "when": "on-skill-invoke:debug"

296 }

297]

298```

299

300To 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"`.

301

302**Required fields:**

303

304| Field | Description |

305| :------------ | :-------------------------------------------------------------------------------------------------------------------- |

306| `name` | Identifier unique within the plugin. Prevents duplicate processes when the plugin reloads or a skill is invoked again |

307| `command` | Shell command run as a persistent background process in the session working directory |

308| `description` | Short summary of what is being watched. Shown in the task panel and in notification summaries |

309

310**Optional fields:**

311

312| Field | Description |

313| :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

314| `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 |

315

316The `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.

317

318Disabling a plugin mid-session does not stop monitors that are already running. They stop when the session ends.

319

268***320***

269 321

270## Plugin installation scopes322## Plugin installation scopes

311 "mcpServers": "./mcp-config.json",363 "mcpServers": "./mcp-config.json",

312 "outputStyles": "./styles/",364 "outputStyles": "./styles/",

313 "lspServers": "./.lsp.json",365 "lspServers": "./.lsp.json",

314 "monitors": "./monitors.json"366 "monitors": "./monitors.json",

367 "dependencies": [

368 "helper-lib",

369 { "name": "secrets-vault", "version": "~2.1.0" }

370 ]

315}371}

316```372```

317 373

342### Component path fields398### Component path fields

343 399

345| :------------- | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------- |401| :------------- | :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |

412| `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 413

357### User configuration414### User configuration

358 415

373}430}

374```431```

375 432

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.433Keys must be valid identifiers. Each value is available for substitution as `${user_config.KEY}` in MCP and LSP server configs, hook commands, monitor 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.

377 434

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.435Non-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 436

424 481

425### Environment variables482### Environment variables

426 483

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.484Claude 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 485

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.486**`${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 487

709 766

710***767***

711 768

769### plugin list

770

771List installed plugins with their version, source marketplace, and enable status.

772

773```bash theme={null}

774claude plugin list [options]

775```

776

777**Options:**

778

779| Option | Description | Default |

780| :------------ | :------------------------------------------------------------- | :------ |

781| `--json` | Output as JSON | |

782| `--available` | Include available plugins from marketplaces. Requires `--json` | |

783| `-h, --help` | Display help for command | |

784

785***

786

712## Debugging and development tools787## Debugging and development tools

713 788

714### Debugging commands789### Debugging commands

quickstart.md +1 −1

Details

10 10

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

12 12

~~13<Experiment flag="quickstart-install-configurator" treatment={<InstallConfigurator />} />~~13

14 14

15## Before you begin15## Before you begin

16 16

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 +1 −0

Details

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 +14 −6

Details

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

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"]}` |218| `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"]}` |

216| `statusLine` | Configure a custom status line to display context. See [`statusLine` documentation](/en/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |219| `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" }]` |220| `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" }]` |

221| `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` |222| `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 225

222### Global config settings226### Global config settings

227| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |231| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |

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` |232| `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` |233| `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` |

234| `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"` |235| `editorMode` | Key binding mode for the input prompt: `"normal"` or `"vim"`. Default: `"normal"`. Appears in `/config` as **Editor mode** | `"vim"` |

236| `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` |237| `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` |238| `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"` |239| `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.281Configure advanced sandboxing behavior. Sandboxing isolates bash commands from your filesystem and network. See [Sandboxing](/en/sandboxing) for details.

276 282

278| :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ |284| :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------- |

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` |286| `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` |

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"]` |292| `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. | `["."]` |293| `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` |294| `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"]` |295| `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` |296| `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.*"]` |298| `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.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` |301| `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` |302| `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` |303| `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 },330 },

324 "network": {331 "network": {

325 "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],332 "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],

333 "deniedDomains": ["uploads.github.com"],

326 "allowUnixSockets": [334 "allowUnixSockets": [

327 "/var/run/docker.sock"335 "/var/run/docker.sock"

328 ],336 ],

setup.md +25 −20

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

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 +3 −3

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

196| `user-invocable` | No | Set to `false` to hide from the `/` menu. Use for background knowledge users shouldn't invoke directly. Default: `true`. |196| `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. |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| `model` | No | Model to use when this skill is active. |198| `model` | No | Model to use when this skill is active. |

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). |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`, `xhigh`, `max`; available levels depend on the model. |

200| `context` | No | Set to `fork` to run in a forked subagent context. |200| `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. |201| `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. |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. |

464 464

465### Restrict Claude's skill access465### Restrict Claude's skill access

466 466

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

469Three ways to control which skills Claude can invoke:469Three ways to control which skills Claude can invoke:

470 470

statusline.md +3 −3

Details

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 +4 −4

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

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. If it reports a conflict such as `Found existing VSCode terminal Shift+Enter key binding`, remove that entry from the terminal's own keybindings file, for example VS Code's `keybindings.json`, and run the command again. 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 +20 −6

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

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, one-time | billed as [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

54| Max | 3 free runs, one-time | 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 and do not refresh. After you use them, 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 +4 −4

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>

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>

Anthropic - Claude Code Docs Changes 2026-04-15 04:00 UTC → 2026-04-20 21:14 UTC