Documentation — Spybara

agent-sdk/file-checkpointing.md +22 −11

Details

14 14

15## How checkpointing works15## How checkpointing works

16 16

17When you enable file checkpointing, the SDK creates backups of files before modifying them through the Write, Edit, or NotebookEdit tools. User messages in the response stream include a checkpoint UUID that you can use as a restore point.17When you enable file checkpointing, the SDK creates backups of files before modifying them through the Write, Edit, or NotebookEdit tools. Each prompt that starts a turn is a checkpoint, and its user message's UUID is the restore point.

18 18

19> [!NOTE]19> [!NOTE]

20>20>

147 147

148**2. Capture checkpoint UUID and session ID**148**2. Capture checkpoint UUID and session ID**

149 149

150With the `replay-user-messages` option set, each user message in the response stream has a UUID that serves as a checkpoint.150With the `replay-user-messages` option set, the user message for each prompt that starts a turn has a UUID that serves as a checkpoint. User messages that carry tool results have a UUID too, but it isn't a checkpoint.

151 151

152For most use cases, capture the first user message UUID (`message.uuid`); rewinding to it restores the tracked files to their original state. To store multiple checkpoints and rewind to intermediate states, see [Multiple restore points](#multiple-restore-points).152For most use cases, capture the first user message UUID (`message.uuid`); rewinding to it restores the tracked files to their original state. To store multiple checkpoints and rewind to intermediate states, see [Multiple restore points](#multiple-restore-points).

153 153

171 171

172### Checkpoint before risky operations172### Checkpoint before risky operations

173 173

174This pattern keeps only the most recent checkpoint UUID, updating it before each agent turn. If something goes wrong during processing, you can immediately rewind to the last safe state and break out of the loop.174This pattern keeps only the most recent checkpoint UUID, updating it at each prompt that starts a turn. If something goes wrong during processing, you can immediately rewind to the last safe state and break out of the loop.

175 175

176Before running this example, replace `your_revert_condition` (Python) or `yourRevertCondition` (TypeScript) with your own check, such as error detection or a validation failure; the placeholder is not defined in the example.176Before running this example, replace `your_revert_condition` (Python) or `yourRevertCondition` (TypeScript) with your own check, such as error detection or a validation failure; the placeholder is not defined in the example.

177 177

193 await client.query("Refactor the authentication module")193 await client.query("Refactor the authentication module")

194 194

195 async for message in client.receive_response():195 async for message in client.receive_response():

196 # Update checkpoint before each agent turn starts196 # Update checkpoint at each prompt you send; a tool result isn't one

197 # This overwrites the previous checkpoint. Only keep the latest197 # This overwrites the previous checkpoint. Only keep the latest

198 if isinstance(message, UserMessage) and message.uuid:198 if (

199 isinstance(message, UserMessage)

200 and message.uuid

201 and message.tool_use_result is None

202 and message.parent_tool_use_id is None

203 ):

199 safe_checkpoint = message.uuid204 safe_checkpoint = message.uuid

200 205

201 # Decide when to revert based on your own logic206 # Decide when to revert based on your own logic

225 let safeCheckpoint: string | undefined;230 let safeCheckpoint: string | undefined;

226 231

227 for await (const message of response) {232 for await (const message of response) {

228 // Update checkpoint before each agent turn starts233 // Update checkpoint at each prompt you send; a tool result isn't one

229 // This overwrites the previous checkpoint. Only keep the latest234 // This overwrites the previous checkpoint. Only keep the latest

230 if (message.type === "user" && message.uuid) {235 if (message.type === "user" && "isReplay" in message && message.isReplay && message.uuid) {

231 safeCheckpoint = message.uuid;236 safeCheckpoint = message.uuid;

232 }237 }

233 238

246 251

247### Multiple restore points252### Multiple restore points

248 253

249If Claude makes changes across multiple turns, you might want to rewind to a specific point rather than all the way back. For example, if Claude refactors a file in turn one and adds tests in turn two, you might want to keep the refactor but undo the tests.254If Claude makes changes across several prompts, you might want to rewind to a specific point rather than all the way back. For example, if your first prompt refactors a file and your second adds tests, rewind to your second prompt's checkpoint to keep the refactor and undo the tests.

250 255

251This pattern stores all checkpoint UUIDs in an array with metadata. After the session completes, you can rewind to any previous checkpoint:256This pattern stores each checkpoint UUID in an array with metadata. After the session completes, you can rewind to any previous checkpoint:

252 257

253```python Python theme={null}258```python Python theme={null}

254import asyncio259import asyncio

284 await client.query("Refactor the authentication module")289 await client.query("Refactor the authentication module")

285 290

286 async for message in client.receive_response():291 async for message in client.receive_response():

287 if isinstance(message, UserMessage) and message.uuid:292 if (

293 isinstance(message, UserMessage)

294 and message.uuid

295 and message.tool_use_result is None

296 and message.parent_tool_use_id is None

297 ):

288 checkpoints.append(298 checkpoints.append(

289 Checkpoint(299 Checkpoint(

290 id=message.uuid,300 id=message.uuid,

338 348

339 try {349 try {

340 for await (const message of response) {350 for await (const message of response) {

341 if (message.type === "user" && message.uuid) {351 if (message.type === "user" && "isReplay" in message && message.isReplay && message.uuid) {

342 checkpoints.push({352 checkpoints.push({

343 id: message.uuid,353 id: message.uuid,

344 description: `After turn ${checkpoints.length + 1}`,354 description: `After turn ${checkpoints.length + 1}`,

638 648

639* File checkpointing was not enabled on the original session (`enable_file_checkpointing` or `enableFileCheckpointing` was not set to `true`)649* File checkpointing was not enabled on the original session (`enable_file_checkpointing` or `enableFileCheckpointing` was not set to `true`)

640* The session wasn't properly completed before attempting to resume and rewind650* The session wasn't properly completed before attempting to resume and rewind

651* The UUID came from a user message that carries a tool result, which isn't a checkpoint

641 652

642**Solution**: Ensure `enable_file_checkpointing=True` (Python) or `enableFileCheckpointing: true` (TypeScript) was set on the original session, then use the pattern shown in the examples: capture the first user message UUID, complete the session fully, then resume with an empty prompt and call `rewindFiles()` once.653**Solution**: Ensure `enable_file_checkpointing=True` (Python) or `enableFileCheckpointing: true` (TypeScript) was set on the original session, then use the pattern shown in the examples: capture the first user message UUID, complete the session fully, then resume with an empty prompt and call `rewindFiles()` once.

643 654

agent-sdk/python.md +1 −1

Details

875| `allowed_tools` | `list[str]` | `[]` | Tools to auto-approve without prompting, apart from reads from [network paths](https://code.claude.com/docs/en/permissions.md#network-paths). This does not restrict Claude to only these tools. If you name one of the [task-tracking tools](https://code.claude.com/docs/en/agent-sdk/todo-tracking.md#model-availability) here, Claude Code also opts the session in. Other unlisted tools fall through to `permission_mode` and `can_use_tool`. Use `disallowed_tools` to block tools. See [Permissions](https://code.claude.com/docs/en/agent-sdk/permissions.md#allow-and-deny-rules) |875| `allowed_tools` | `list[str]` | `[]` | Tools to auto-approve without prompting, apart from reads from [network paths](https://code.claude.com/docs/en/permissions.md#network-paths). This does not restrict Claude to only these tools. If you name one of the [task-tracking tools](https://code.claude.com/docs/en/agent-sdk/todo-tracking.md#model-availability) here, Claude Code also opts the session in. Other unlisted tools fall through to `permission_mode` and `can_use_tool`. Use `disallowed_tools` to block tools. See [Permissions](https://code.claude.com/docs/en/agent-sdk/permissions.md#allow-and-deny-rules) |

876| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptCustom \| SystemPromptFile \| None` | `None` | System prompt configuration. Pass a string for a custom prompt, `{"type": "preset", "preset": "claude_code"}` for Claude Code's system prompt with optional `"append"`, `{"type": "custom", "prompt": "..."}` for a custom prompt that can also set `"snapshot"`, or `{"type": "file", "path": "..."}` to load a large prompt from disk. See [`SystemPromptPreset`](#systempromptpreset), [`SystemPromptCustom`](#systempromptcustom), and [`SystemPromptFile`](#systempromptfile) |876| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptCustom \| SystemPromptFile \| None` | `None` | System prompt configuration. Pass a string for a custom prompt, `{"type": "preset", "preset": "claude_code"}` for Claude Code's system prompt with optional `"append"`, `{"type": "custom", "prompt": "..."}` for a custom prompt that can also set `"snapshot"`, or `{"type": "file", "path": "..."}` to load a large prompt from disk. See [`SystemPromptPreset`](#systempromptpreset), [`SystemPromptCustom`](#systempromptcustom), and [`SystemPromptFile`](#systempromptfile) |

877| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP server configurations or path to config file |877| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP server configurations or path to config file |

878| `strict_mcp_config` | `bool` | `False` | When `True`, use only the servers passed in `mcp_servers` and ignore project `.mcp.json`, user settings, plugin-provided MCP servers, and [claude.ai connectors](https://code.claude.com/docs/en/mcp.md#use-mcp-servers-from-claude-ai). Maps to the CLI `--strict-mcp-config` flag |878| `strict_mcp_config` | `bool` | `False` | When `True`, use the servers passed in `mcp_servers` and ignore project `.mcp.json`, user settings, plugin-provided MCP servers, and [claude.ai connectors](https://code.claude.com/docs/en/mcp.md#use-mcp-servers-from-claude-ai). Maps to the CLI `--strict-mcp-config` flag |

agent-sdk/subagents.md +1 −1

Details

148| `disallowedTools` | `string[]` | No | Array of tool names to remove from the agent's tool set. MCP server-level patterns are also accepted: `mcp__server` or `mcp__server__*` removes every tool from that server, and `mcp__*` removes every MCP tool from any server |148| `disallowedTools` | `string[]` | No | Array of tool names to remove from the agent's tool set. MCP server-level patterns are also accepted: `mcp__server` or `mcp__server__*` removes every tool from that server, and `mcp__*` removes every MCP tool from any server |

149| `model` | `string` | No | Model override for this agent. Accepts an alias such as `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, or a full model ID. `'inherit'` uses the main model. When you omit it, Claude Code picks the model in the [subagent model order](https://code.claude.com/docs/en/sub-agents.md#choose-a-model) |149| `model` | `string` | No | Model override for this agent. Accepts an alias such as `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, or a full model ID. `'inherit'` uses the model of the agent that spawned this one. When you omit `model`, Claude Code picks the model in the [subagent model order](https://code.claude.com/docs/en/sub-agents.md#choose-a-model) |

150| `skills` | `string[]` | No | List of skill names to preload into the agent's context at startup. At most the [first 32 distinct names](https://code.claude.com/docs/en/sub-agents.md#preload-skills-into-subagents) in the list are preloaded. Unlisted skills remain invocable through the Skill tool |150| `skills` | `string[]` | No | List of skill names to preload into the agent's context at startup. At most the [first 32 distinct names](https://code.claude.com/docs/en/sub-agents.md#preload-skills-into-subagents) in the list are preloaded. Unlisted skills remain invocable through the Skill tool |

agent-sdk/typescript.md +2 −2

Details

589| `skills` | `string[] \| 'all'` | `undefined` | Skills available to the session. Pass `'all'` to enable every discovered skill, or a list of skill names. Pass exact names only. On Agent SDK v0.3.221 or later, the SDK rejects malformed and wildcard-form names with an error before starting the Claude Code process. When set, the SDK adds the Skill tool to `allowedTools` automatically. If you also pass `tools`, include `'Skill'` in that list. See [Skills](https://code.claude.com/docs/en/agent-sdk/skills.md) |589| `skills` | `string[] \| 'all'` | `undefined` | Skills available to the session. Pass `'all'` to enable every discovered skill, or a list of skill names. Pass exact names only. On Agent SDK v0.3.221 or later, the SDK rejects malformed and wildcard-form names with an error before starting the Claude Code process. When set, the SDK adds the Skill tool to `allowedTools` automatically. If you also pass `tools`, include `'Skill'` in that list. See [Skills](https://code.claude.com/docs/en/agent-sdk/skills.md) |

592| `strictMcpConfig` | `boolean` | `false` | Use only the servers passed in `mcpServers` and ignore project `.mcp.json`, user settings, plugin-provided MCP servers, and [claude.ai connectors](https://code.claude.com/docs/en/mcp.md#use-mcp-servers-from-claude-ai) |592| `strictMcpConfig` | `boolean` | `false` | Use the servers passed in `mcpServers` and ignore project `.mcp.json`, user settings, plugin-provided MCP servers, and [claude.ai connectors](https://code.claude.com/docs/en/mcp.md#use-mcp-servers-from-claude-ai) |

593| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined` (minimal prompt) | System prompt configuration. Pass a string for a custom prompt, or `{ type: 'preset', preset: 'claude_code' }` to use Claude Code's system prompt. Pass an array of strings with the exported `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` constant between the static and per-request parts to [cache the static part of a custom prompt](https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts.md#cache-the-static-part-of-a-custom-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](https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts.md#improve-prompt-caching-across-users-and-machines). Set `snapshot: false` to rebuild the prompt on every request instead of [reusing the prompt the session recorded on its first request](https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session). To set `snapshot` on a custom prompt, pass the `{ type: 'custom', prompt }` form. The `{ type: 'custom' }` form and the `snapshot` field require TypeScript Agent SDK v0.3.257 or later |593| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined` (minimal prompt) | System prompt configuration. Pass a string for a custom prompt, or `{ type: 'preset', preset: 'claude_code' }` to use Claude Code's system prompt. Pass an array of strings with the exported `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` constant between the static and per-request parts to [cache the static part of a custom prompt](https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts.md#cache-the-static-part-of-a-custom-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](https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts.md#improve-prompt-caching-across-users-and-machines). Set `snapshot: false` to rebuild the prompt on every request instead of [reusing the prompt the session recorded on its first request](https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session). To set `snapshot` on a custom prompt, pass the `{ type: 'custom', prompt }` form. The `{ type: 'custom' }` form and the `snapshot` field require TypeScript Agent SDK v0.3.257 or later |

594| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* API-side task budget in tokens. When set, the model is told its remaining token budget so it can pace tool use and wrap up before the limit |594| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* API-side task budget in tokens. When set, the model is told its remaining token budget so it can pace tool use and wrap up before the limit |

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

1285| `tools` | No | Array of allowed tool names. If omitted, inherits every [tool available to subagents](https://code.claude.com/docs/en/sub-agents.md#available-tools). To preload Skills into the agent's context, use the `skills` field rather than listing `'Skill'` here |1285| `tools` | No | Array of allowed tool names. If omitted, inherits every [tool available to subagents](https://code.claude.com/docs/en/sub-agents.md#available-tools). To preload Skills into the agent's context, use the `skills` field rather than listing `'Skill'` here |

1286| `disallowedTools` | No | Array of tool names to explicitly disallow for this agent. MCP server-level patterns are also accepted: `mcp__server` or `mcp__server__*` removes every tool from that server, and `mcp__*` removes every MCP tool from any server |1286| `disallowedTools` | No | Array of tool names to explicitly disallow for this agent. MCP server-level patterns are also accepted: `mcp__server` or `mcp__server__*` removes every tool from that server, and `mcp__*` removes every MCP tool from any server |

1287| `prompt` | Yes | The agent's system prompt |1287| `prompt` | Yes | The agent's system prompt |

1288| `model` | No | Model override for this agent. Accepts an alias such as `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, or a full model ID. `'inherit'` uses the main model. When you omit it, Claude Code picks the model in the [subagent model order](https://code.claude.com/docs/en/sub-agents.md#choose-a-model) |1288| `model` | No | Model override for this agent. Accepts an alias such as `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, or a full model ID. `'inherit'` uses the model of the agent that spawned this one. When you omit `model`, Claude Code picks the model in the [subagent model order](https://code.claude.com/docs/en/sub-agents.md#choose-a-model) |

1289| `mcpServers` | No | MCP server specifications for this agent |1289| `mcpServers` | No | MCP server specifications for this agent |

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

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

agent-teams.md +26 −9

Details

102>102>

103> `tmux` has known limitations on certain operating systems and traditionally works best on macOS. Using `tmux -CC` in iTerm2 is the suggested entrypoint into `tmux`.103> `tmux` has known limitations on certain operating systems and traditionally works best on macOS. Using `tmux -CC` in iTerm2 is the suggested entrypoint into `tmux`.

104 104

105The default is `"in-process"`. Set `"auto"` to enable split panes when you're already running inside a tmux session, or when your terminal is iTerm2 with the `it2` CLI installed, falling back to in-process otherwise. The `"tmux"` setting enables split-pane mode and auto-detects whether to use tmux or iTerm2 based on your terminal.105With agent teams [enabled](#enable-agent-teams), follow these steps to give each teammate its own pane:

106 106

107Set `"iterm2"` to use iTerm2 native split panes explicitly. This mode requires the [`it2` CLI](https://github.com/mkusaka/it2) and shows an error with the install command if `it2` is missing. The setup prompt that offers to install `it2` or switch to tmux appears under `"auto"` or `"tmux"` when your terminal is iTerm2 and tmux is available as a fallback.107**1. Install tmux or set up iTerm2**

108 108

109To override the default, set [`teammateMode`](https://code.claude.com/docs/en/settings-reference#teammatemode) in `~/.claude/settings.json`:109Split-pane mode requires either [tmux](https://github.com/tmux/tmux/wiki) or iTerm2 with the [`it2` CLI](https://github.com/mkusaka/it2). Set up the one you'll run Claude Code in:

110

111* **tmux**: install through your system's package manager. See the [tmux wiki](https://github.com/tmux/tmux/wiki/Installing) for platform-specific instructions.

112* **iTerm2**: install the [`it2` CLI](https://github.com/mkusaka/it2), then enable the Python API in **iTerm2 > Settings > General > Magic > Enable Python API**.

113

114**2. Turn on split panes**

115

116Teammates run in-process until you change the [`teammateMode`](https://code.claude.com/docs/en/settings-reference#teammatemode) setting.

117

118Set it to `"auto"` in `~/.claude/settings.json`:

110 119

111```json theme={null}120```json theme={null}

112{121{

114}123}

115```124```

116 125

126With `"auto"`, teammates open in split panes when you run Claude Code inside tmux or iTerm2, and run in-process in other terminals.

127

128**3. Start Claude Code and spawn teammates**

129

130Run `claude` inside tmux or in iTerm2, then ask Claude to spawn teammates.

131

132If a setup prompt for `it2` appears in iTerm2, select **Install it2 now** to open the panes in your iTerm2 window.

133

134If you run Claude Code outside tmux and iTerm2, or the panes don't open in your iTerm2 window, change `teammateMode` again:

135

136* **Outside tmux and iTerm2**: with tmux installed, set `teammateMode` to `"tmux"`. The panes open in a separate tmux session. To watch them, copy the command from the `View teammates` line at the Claude Code prompt and run that command in a second terminal.

137* **Panes don't open in your iTerm2 window**: set `teammateMode` to `"iterm2"` to use iTerm2's own panes. Teammates then start only when you run Claude Code in iTerm2 with `it2` set up.

138

117To set the mode for a single session, pass it as a flag:139To set the mode for a single session, pass it as a flag:

118 140

119```bash theme={null}141```bash theme={null}

122 144

123The `--teammate-mode` flag is experimental and doesn't appear in `claude --help`.145The `--teammate-mode` flag is experimental and doesn't appear in `claude --help`.

124 146

125Split-pane mode requires either [tmux](https://github.com/tmux/tmux/wiki) or iTerm2 with the [`it2` CLI](https://github.com/mkusaka/it2). To install manually:

~~126~~

127* **tmux**: install through your system's package manager. See the [tmux wiki](https://github.com/tmux/tmux/wiki/Installing) for platform-specific instructions.

128* **iTerm2**: install the [`it2` CLI](https://github.com/mkusaka/it2), then enable the Python API in **iTerm2 → Settings → General → Magic → Enable Python API**.

~~129~~

130### Specify teammates and models147### Specify teammates and models

131 148

132Claude decides the number of teammates to spawn based on your task, or you can specify exactly what you want:149Claude decides the number of teammates to spawn based on your task, or you can specify exactly what you want:

497* **No background subagents from in-process teammates**: an in-process teammate's own subagents run in the foreground, because a teammate's background work can't outlive the lead's process. Claude Code returns an error when a teammate spawns a subagent whose definition sets `background: true`. A teammate's `run_in_background: true` request also fails, either with an error or by running silently in the foreground. Subagents launched from the main conversation follow the [background default](https://code.claude.com/docs/en/sub-agents.md#run-subagents-in-foreground-or-background).514* **No background subagents from in-process teammates**: an in-process teammate's own subagents run in the foreground, because a teammate's background work can't outlive the lead's process. Claude Code returns an error when a teammate spawns a subagent whose definition sets `background: true`. A teammate's `run_in_background: true` request also fails, either with an error or by running silently in the foreground. Subagents launched from the main conversation follow the [background default](https://code.claude.com/docs/en/sub-agents.md#run-subagents-in-foreground-or-background).

498* **Lead is fixed**: the main session is the lead for its lifetime. You can't promote a teammate to lead or transfer leadership.515* **Lead is fixed**: the main session is the lead for its lifetime. You can't promote a teammate to lead or transfer leadership.

499* **No per-teammate permission modes at spawn**: teammates start with the permission mode described under [Permissions](#permissions).516* **No per-teammate permission modes at spawn**: teammates start with the permission mode described under [Permissions](#permissions).

500* **Split panes require tmux or iTerm2**: the default in-process mode works in any terminal. Split-pane mode isn't supported in VS Code's integrated terminal, Windows Terminal, or Ghostty.517* **Split panes require tmux or iTerm2**: the default in-process mode works in any terminal.

501 518

502## Next steps519## Next steps

503 520

agent-view.md +30 −39

Details

144| Shape | What it means |144| Shape | What it means |

145| :- | :- |145| :- | :- |

147| `∙` | The process has exited. You can still peek at the row, and when you reply or attach, Claude restarts it from its saved conversation |147| `∙` | The process has exited. You can still peek at the row, and when you reply or press `Enter`, Claude restarts it from its saved conversation |

148| `✢` | A [`/loop`](https://code.claude.com/docs/en/scheduled-tasks) session sleeping between iterations. The row shows its run count and a countdown |148| `✢` | A [`/loop`](https://code.claude.com/docs/en/scheduled-tasks) session sleeping between iterations. The row shows its run count and a countdown |

149 149

150The `#N` or `!N` label that can appear at the right edge of a row is a link to the session's [pull request or merge request](#pull-request-status), not part of the state icon.150The `#N` or `!N` label that can appear at the right edge of a row is a link to the session's [pull request or merge request](#pull-request-status), not part of the state icon.

316* Press `Enter` on a group header to collapse it, except while a [filter](#filter-sessions) is active, when every group stays expanded316* Press `Enter` on a group header to collapse it, except while a [filter](#filter-sessions) is active, when every group stays expanded

317* Press `Ctrl+X` to stop a session and `Ctrl+X` again within two seconds to delete it from the list, or `Esc` to dismiss the confirmation without deleting. The second press deletes the session even when the stop attempt fails, for example because the [background service isn't responding](#agent-view-says-the-background-service-did-not-respond). In that case the confirmation stays active for another two seconds, and the delete ends the session's process itself317* Press `Ctrl+X` to stop a session and `Ctrl+X` again within two seconds to delete it from the list, or `Esc` to dismiss the confirmation without deleting. The second press deletes the session even when the stop attempt fails, for example because the [background service isn't responding](#agent-view-says-the-background-service-did-not-respond). In that case the confirmation stays active for another two seconds, and the delete ends the session's process itself

318 318

319Pressing `Ctrl+X` on a group header deletes every session in that group after confirmation. Except in the kept cases covered in [What deleting a session removes](#what-deleting-a-session-removes), deleting removes the session from the list. A worktree Claude created for it is removed, kept, or left in place depending on how you delete and what the worktree holds. The conversation transcript stays on your local machine, available through `claude --resume`.319Press `Ctrl+X` on a group header to delete every session in that group after confirmation, except any that Claude Code [refuses to delete](#delete-a-session-after-claude-code-refuses). See [What deleting a session removes](#what-deleting-a-session-removes) for what happens to each session's worktree. The conversation transcript stays on your local machine, available through `claude --resume`.

320 320

321Completed sessions that don't fit on screen fold into a `… N more` row. The `Completed` group fills the vertical space left after the live groups. On a short terminal, the header compacts to a single summary line so sessions that are working or need input stay visible.321Completed sessions that don't fit on screen fold into a `… N more` row. The `Completed` group fills the vertical space left after the live groups. On a short terminal, the header compacts to a single summary line so sessions that are working or need input stay visible.

322 322

622 622

623#### What deleting a session removes623#### What deleting a session removes

624 624

625Delete a session with `Ctrl+X` twice in [agent view](#organize-the-list) or with [`claude rm`](#manage-sessions-from-the-shell). Except in the kept cases below, the session leaves the list. Its transcript stays on your machine through `claude --resume`, and the removal survives supervisor restarts.625Delete a session with `Ctrl+X` twice in [agent view](#organize-the-list) or with [`claude rm`](#manage-sessions-from-the-shell). The session disappears from the list, unless Claude Code [refuses to delete it](#delete-a-session-after-claude-code-refuses). Its transcript stays on your machine, available through `claude --resume`.

626 626

627What happens to a worktree Claude created for the session:627What happens to a worktree Claude created for the session:

628 628

629* Agent view removes it, including uncommitted changes, so commit what you want to keep first.629* Agent view removes it, including uncommitted changes, so commit what you want to keep first.

630* `claude rm` keeps it, along with the session row, when it has uncommitted changes.630* `claude rm` keeps it, along with the session row, when it has uncommitted changes.

631* Neither agent view nor `claude rm` removes a worktree that another running session is using or has locked, and deleting again doesn't change that. Claude Code keeps the worktree and the session, and names the kept directory and the reason; in agent view, the session's row shows `not removed`. Close the other session, then delete again.

632* When you delete a session whose worktree has commits that Claude Code can't confirm are saved elsewhere, Claude Code keeps the worktree and the session, and the message names the worktree's branch and how many commits are unpushed. The message also offers the two ways forward: push the commits, or delete again to discard them.

633 631

634 Commits on a remote don't block the delete. Neither do commits on the local copy of your `origin` remote's default branch, as long as that branch is checked out in your main checkout, the repository directory itself rather than a worktree.632One reason Claude Code refuses to delete a session is [unpushed commits in its worktree](https://code.claude.com/docs/en/errors.md#worktree-has-commits-that-are-not-pushed-anywhere). To keep those commits, push them before you delete the session.

635 633

636 After that refusal, you choose:634Some worktrees stay on disk, whether you use agent view or `claude rm`:

637 635

638 * To keep the commits, push them, or merge them into that default branch, then delete the session again.636* If you created a worktree yourself and started the session from inside it, the worktree stays on disk for you to keep or remove.

639 * To discard them, delete the session again without pushing: press `Ctrl+X` twice on its row in agent view, or run the `claude rm <id> --discard-unpushed` command the refusal printed. This removes the session and the worktree along with its branch, discarding the unpushed commits and any uncommitted changes.637* If a worktree directory Claude created inside your repository no longer has its `.git` file, the directory stays on disk for you to remove. The worktree's branch stays in the repository, so you keep the commits on that branch.

640 638

641 When you delete again, Claude Code discards only what the refusal showed: if the worktree has gained a commit since, Claude Code keeps it again and shows the updated state.639##### Delete a session after Claude Code refuses

642 640

643 When another finished session's records also name the worktree, it stays when you delete again; push the commits, then delete again.641When Claude Code refuses to delete a session because of its worktree, follow the message it shows. If the message names unpushed commits, see [Worktree has commits that are not pushed anywhere](https://code.claude.com/docs/en/errors.md#worktree-has-commits-that-are-not-pushed-anywhere).

644* A worktree git no longer recognizes, for example after `git worktree prune`, doesn't block the delete. Claude Code deletes the session and leaves the directory on disk.

645* When git or your [`WorktreeRemove` hook](https://code.claude.com/docs/en/hooks#worktreeremove) fails to remove the worktree, Claude Code keeps the worktree and the session, and the message names the cause. For a hook, the message says how it ended, such as `exited 1`, and quotes the start of its stderr. The message also tells you which of these to do next:

646 642

647 * Delete the session again to remove the directory anyway, by pressing `Ctrl+X` twice on its row in agent view or running the `claude rm <id> --force-remove-worktree <worktree-id>` command that the `claude rm` refusal printed. The worktree's branch stays in the repository.643##### Resolve a `Worktree not removed` message

648 644

649 Claude Code offers this only when it can confirm all of the following:645A `Worktree not removed` message means Claude Code or your [`WorktreeRemove` hook](https://code.claude.com/docs/en/hooks#worktreeremove) didn't finish removing the session's worktree. Push any commits and copy out any files you want to keep, then follow the message.

650 646

651 * The directory is one of the repository's linked worktrees under `.claude/worktrees/`647##### Resolve a `files that weren't checked against a repository` message

652 * Neither the worktree nor a checked-out submodule has uncommitted changes to tracked files

653 * No other session's record names it

654 648

655 When Claude Code can't verify a submodule checkout's state, such as one replaced by a separate git repository, it doesn't offer this either.649This message from `claude rm` means files remain in a worktree directory that isn't inside any git repository or that a [`WorktreeCreate` hook](https://code.claude.com/docs/en/hooks#worktreecreate) manages. Copy out any files you want to keep, then take the step for your case:

656 * Fix what stands in the way, such as committing or stashing the uncommitted changes, moving a separate git repository out of the worktree, closing whatever is using the directory, or fixing the hook, then delete the session again.

657 * Remove the directory yourself, then delete the session again.

658 650

659A worktree you created yourself and started the session inside is left in place either way.651| Your case | What to do |

~~660~~ 652| :- | :- |

661A session whose worktree directory belongs to no git repository, because the repository was deleted or a [`WorktreeCreate` hook](https://code.claude.com/docs/en/hooks#worktreecreate) created the directory elsewhere, can still be deleted. While files remain in the directory:653| No `WorktreeCreate` hook manages the directory | To discard the files, press `Ctrl+X` twice on the session's row in agent view. Or remove the directory yourself, then run `claude rm <id>` again |

~~662~~ 654| A `WorktreeCreate` hook manages the directory, and you have a [`WorktreeRemove` hook](https://code.claude.com/docs/en/hooks#worktreeremove) | To try removing the directory with your hook, press `Ctrl+X` twice on the session's row in agent view. Or remove the directory yourself, then run `claude rm <id>` again |

663* Agent view asks for the same `Ctrl+X` double-press before discarding them. For a hook-created directory it runs your [`WorktreeRemove` hook](https://code.claude.com/docs/en/hooks#worktreeremove) instead, and without one it refuses the delete and keeps the session.655| A `WorktreeCreate` hook manages the directory, and you have no `WorktreeRemove` hook | Remove the directory yourself, then run `claude rm <id>` again |

664* `claude rm` keeps the session and worktree, and names the reason.

~~665~~

666Either path keeps a directory that another finished session's records name.

667 656

668### Set the model, effort, and fast mode657### Set the model, effort, and fast mode

669 658

774| [`--add-dir <path>`](https://code.claude.com/docs/en/permissions#additional-directories-grant-file-access-not-configuration) | Grant file access to an additional directory |763| [`--add-dir <path>`](https://code.claude.com/docs/en/permissions#additional-directories-grant-file-access-not-configuration) | Grant file access to an additional directory |

775| [`--plugin-dir <path>`](https://code.claude.com/docs/en/plugins/create#load-a-directory-or-archive-for-one-session) | Load a plugin from a local directory |764| [`--plugin-dir <path>`](https://code.claude.com/docs/en/plugins/create#load-a-directory-or-archive-for-one-session) | Load a plugin from a local directory |

776| [`--mcp-config <file-or-json>`](https://code.claude.com/docs/en/mcp) | Load MCP servers from a config file or JSON string |765| [`--mcp-config <file-or-json>`](https://code.claude.com/docs/en/mcp) | Load MCP servers from a config file or JSON string |

777| `--strict-mcp-config` | Use only the MCP servers from `--mcp-config`, ignoring other MCP configuration. See [Exclusive control with managed-mcp.json](https://code.claude.com/docs/en/managed-mcp.md#exclusive-control-with-managed-mcp-json) for what the flag does under a managed MCP file |766| `--strict-mcp-config` | Skip the MCP servers configured in places such as `.mcp.json`, and load the ones you pass with `--mcp-config`. See [Exclusive control with managed-mcp.json](https://code.claude.com/docs/en/managed-mcp.md#exclusive-control-with-managed-mcp-json) for what the flag does under a managed MCP file |

778 767

779Repeat `--add-dir`, `--plugin-dir`, or `--mcp-config` once per value. `claude agents` doesn't support the space-separated form, such as `--add-dir a b c`.768Repeat `--add-dir`, `--plugin-dir`, or `--mcp-config` once per value. `claude agents` doesn't support the space-separated form, such as `--add-dir a b c`.

780 769

803| `claude respawn <id>` | Restart a session, running or stopped, for example to pick up an updated Claude Code binary. A session that has a saved conversation resumes it |792| `claude respawn <id>` | Restart a session, running or stopped, for example to pick up an updated Claude Code binary. A session that has a saved conversation resumes it |

804| `claude respawn --all` | Restart every running session, e.g. to move all sessions onto an updated Claude Code binary at once |793| `claude respawn --all` | Restart every running session, e.g. to move all sessions onto an updated Claude Code binary at once |

805| `claude rm <id>` | Remove a session from the list, along with a worktree Claude created for it when that's safe to delete; see [What deleting a session removes](#what-deleting-a-session-removes). The conversation transcript stays on your local machine and remains available through `claude --resume` |794| `claude rm <id>` | Remove a session from the list, along with a worktree Claude created for it when that's safe to delete. If Claude Code refuses to delete the session because of its worktree, see [Delete a session after Claude Code refuses](#delete-a-session-after-claude-code-refuses). The conversation transcript stays on your local machine and remains available through `claude --resume` |

806| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | Delete a session whose delete was refused over unpushed commits, discarding the worktree along with its branch and commits. Pass the exact value that refusal printed; see [What deleting a session removes](#what-deleting-a-session-removes). Requires v2.1.260 or later |795| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | Try again to delete a session and discard its worktree, after Claude Code refused because of unpushed commits. Copy the command from the `claude rm` message that offers it; see [Worktree has commits that are not pushed anywhere](https://code.claude.com/docs/en/errors.md#worktree-has-commits-that-are-not-pushed-anywhere). Requires v2.1.260 or later |

807| `claude rm <id> --force-remove-worktree <worktree-id>` | Delete a session whose delete was refused because git or the `WorktreeRemove` hook couldn't remove its worktree, deleting the worktree directory anyway and leaving its branch in the repository. Pass the exact value that refusal printed; see [What deleting a session removes](#what-deleting-a-session-removes). Requires v2.1.268 or later |796| `claude rm <id> --force-remove-worktree <worktree-id>` | Try again to delete a session and remove its worktree directory anyway, after Claude Code refused because it couldn't remove the worktree. Copy the command from the `claude rm` message that offers it; see [Resolve a `Worktree not removed` message](#resolve-a-worktree-not-removed-message). Requires v2.1.268 or later |

808| `claude daemon status` | Print the [supervisor's](#the-supervisor-process) state, version, socket directory, and worker count |797| `claude daemon status` | Print the [supervisor's](#the-supervisor-process) state, version, socket directory, and worker count |

809| `claude daemon logs` | Follow the supervisor's log file, [`~/.claude/daemon.log`](#where-state-is-stored), printing new lines as they arrive until you press `Ctrl+C` |798| `claude daemon logs` | Follow the supervisor's log file, [`~/.claude/daemon.log`](#where-state-is-stored), printing new lines as they arrive until you press `Ctrl+C` |

810| `claude daemon stop --any` | Stop the supervisor process and the background sessions it hosts. Pass `--keep-workers` to leave background sessions running for [the next supervisor](#the-supervisor-process) to reconnect to. The next `claude agents` or `claude --bg` starts a fresh supervisor |799| `claude daemon stop --any` | Stop the supervisor process and the background sessions it hosts. Pass `--keep-workers` to leave background sessions running for [the next supervisor](#the-supervisor-process) to reconnect to. The next `claude agents` or `claude --bg` starts a fresh supervisor |

939 928

940 Press `Enter` on the row and the footer shows `Press enter again to resume this session (it ended while the background service was off), or ctrl+x to remove it.` Press `Enter` on the same row again to resume its saved conversation. A reply, or `claude attach <id>`, resumes it without that footer prompt.929 Press `Enter` on the row and the footer shows `Press enter again to resume this session (it ended while the background service was off), or ctrl+x to remove it.` Press `Enter` on the same row again to resume its saved conversation. A reply, or `claude attach <id>`, resumes it without that footer prompt.

941 930

942When [transcript cleanup](https://code.claude.com/docs/en/settings-reference.md#cleanupperioddays) has removed a stopped session's saved conversation, Claude Code refuses to open the row: the message says there is nothing to resume. `claude rm <id>` deletes the row, except in the [kept cases](#what-deleting-a-session-removes) described above, and `claude respawn <id>` runs its original prompt again. See [This session's saved conversation is no longer on disk](https://code.claude.com/docs/en/errors.md#this-sessions-saved-conversation-is-no-longer-on-disk).931When [transcript cleanup](https://code.claude.com/docs/en/settings-reference.md#cleanupperioddays) has removed a stopped session's saved conversation, Claude Code refuses to open the row: the message says there is nothing to resume. `claude rm <id>` deletes the row, unless [Claude Code refuses](#what-deleting-a-session-removes), and `claude respawn <id>` runs its original prompt again. See [This session's saved conversation is no longer on disk](https://code.claude.com/docs/en/errors.md#this-sessions-saved-conversation-is-no-longer-on-disk).

943 932

944Sleep alone doesn't stop sessions. Sessions are preserved across sleep and the supervisor reconnects to them on wake.933Sleep alone doesn't stop sessions. Sessions are preserved across sleep and the supervisor reconnects to them on wake.

945 934

973 962

974When a background session's process exits before it finishes starting and the host is low on memory, the row's status names the exit and adds `possibly low memory — free some up and retry`.963When a background session's process exits before it finishes starting and the host is low on memory, the row's status names the exit and adds `possibly low memory — free some up and retry`.

975 964

976The note is a hypothesis, not a confirmed cause. Claude Code adds it only when the process exited silently, without writing an error and without being stopped by a signal, and the host reported low memory at that moment. When the process did write an error before exiting, the row shows that error instead.965> [!NOTE]

966>

967> The note is a hypothesis, not a confirmed cause. Claude Code adds it only when the process exited silently, without writing an error and without being stopped by a signal, and the host reported low memory at that moment. When the process did write an error before exiting, the row shows that error instead.

977 968

978Free up memory on the machine, then attach or reply to the row and the supervisor starts a fresh process for the session. When memory stays low, the supervisor also [stops idle sessions](#the-supervisor-process) to free resources on its own, and stops idle pinned sessions too if stopping the others freed nothing.969Free up memory on the host, then press `Enter` on the row, and press it again if [the footer asks](#opening-a-session-says-it-has-no-saved-transcript). The [supervisor](#the-supervisor-process) starts a new process for the session. When memory stays low, the supervisor also [stops idle sessions](#the-supervisor-process) to free resources on its own, and stops idle pinned sessions too if stopping the others freed nothing.

979 970

980### Agent view says the background service did not respond971### Agent view says the background service did not respond

981 972

1036 1027

1037### `.claude/worktrees/` is filling up1028### `.claude/worktrees/` is filling up

1038 1029

1039Deleting a session in agent view removes the worktree Claude created for it, but [some deletes keep the worktree or leave its directory on disk](#what-deleting-a-session-removes), so leftover directories can accumulate. Directories git no longer recognizes don't appear in `git worktree list`, so remove those by hand.1030Deleting a session in agent view removes the worktree Claude created for it, but [some worktree directories stay on disk](#what-deleting-a-session-removes). Directories git no longer recognizes don't appear in `git worktree list`, so remove those yourself.

1040 1031

1041List leftover entries with `git worktree list` in the project directory and remove each with `git worktree remove <path>`. See [Clean up worktrees](https://code.claude.com/docs/en/worktrees.md#clean-up-worktrees).1032List leftover entries with `git worktree list` in the project directory and remove each with `git worktree remove <path>`. If git refuses, see [Clean up subagent and background-session worktrees](https://code.claude.com/docs/en/worktrees.md#clean-up-subagent-and-background-session-worktrees).

1042 1033

1043## Limitations1034## Limitations

1044 1035

1046 1037

1047* **Rate limits apply**: background sessions consume your subscription usage the same as interactive sessions, so running ten agents in parallel uses quota roughly ten times as fast as running one.1038* **Rate limits apply**: background sessions consume your subscription usage the same as interactive sessions, so running ten agents in parallel uses quota roughly ten times as fast as running one.

1048* **Sessions are local**: background sessions run on your machine. They are preserved across sleep but stop if the machine shuts down.1039* **Sessions are local**: background sessions run on your machine. They are preserved across sleep but stop if the machine shuts down.

1049* **Claude-created worktrees are deleted with the session in agent view**: commit changes before deleting a session that edited files in its own worktree. [Some deletes keep the worktree instead](#what-deleting-a-session-removes).1040* **Claude-created worktrees are deleted with the session in agent view**: commit changes before deleting a session that edited files in its own worktree. [Some worktrees stay on disk](#what-deleting-a-session-removes).

1050 1041

1051## Related resources1042## Related resources

1052 1043

artifacts.md +2 −2

Details

432 432

433To set how long artifacts are kept before automatic deletion, go to [**Organization settings > Data and privacy**](https://claude.ai/admin-settings/data-privacy-controls). You can set separate retention periods for artifacts that are still private to their author and artifacts that have been shared.433To set how long artifacts are kept before automatic deletion, go to [**Organization settings > Data and privacy**](https://claude.ai/admin-settings/data-privacy-controls). You can set separate retention periods for artifacts that are still private to their author and artifacts that have been shared.

434 434

435### Review the audit log435### Audit artifact activity with the Compliance API

436 436

437Publishing, sharing, and deleting an artifact each appear in your organization's audit log under the `claude_artifact_*` event types, the same family used for artifacts created in claude.ai conversations.437On Enterprise plans, query the Compliance API's [Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed) to see who published, shared, or deleted an artifact. To find the activity types to filter by, expand `activity_types` in the [Activity Feed reference](https://platform.claude.com/docs/en/api/compliance/activities/list) and look for names that contain `artifact`.

438 438

439### Allowlist the viewer domain439### Allowlist the viewer domain

440 440

cli-reference.md +2 −2

Details

43| `claude purge [path]` | Delete all local Claude Code state for a project: transcripts, task lists, debug logs, file-edit history, prompt history lines, and the project's entry in `~/.claude.json`. Omit `[path]` to pick from an interactive list. Flags: `--dry-run` to preview, `-y`/`--yes` to skip confirmation, `-i`/`--interactive` to confirm each item, `--all` for every project. See [Clear local data](https://code.claude.com/docs/en/claude-directory.md#clear-local-data) | `claude purge ~/work/repo --dry-run` |43| `claude purge [path]` | Delete all local Claude Code state for a project: transcripts, task lists, debug logs, file-edit history, prompt history lines, and the project's entry in `~/.claude.json`. Omit `[path]` to pick from an interactive list. Flags: `--dry-run` to preview, `-y`/`--yes` to skip confirmation, `-i`/`--interactive` to confirm each item, `--all` for every project. See [Clear local data](https://code.claude.com/docs/en/claude-directory.md#clear-local-data) | `claude purge ~/work/repo --dry-run` |

44| `claude remote-control` | Start a [Remote Control](https://code.claude.com/docs/en/remote-control.md) server to control Claude Code from claude.ai or the Claude app. Alias: `claude rc`. Runs in server mode (no local interactive session). See [Server mode flags](https://code.claude.com/docs/en/remote-control.md#start-a-remote-control-session). After you stop the server, you can bring back the sessions it was serving. See [Resume sessions after stopping the server](https://code.claude.com/docs/en/remote-control.md#resume-sessions-after-stopping-the-server) | `claude remote-control --name "My Project"` |44| `claude remote-control` | Start a [Remote Control](https://code.claude.com/docs/en/remote-control.md) server to control Claude Code from claude.ai or the Claude app. Alias: `claude rc`. Runs in server mode (no local interactive session). See [Server mode flags](https://code.claude.com/docs/en/remote-control.md#start-a-remote-control-session). After you stop the server, you can bring back the sessions it was serving. See [Resume sessions after stopping the server](https://code.claude.com/docs/en/remote-control.md#resume-sessions-after-stopping-the-server) | `claude remote-control --name "My Project"` |

45| `claude respawn <id>` | Restart a [background session](https://code.claude.com/docs/en/agent-view.md#manage-sessions-from-the-shell), running or stopped, with its conversation intact. Use `--all` to restart every running session, e.g. to pick up an updated Claude Code binary | `claude respawn 7c5dcf5d` |45| `claude respawn <id>` | Restart a [background session](https://code.claude.com/docs/en/agent-view.md#manage-sessions-from-the-shell), running or stopped, with its conversation intact. Use `--all` to restart every running session, e.g. to pick up an updated Claude Code binary | `claude respawn 7c5dcf5d` |

46| `claude rm <id>` | Remove a [background session](https://code.claude.com/docs/en/agent-view.md#manage-sessions-from-the-shell) from the list. When the removal is [refused over the session's worktree](https://code.claude.com/docs/en/agent-view.md#what-deleting-a-session-removes) and a second `claude rm` can resolve it, the refusal prints the exact flag and value to pass: `--discard-unpushed <commit>@<worktree-id>` discards a worktree that has unpushed commits along with those commits, and `--force-remove-worktree <worktree-id>` deletes a worktree directory that git or the `WorktreeRemove` hook couldn't remove. `--discard-unpushed` requires Claude Code v2.1.260 or later, and `--force-remove-worktree` requires v2.1.268 or later. The conversation transcript stays on your local machine, available through `claude --resume` | `claude rm 7c5dcf5d` |46| `claude rm <id>` | Remove a [background session](https://code.claude.com/docs/en/agent-view.md#manage-sessions-from-the-shell) from the list. If Claude Code refuses to delete the session because of its worktree, see [Delete a session after Claude Code refuses](https://code.claude.com/docs/en/agent-view.md#delete-a-session-after-claude-code-refuses). The conversation transcript stays on your local machine, available through `claude --resume` | `claude rm 7c5dcf5d` |

47| `claude self-hosted-runner` | Start a runner process that registers this machine or container with a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments) and hosts Claude Code cloud sessions on your infrastructure. Run `claude self-hosted-runner setup` for a guided operator walkthrough, `claude self-hosted-runner doctor` to [diagnose a deployed runner](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#troubleshooting), and `claude self-hosted-runner orchestrator` to spawn [on-demand runners](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#on-demand-runners). Requires Claude Code v2.1.224 or later | `claude self-hosted-runner setup` |47| `claude self-hosted-runner` | Start a runner process that registers this machine or container with a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments) and hosts Claude Code cloud sessions on your infrastructure. Run `claude self-hosted-runner setup` for a guided operator walkthrough, `claude self-hosted-runner doctor` to [diagnose a deployed runner](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#troubleshooting), and `claude self-hosted-runner orchestrator` to spawn [on-demand runners](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#on-demand-runners). Requires Claude Code v2.1.224 or later | `claude self-hosted-runner setup` |

48| `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](https://code.claude.com/docs/en/authentication.md#generate-a-long-lived-token) | `claude setup-token` |48| `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](https://code.claude.com/docs/en/authentication.md#generate-a-long-lived-token) | `claude setup-token` |

129| `--setting-sources` | Comma-separated list of setting sources to load (`user`, `project`, `local`). See [agent view](https://code.claude.com/docs/en/agent-view.md#what-carries-over-when-you-background) and [agent teams](https://code.claude.com/docs/en/agent-teams.md#context-and-communication) for the sessions you start from this one that inherit the list | `claude --setting-sources user,project` |129| `--setting-sources` | Comma-separated list of setting sources to load (`user`, `project`, `local`). See [agent view](https://code.claude.com/docs/en/agent-view.md#what-carries-over-when-you-background) and [agent teams](https://code.claude.com/docs/en/agent-teams.md#context-and-communication) for the sessions you start from this one that inherit the list | `claude --setting-sources user,project` |

130| `--settings` | Path to a settings JSON file or an inline JSON string. Values you set here override the same keys in your `settings.json` files for this session. Keys you omit keep their file-based values. The file must be a regular file no larger than 2 MiB. See [settings precedence](https://code.claude.com/docs/en/settings.md#settings-precedence) | `claude --settings ./settings.json` |130| `--settings` | Path to a settings JSON file or an inline JSON string. Values you set here override the same keys in your `settings.json` files for this session. Keys you omit keep their file-based values. The file must be a regular file no larger than 2 MiB. See [settings precedence](https://code.claude.com/docs/en/settings.md#settings-precedence) | `claude --settings ./settings.json` |

131| `--strict-mcp-config` | Only use MCP servers from `--mcp-config`, ignoring all other MCP configurations. See [Exclusive control with managed-mcp.json](https://code.claude.com/docs/en/managed-mcp.md#exclusive-control-with-managed-mcp-json) for what the flag does under a managed MCP file | `claude --strict-mcp-config --mcp-config ./mcp.json` |131| `--strict-mcp-config` | Skip the MCP servers configured in places such as `.mcp.json`, `~/.claude.json`, or a plugin, and load the ones you pass with `--mcp-config`. See [Exclusive control with managed-mcp.json](https://code.claude.com/docs/en/managed-mcp.md#exclusive-control-with-managed-mcp-json) for what the flag does under a managed MCP file | `claude --strict-mcp-config --mcp-config ./mcp.json` |

134| `--system-prompt-snapshot` | Pass `off` to rebuild the system prompt on every request instead of reusing the prompt [recorded on the conversation's first request](#system-prompt-flags-in-resumed-conversations), for example while you iterate on `--append-system-prompt` text across `--continue` runs. Requires Claude Code v2.1.257 or later | `claude --system-prompt-snapshot off` |134| `--system-prompt-snapshot` | Pass `off` to rebuild the system prompt on every request instead of reusing the prompt [recorded on the conversation's first request](#system-prompt-flags-in-resumed-conversations), for example while you iterate on `--append-system-prompt` text across `--continue` runs. Requires Claude Code v2.1.257 or later | `claude --system-prompt-snapshot off` |

desktop.md +2 −1

Details

2127 2127

2128To stop that, also deploy `forceLoginOrgUUID` in the Claude Desktop policy (in `HKLM` on Windows), with your claude.ai organization ID. Unless the policy itself [selects the Claude API](https://claude.com/docs/third-party/claude-desktop/claude-api#choose-an-authentication-approach), Claude Desktop stops using a person's own API key or Console account at the app's next launch.2128To stop that, also deploy `forceLoginOrgUUID` in the Claude Desktop policy (in `HKLM` on Windows), with your claude.ai organization ID. Unless the policy itself [selects the Claude API](https://claude.com/docs/third-party/claude-desktop/claude-api#choose-an-authentication-approach), Claude Desktop stops using a person's own API key or Console account at the app's next launch.

2129 2129

2130Check two cases before you deploy it:2130Check three cases before you deploy it:

2131 2131

2132* **Claude Console organizations**: don't deploy `forceLoginOrgUUID` on its own with a Claude Console organization's ID, or you'd lock your people out of Claude Desktop. See [Which devices offer the Claude API account sign-in](https://claude.com/docs/third-party/claude-desktop/claude-api#which-devices-offer-the-claude-api-account-sign-in) instead.2132* **Claude Console organizations**: don't deploy `forceLoginOrgUUID` on its own with a Claude Console organization's ID, or you'd lock your people out of Claude Desktop. See [Which devices offer the Claude API account sign-in](https://claude.com/docs/third-party/claude-desktop/claude-api#which-devices-offer-the-claude-api-account-sign-in) instead.

2133* **Enterprise Admin Console**: if it delivers your computers' Claude Desktop configuration, update them to Claude Desktop v2.37337.0 or later first, because earlier versions ignore it once this key is set. See [Keep a device on its managed profile](https://claude.com/docs/third-party/claude-desktop/admin-console#keep-a-device-on-its-managed-profile).2133* **Enterprise Admin Console**: if it delivers your computers' Claude Desktop configuration, update them to Claude Desktop v2.37337.0 or later first, because earlier versions ignore it once this key is set. See [Keep a device on its managed profile](https://claude.com/docs/third-party/claude-desktop/admin-console#keep-a-device-on-its-managed-profile).

2134* **Third-party providers**: if people set up their own [third-party inference configuration](https://claude.com/docs/third-party/claude-desktop/in-app-configuration) in the app, Claude Desktop ignores that configuration from the next launch after you deploy this key. To keep people on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or an LLM gateway, [deploy a configuration](https://claude.com/docs/third-party/claude-desktop/configuration) to their computers in the same Claude Desktop policy.

2134 2135

2135### Network access requirements2136### Network access requirements

2136 2137

errors.md +4 −8

Details

5556 5556

5557### Worktree has commits that are not pushed anywhere5557### Worktree has commits that are not pushed anywhere

5558 5558

5559You tried to delete a [background session](https://code.claude.com/docs/en/agent-view.md#what-deleting-a-session-removes) whose worktree holds commits Claude Code can't confirm are saved elsewhere. Claude Code keeps the worktree and the session row rather than destroy the commits unseen. `claude rm` names the branch and the unpushed commits, and says how to proceed:5559You tried to delete a [background session](https://code.claude.com/docs/en/agent-view.md#what-deleting-a-session-removes) whose worktree holds commits Claude Code can't confirm are saved elsewhere. `claude rm` says how to proceed:

5560 5560

5561```text theme={null}5561```text theme={null}

5562kept 7c5dcf5d — its worktree is still at “/home/you/project/.claude/worktrees/fix-login”5562kept 7c5dcf5d — its worktree is still at “/home/you/project/.claude/worktrees/fix-login”

5566 5566

5567When Claude Code can't summarize the commits, the detail line reads `The worktree has unpushed commits` instead. In [agent view](https://code.claude.com/docs/en/agent-view.md), the session's row shows `not removed` with the same reason.5567When Claude Code can't summarize the commits, the detail line reads `The worktree has unpushed commits` instead. In [agent view](https://code.claude.com/docs/en/agent-view.md), the session's row shows `not removed` with the same reason.

5568 5568

5569Commits on a remote don't block the delete. Neither do commits on the local copy of your `origin` remote's default branch, as long as that branch is checked out in your main checkout, the repository directory itself rather than a worktree.

~~5570~~

5571**What to do:**5569**What to do:**

5572 5570

5573* To keep the commits, push the worktree's branch, or merge it into the default branch checked out in your main checkout, then delete the session again5571* To keep the commits, push them. Once the push puts them on a remote-tracking branch, such as `origin/claude/fix-login`, try deleting the session again.

5574* To discard the commits, run the `claude rm <id> --discard-unpushed` command the message printed, or press `Ctrl+X` twice on the session's row in agent view again. This removes the session and the worktree along with its branch, the unpushed commits, and any uncommitted changes. If the delete is refused again, follow the new message.5572* If the message offers to discard the commits, first make sure you don't need the worktree, the commits or any uncommitted changes. Then take the step the message gives: press `Ctrl+X` twice on the session's row in agent view, or run the `claude rm <id> --discard-unpushed <commit>@<worktree-id>` command that `claude rm` printed. If Claude Code refuses again, follow the new message.

5575* When the message says the worktree is also recorded by another finished session, deleting again doesn't discard it: push the commits, then delete the session again5573* When the message says the worktree is also recorded by another finished session, deleting again doesn't discard it: push the commits, then try deleting the session again

5576 5574

5577Before v2.1.268, `claude rm` put the commit summary on the `kept` line itself. When `claude rm` couldn't summarize the commits, the `kept` line read `worktree has commits that are not pushed anywhere` in place of the summary.5575Before v2.1.268, `claude rm` put the commit summary on the `kept` line itself. When `claude rm` couldn't summarize the commits, the `kept` line read `worktree has commits that are not pushed anywhere` in place of the summary.

5578 5576

5579Before v2.1.260, the message didn't name the branch or commits, and there was no discard route. You can still delete the session, losing uncommitted changes but keeping the branch and commits. Run `git worktree remove --force --force <path>` with the path the refusal printed, then `claude rm <id>`. Git needs `--force` twice for a locked worktree.5577Before v2.1.260, the message didn't name the branch or commits, and there was no discard route. You can still delete the session, losing uncommitted changes but keeping the branch and commits. Run `git worktree remove --force --force <path>` with the path the refusal printed, then `claude rm <id>`. Git needs `--force` twice for a locked worktree.

5580 5578

5581Before v2.1.248, the default branch checked out in your main checkout didn't count: a branch you had already merged there still triggered this refusal until its commits reached a remote.

~~5582~~

5583### Terminal host process died5579### Terminal host process died

5584 5580

5585Each [background session's](https://code.claude.com/docs/en/agent-view.md) terminal runs in a host process under the background service, and that process died while the service still held its connection, so the session couldn't be reached.5581Each [background session's](https://code.claude.com/docs/en/agent-view.md) terminal runs in a host process under the background service, and that process died while the service still held its connection, so the session couldn't be reached.

feature-availability.md +1 −1

Details

35These have provider-specific differences:35These have provider-specific differences:

36 36

37* **MCP servers**: [connectors from claude.ai](https://code.claude.com/docs/en/mcp.md#use-mcp-servers-from-claude-ai) load only when your claude.ai subscription is the active authentication method. [Tool search](https://code.claude.com/docs/en/mcp.md#configure-tool-search) isn't supported on Microsoft Foundry [deployments hosted on Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options). On Google Cloud's Agent Platform, tool search isn't supported on models earlier than Claude Opus 4.5, Claude Sonnet 4.5, and Claude Haiku 4.537* **MCP servers**: [connectors from claude.ai](https://code.claude.com/docs/en/mcp.md#use-mcp-servers-from-claude-ai) load only when your claude.ai subscription is the active authentication method. [Tool search](https://code.claude.com/docs/en/mcp.md#configure-tool-search) isn't supported on Microsoft Foundry [deployments hosted on Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options). On Google Cloud's Agent Platform, tool search isn't supported on models earlier than Claude Opus 4.5, Claude Sonnet 4.5, and Claude Haiku 4.5

38* **Subagents**: when the main conversation runs Fable, the built-in [Explore subagent](https://code.claude.com/docs/en/sub-agents.md#built-in-subagents) runs on Opus with a Claude subscription, an Anthropic Console account, or an [LLM gateway](https://code.claude.com/docs/en/llm-gateway) reached through `ANTHROPIC_BASE_URL`. On other providers, including Claude Platform on AWS, it runs on Fable38* **Subagents**: when the parent conversation runs Fable, the built-in [Explore subagent](https://code.claude.com/docs/en/sub-agents.md#built-in-subagents) runs on Opus with a Claude subscription, an Anthropic Console account, or an [LLM gateway](https://code.claude.com/docs/en/llm-gateway) reached through `ANTHROPIC_BASE_URL`. On other providers, including Claude Platform on AWS, it runs on Fable

39* **[Commands](https://code.claude.com/docs/en/commands.md#all-commands)**:39* **[Commands](https://code.claude.com/docs/en/commands.md#all-commands)**:

40 * `/design-sync` and `/import` with its `claude import` subcommand form are unavailable on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, and Claude Platform on AWS, and through a [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway#availability-and-limitations)40 * `/design-sync` and `/import` with its `claude import` subcommand form are unavailable on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, and Claude Platform on AWS, and through a [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway#availability-and-limitations)

41 * `/voice` requires a claude.ai account41 * `/voice` requires a claude.ai account

features-overview.md +1 −1

Details

188>188>

189> **Put guardrails in hooks.** An instruction like "never edit `.env`" in CLAUDE.md or a skill is a request, not a guarantee. A `PreToolUse` hook that blocks the edit is enforcement. If a rule must hold every time, make it a hook rather than a prompt instruction.189> **Put guardrails in hooks.** An instruction like "never edit `.env`" in CLAUDE.md or a skill is a request, not a guarantee. A `PreToolUse` hook that blocks the edit is enforcement. If a rule must hold every time, make it a hook rather than a prompt instruction.

190>190>

191> **Pair a hook with a skill.** If a `PostToolUse` hook runs your linter, printing the errors to stdout isn't enough for Claude to see them. When there are errors, have the hook print them to stderr instead and [exit with code 2](https://code.claude.com/docs/en/hooks.md#exit-code-2-behavior-per-event). To give Claude your own rules for fixing the errors, write a skill such as `/fix-lint`.191> **Pair a hook with a skill.** Use a `PostToolUse` hook to run your linter and [send the errors to Claude](https://code.claude.com/docs/en/hooks.md#exit-code-2-behavior-per-event). To give Claude your own rules for fixing the errors, write a skill such as `/fix-lint`.

192 192

193### Understand how features layer193### Understand how features layer

194 194

glossary.md +1 −1

Details

283 283

284### Sandboxing284### Sandboxing

285 285

286OS-level filesystem and network isolation for the Bash tool. Commands run inside a boundary you define upfront, so Claude can work freely within it without per-command approval prompts. Sandboxing is a separate layer from [permission rules](#permission-rule).286OS-level filesystem and network isolation for the Bash tool. Commands run inside a boundary you define upfront. Sandboxing is a separate layer from [permission rules](#permission-rule).

287 287

288Learn more: [Sandboxing](https://code.claude.com/docs/en/sandboxing.md)288Learn more: [Sandboxing](https://code.claude.com/docs/en/sandboxing.md)

289 289

hooks-guide.md +5 −1

Details

242 242

243### Block edits to protected files243### Block edits to protected files

244 244

245Prevent Claude from modifying sensitive files like `.env`, `package-lock.json`, or anything in `.git/`. Claude receives feedback explaining why the edit was blocked, so it can adjust its approach.245Stop Claude's `Edit` and `Write` tools from modifying sensitive files like `.env`, `package-lock.json`, or anything in `.git/`. Claude receives feedback explaining why the edit was blocked, so it can adjust its approach.

246 246

247This example uses a separate script file that the hook calls. The script checks the target file path against a list of protected patterns and exits with code 2 to block the edit.247This example uses a separate script file that the hook calls. The script checks the target file path against a list of protected patterns and exits with code 2 to block the edit.

248 248

306 306

307Ask Claude to add a comment to your `.env` file. Claude Code blocks the edit before it runs and passes the script's `Blocked:` message to Claude as feedback.307Ask Claude to add a comment to your `.env` file. Claude Code blocks the edit before it runs and passes the script's `Blocked:` message to Claude as feedback.

308 308

309Claude can still change the protected files with shell commands. To block some of those commands, add an [`Edit` deny rule](https://code.claude.com/docs/en/permissions#what-read-and-edit-rules-cover) per path under `permissions.deny` in `.claude/settings.json`, like `Edit(/.env)` for the project root's `.env`.

310

311Even with those rules, Claude can change `.env` in other ways. To limit which files commands can write to, see [Configure sandboxing](https://code.claude.com/docs/en/sandboxing.md#configure-sandboxing).

312

309### Re-inject context after compaction313### Re-inject context after compaction

310 314

311When Claude's context window fills up, compaction summarizes the conversation to free space. This can lose important details. Use a `SessionStart` hook with a `compact` matcher to re-inject critical context after every compaction.315When Claude's context window fills up, compaction summarizes the conversation to free space. This can lose important details. Use a `SessionStart` hook with a `compact` matcher to re-inject critical context after every compaction.

llm-gateway-protocol.md +1 −0

Details

296* The top-level `output_config.effort` field. [Automatic retry and error forwarding](#automatic-retry-and-error-forwarding) covers an upstream that rejects it296* The top-level `output_config.effort` field. [Automatic retry and error forwarding](#automatic-retry-and-error-forwarding) covers an upstream that rejects it

297* The adaptive reasoning `thinking` field, which has no beta header297* The adaptive reasoning `thinking` field, which has no beta header

298* The `role: "system"` entries that carry [mid-conversation system messages](#feature-pass-through)298* The `role: "system"` entries that carry [mid-conversation system messages](#feature-pass-through)

299* The `anthropic-beta` value and `safeguards` field for auto mode's [server-side classifier review](https://code.claude.com/docs/en/permission-modes.md#server-side-classifier-review), in sessions where that review stays on, such as when `/status` shows **Auto mode server** as `Enabled`. To turn the review off, set `CLAUDE_CODE_AUTO_MODE_SERVER=0` before starting the session. In the terminal, `/status` then shows **Auto mode server** as `Disabled`.

299* The OAuth `anthropic-beta` value that subscription authentication requires300* The OAuth `anthropic-beta` value that subscription authentication requires

300* Header values and body fields developers add themselves through [`ANTHROPIC_BETAS`](https://code.claude.com/docs/en/env-vars) or [`CLAUDE_CODE_EXTRA_BODY`](https://code.claude.com/docs/en/env-vars)301* Header values and body fields developers add themselves through [`ANTHROPIC_BETAS`](https://code.claude.com/docs/en/env-vars) or [`CLAUDE_CODE_EXTRA_BODY`](https://code.claude.com/docs/en/env-vars)

301 302

managed-mcp.md +3 −2

Details

31| :- | :- | :- |31| :- | :- | :- |

36| **Plugin servers only** | Users can't add servers through `~/.claude.json` or `.mcp.json`; [skills-directory plugins](https://code.claude.com/docs/en/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings) stop loading as plugins, and servers from other plugins still load | [`strictPluginOnlyCustomization`](https://code.claude.com/docs/en/settings-reference#strictpluginonlycustomization) with `mcp` in the list |36| **Plugin servers only** | Users can't add servers through `~/.claude.json` or `.mcp.json`; [skills-directory plugins](https://code.claude.com/docs/en/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings) stop loading as plugins, and servers from other plugins still load | [`strictPluginOnlyCustomization`](https://code.claude.com/docs/en/settings-reference#strictpluginonlycustomization) with `mcp` in the list |

49* The servers the file defines49* The servers the file defines

50* Servers you [provide through `managedMcpServers`](#provide-servers-through-managed-settings)50* Servers you [provide through `managedMcpServers`](#provide-servers-through-managed-settings)

51* In-process servers that the app that started the session registers, such as the VS Code extension's own server or the [connectors the desktop app delivers](https://code.claude.com/docs/en/mcp.md#how-connectors-reach-claude-code)51* In-process servers that the app that started the session registers, such as the VS Code extension's own server or the [connectors the desktop app delivers](https://code.claude.com/docs/en/mcp.md#how-connectors-reach-claude-code)

52* The server that Claude Code creates when a [mod](https://code.claude.com/docs/en/plugins/mods/overview.md) [adds tools](https://code.claude.com/docs/en/plugins/mods/api.md#add-a-tool). To block the tools that your users' mods add, [stop user-installed mods from loading](https://code.claude.com/docs/en/plugins/mods/admin.md#stop-user-installed-mods-from-loading).

52* The built-in [Claude in Chrome](https://code.claude.com/docs/en/chrome.md) server, if you [allow it alongside the managed set](#allow-claude-in-chrome-alongside-the-managed-set)53* The built-in [Claude in Chrome](https://code.claude.com/docs/en/chrome.md) server, if you [allow it alongside the managed set](#allow-claude-in-chrome-alongside-the-managed-set)

53 54

54Users can't add, modify, or use any other MCP servers, including plugin-provided servers and servers passed with the [`--mcp-config` CLI flag](https://code.claude.com/docs/en/cli-reference#cli-flags). The file also suppresses the claude.ai connectors Claude Code fetches itself unless you [allow them alongside the managed set](#allow-claude-ai-connectors-alongside-the-managed-set).55Users can't add, modify, or use any other MCP servers, including plugin-provided servers and servers passed with the [`--mcp-config` CLI flag](https://code.claude.com/docs/en/cli-reference#cli-flags). The file also suppresses the claude.ai connectors Claude Code fetches itself unless you [allow them alongside the managed set](#allow-claude-ai-connectors-alongside-the-managed-set).

137}138}

138```139```

139 140

140`claude mcp add` fails with the enterprise-policy error above. Servers users had previously configured stop loading the next time they start a session, with no warning that policy is the reason. Servers you provide through `managedMcpServers`, and anything else you allow alongside the managed set, still load under an empty map, so leave those keys unset to turn MCP off completely.141`claude mcp add` fails with the enterprise-policy error above. Servers users had previously configured stop loading the next time they start a session, with no warning that policy is the reason. Servers you provide through `managedMcpServers`, and anything else you allow alongside the managed set, [still load](#exclusive-control-with-managed-mcp-json) under an empty map, so leave those keys unset.

141 142

142### Allow claude.ai connectors alongside the managed set143### Allow claude.ai connectors alongside the managed set

143 144

mcp.md +1 −1

Details

806 806

807* Add it to [`disabledMcpjsonServers`](https://code.claude.com/docs/en/settings-reference#disabledmcpjsonservers), which blocks it in every permission mode.807* Add it to [`disabledMcpjsonServers`](https://code.claude.com/docs/en/settings-reference#disabledmcpjsonservers), which blocks it in every permission mode.

808* Exclude project settings entirely with [`--setting-sources`](https://code.claude.com/docs/en/cli-reference#cli-flags) or the SDK's `settingSources` option.808* Exclude project settings entirely with [`--setting-sources`](https://code.claude.com/docs/en/cli-reference#cli-flags) or the SDK's `settingSources` option.

809* Start the session with [`--strict-mcp-config`](https://code.claude.com/docs/en/cli-reference#cli-flags). Claude Code then uses only the MCP servers you pass with `--mcp-config`. Skipping the approval prompt for the project-scoped servers Claude Code isn't loading requires Claude Code v2.1.246 or later; before v2.1.246, a strict session still waited on approval for them, which left background sessions waiting at startup. See [Exclusive control with managed-mcp.json](https://code.claude.com/docs/en/managed-mcp.md#exclusive-control-with-managed-mcp-json) for what the flag does under a managed MCP file.809* Start the session with [`--strict-mcp-config`](https://code.claude.com/docs/en/cli-reference#cli-flags). Claude Code then loads the servers you pass with `--mcp-config` and skips the ones configured in places such as `.mcp.json`. Skipping the approval prompt for the project-scoped servers Claude Code isn't loading requires Claude Code v2.1.246 or later. See [Exclusive control with managed-mcp.json](https://code.claude.com/docs/en/managed-mcp.md#exclusive-control-with-managed-mcp-json) for what the flag does under a managed MCP file.

810 810

811[Project server approvals and workspace trust](#project-server-approvals-and-workspace-trust) covers how approvals committed to the repository interact with workspace trust.811[Project server approvals and workspace trust](#project-server-approvals-and-workspace-trust) covers how approvals committed to the repository interact with workspace trust.

812 812

model-config.md +2 −2

Details

273* **`/model`**: Claude Code rejects the switch with an error273* **`/model`**: Claude Code rejects the switch with an error

274* **`--model` flag, `ANTHROPIC_MODEL`, or the `model` setting**: Claude Code replaces the value at startup with a warning naming both the requested and substituted models, and the session starts on the default model274* **`--model` flag, `ANTHROPIC_MODEL`, or the `model` setting**: Claude Code replaces the value at startup with a warning naming both the requested and substituted models, and the session starts on the default model

275* **[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions)**: Claude Code ignores the variable275* **[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions)**: Claude Code ignores the variable

276* **Subagent or teammate override**: Claude Code runs the subagent or teammate on a fallback model rather than failing the request. See [Choose a model](https://code.claude.com/docs/en/sub-agents.md#choose-a-model) for the subagent fallback and [Specify teammates and models](https://code.claude.com/docs/en/agent-teams.md#specify-teammates-and-models) for the teammate fallback.276* **Subagent or teammate override**: Claude Code runs the subagent or teammate on a fallback model rather than failing the request. See [When an allowlist blocks a subagent model](https://code.claude.com/docs/en/sub-agents.md#when-an-allowlist-blocks-a-subagent-model) for the subagent fallback and [Specify teammates and models](https://code.claude.com/docs/en/agent-teams.md#specify-teammates-and-models) for the teammate fallback.

277 277

278 In interactive sessions, Claude Code warns you when it substitutes a subagent's model, by this fallback or by the newest-permitted-version substitution above, naming the requested and substituted models; it doesn't report a teammate's fallback.278 In interactive sessions, Claude Code warns you when it substitutes a top-level subagent's model. It doesn't report a teammate's fallback.

279 279

280 Where the newest-permitted-version substitution above operates, a blocked family alias follows it instead. Before v2.1.222, an alias fell back like any other blocked value on every provider280 Where the newest-permitted-version substitution above operates, a blocked family alias follows it instead. Before v2.1.222, an alias fell back like any other blocked value on every provider

281* **Skill or command override**: Claude Code ignores the override, including a blocked family alias, and the skill or command runs on the session model. A skill or command that [runs in a subagent](https://code.claude.com/docs/en/skills.md#run-skills-in-a-subagent) follows the subagent behavior above instead281* **Skill or command override**: Claude Code ignores the override, including a blocked family alias, and the skill or command runs on the session model. A skill or command that [runs in a subagent](https://code.claude.com/docs/en/skills.md#run-skills-in-a-subagent) follows the subagent behavior above instead

permission-modes.md +1 −1

Details

51| :- | :- | :- | :- |51| :- | :- | :- | :- |

53| Iterate locally with fewer prompts, without a classifier | Manual mode plus the Bash sandbox in [auto-allow mode](https://code.claude.com/docs/en/sandboxing.md#sandbox-modes): `claude --permission-mode default`, then run `/sandbox` and select auto-allow | The built-in Bash sandbox, on macOS, Linux, and WSL2 | Deny rules still apply, and ask rules that name a command, such as `Bash(git push *)`, still prompt. [Auto-allow mode](https://code.claude.com/docs/en/sandboxing.md#auto-allow-mode) covers other commands that can prompt. To turn the sandbox on from a settings file instead, set [`sandbox.enabled`](https://code.claude.com/docs/en/settings-reference#sandbox-enabled) to `true` |53| Iterate locally with fewer prompts, without a classifier | Manual mode plus the Bash sandbox in [auto-allow mode](https://code.claude.com/docs/en/sandboxing.md#sandbox-modes): `claude --permission-mode default`, then run `/sandbox` and select auto-allow | The built-in Bash sandbox, on macOS, Linux, and WSL2 | Deny rules still apply, and ask rules that name a command, such as `Bash(git push *)`, still prompt. [Auto-allow mode](https://code.claude.com/docs/en/sandboxing.md#auto-allow-mode) covers other commands that can prompt. To turn the sandbox on from a settings file instead, set [`sandbox.enabled`](https://code.claude.com/docs/en/settings-reference#sandbox-enabled) and [`sandbox.autoAllowBashIfSandboxed`](https://code.claude.com/docs/en/settings-reference#sandbox-autoallowbashifsandboxed) to `true` |

55| Work hands-off in auto mode | `claude --permission-mode auto`, the [built-in starting permission mode](#which-mode-a-session-starts-in) with v2.1.283 or later | None; a sandbox or container adds defense in depth | Requires a [supported model](#eliminate-prompts-with-auto-mode), and your organization can [turn auto mode off](#eliminate-prompts-with-auto-mode) |55| Work hands-off in auto mode | `claude --permission-mode auto`, the [built-in starting permission mode](#which-mode-a-session-starts-in) with v2.1.283 or later | None; a sandbox or container adds defense in depth | Requires a [supported model](#eliminate-prompts-with-auto-mode), and your organization can [turn auto mode off](#eliminate-prompts-with-auto-mode) |

56| Run in CI with an exact allowlist | `claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"` | None beyond what your CI runner provides | [Cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) ignore `dontAsk` from settings files |56| Run in CI with an exact allowlist | `claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"` | None beyond what your CI runner provides | [Cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) ignore `dontAsk` from settings files |

permissions.md +1 −1

Details

743 743

744Use both for defense-in-depth, since sandbox restrictions still apply even if a prompt injection bypasses Claude's decision-making. Paths and domains from both sandbox settings and permission rules are [merged into the final sandbox configuration](https://code.claude.com/docs/en/sandboxing.md#permission-rules).744Use both for defense-in-depth, since sandbox restrictions still apply even if a prompt injection bypasses Claude's decision-making. Paths and domains from both sandbox settings and permission rules are [merged into the final sandbox configuration](https://code.claude.com/docs/en/sandboxing.md#permission-rules).

745 745

746When you enable sandboxing and leave `autoAllowBashIfSandboxed` at its default of `true`, sandboxed Bash commands run without prompting even if your permissions include a bare `Bash` ask rule, or the [equivalent `Bash(*)` form](#match-all-uses-of-a-tool): the sandbox boundary substitutes for that whole-tool prompt.746When you enable sandboxing and set [`sandbox.autoAllowBashIfSandboxed`](https://code.claude.com/docs/en/settings-reference#sandbox-autoallowbashifsandboxed) to `true`, sandboxed Bash commands run without prompting. That holds even with a bare `Bash` ask rule or the [equivalent `Bash(*)` form](#match-all-uses-of-a-tool): the sandbox boundary substitutes for that whole-tool prompt.

747 747

748In [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode), Claude Code skips this substitution. Without an ask rule, the [built-in read-only commands](#read-only-commands) still run without prompting, and any other shell command goes through the regular permission flow while you are still planning; see [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) for how Claude Code gates commands there. With a bare `Bash` ask rule, every Bash command prompts, including sandboxed read-only commands, the same as outside sandboxing.748In [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode), Claude Code skips this substitution. Without an ask rule, the [built-in read-only commands](#read-only-commands) still run without prompting, and any other shell command goes through the regular permission flow while you are still planning; see [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) for how Claude Code gates commands there. With a bare `Bash` ask rule, every Bash command prompts, including sandboxed read-only commands, the same as outside sandboxing.

749 749

plugins/mods/interface.md +91 −2

Details

438 438

439* **The `backdrop` fields**: `scene` is a [name](https://code.claude.com/docs/en/plugins/mods/reference.md#limits) you choose for a backdrop your hook draws. For the other fields and `overrideColorScheme`, see [the types for your build](https://code.claude.com/docs/en/plugins/mods/create.md#get-the-types-for-your-build).439* **The `backdrop` fields**: `scene` is a [name](https://code.claude.com/docs/en/plugins/mods/reference.md#limits) you choose for a backdrop your hook draws. For the other fields and `overrideColorScheme`, see [the types for your build](https://code.claude.com/docs/en/plugins/mods/create.md#get-the-types-for-your-build).

440* **Whether the backdrop is drawn**: `$.theme.set` resolves with `isDrawn: true` when a Desktop or mobile app connected to the session says it draws backdrops. Otherwise `isDrawn` is `false` and `reason` says why.440* **Whether the backdrop is drawn**: `$.theme.set` resolves with `isDrawn: true` when a Desktop or mobile app connected to the session says it draws backdrops. Otherwise `isDrawn` is `false` and `reason` says why.

441* **One backdrop for each session**: a `$.theme.set` call replaces the session's backdrop and `$.theme.clear()` removes that backdrop, whichever mod set it. Call `$.theme.clear()` only when the user asks for it.441* **One theme for each session**: a mod that calls `$.theme.set` replaces the session's backdrop and [colors](#change-the-colors-of-the-desktop-app), and a mod that calls `$.theme.clear()` removes them, whichever mod set them. Call `$.theme.clear()` only when the user asks for it.

442

443### Change the colors of the Desktop app

444

445To change the colors of the Desktop app's Code tab with a mod, [ask Claude for one](#ask-claude-for-a-colors-mod) or [write one yourself](#write-a-colors-mod-yourself). Both ways require Claude Code v2.1.324 or later in the Code tab, so [check the version there](https://code.claude.com/docs/en/desktop.md#claude-code-version-in-the-code-tab) first. Claude Code in the terminal keeps its own colors.

446

447#### Ask Claude for a colors mod

448

449**1. Describe the colors**

450

451Start a local session in the Code tab and tell Claude which colors you want. For example, enter `make a mod that makes the app cream in light mode and dark brown in dark mode`. Claude writes the mod's files.

452

453**2. Approve the mod**

454

455Answer the questions Claude Code asks about the mod's files and hot reloading. For what each answer does, see [Ask Claude for a mod](https://code.claude.com/docs/en/plugins/mods/create.md#ask-claude-for-a-mod).

456

457**3. Check the colors**

458

459The Code tab changes color when the mod loads. To adjust a color, tell Claude what to change. If nothing changes, see [Fix missing mod colors](#fix-missing-mod-colors-in-the-desktop-app).

460

461#### Write a colors mod yourself

462

463`makeColors` is a function that builds a theme from a few hex colors. These steps create a mod named `paper` that uses it.

464

465**1. Have Claude copy makeColors**

466

467Start a local session in the Code tab, and enter `copy make-colors.js and make-colors.d.ts from your plugin-authoring skill into ~/.claude/skills/paper/hooks/`. Check that both files are in that directory.

468

469**2. Save the manifest and hooks.json**

470

471From [Write a mod yourself](https://code.claude.com/docs/en/plugins/mods/create.md#write-a-mod-yourself), save `.claude-plugin/plugin.json` and `hooks/hooks.json` in `~/.claude/skills/paper/`, and change `first-mod` to `paper` in both files. A mod [under `~/.claude/skills/`](https://code.claude.com/docs/en/plugins/create#scaffold-a-plugin-that-loads-every-session) loads when you start a session.

472

473**3. Write the code**

474

475Save this file as `~/.claude/skills/paper/hooks/register.js`. When a session starts, the code calls `$.theme.set` with the colors for light mode and dark mode:

476

477```javascript theme={null}

478import { makeColors } from './make-colors.js'

479

480const { theme } = makeColors({

481 label: 'Paper',

482 // surface-0 is the background, text-primary is the main text, and text-muted is the faint text

483 light: {

484 gray: { anchors: { 'surface-0': '#efe6d3', 'text-primary': '#2a241d', 'text-muted': '#6a5f50' } },

485 },

486 dark: {

487 gray: { anchors: { 'surface-0': '#1f1a15', 'text-primary': '#f0e7d7', 'text-muted': '#aca08d' } },

488 },

489})

490

491export function register(on) {

492 on('session.start', async ($, e, next) => {

493 await $.theme.set({ colors: theme })

494 return next(e)

495 })

496}

497```

498

499To use your own colors, replace the hex values with other six-digit hex colors.

500

501**4. Check the colors**

502

503Start a new local session in the Code tab. With the example's values, the background is cream in light mode and dark brown in dark mode. If nothing changes, see [Fix missing mod colors](#fix-missing-mod-colors-in-the-desktop-app).

504

505### Fix missing mod colors in the Desktop app

506

507If you use a [third-party provider](https://code.claude.com/docs/en/third-party-integrations.md) instead of a Claude account in [Claude Desktop v5.11492.5 or earlier](https://code.claude.com/docs/en/desktop.md#check-your-version), the Code tab keeps its own colors, so skip these checks. Otherwise, if a mod's colors don't appear in the Code tab, or if they disappear, check for these causes:

508

509* **Old version**: [update the Desktop app](https://code.claude.com/docs/en/desktop.md#claude-code-version-in-the-code-tab), restart it, and start a new local session in the Code tab. If Claude wrote the mod, ask for it again there.

510* **Mod not loaded**: if Claude wrote the mod, see when it loads in [Ask Claude for a mod](https://code.claude.com/docs/en/plugins/mods/create.md#ask-claude-for-a-mod). If you wrote it, compare your files and their paths with [Write a colors mod yourself](#write-a-colors-mod-yourself).

511* **Refused theme**: ask Claude to run the mod's [`makeColors`](#write-a-colors-mod-yourself) call. If the call throws an error, or its `problems` list has an entry that starts `Desktop won't paint this theme`, have Claude fix the theme. If you installed the mod, send what Claude finds to its author.

512* **Another `$.theme` call**: when any mod in the session calls `$.theme.set` or `$.theme.clear()`, the colors and [backdrop](#put-a-backdrop-behind-the-conversation) from an earlier call disappear. In your own mod, pass `colors` and `backdrop` in the same `$.theme.set` call. Use one mod at a time that sets a theme.

513

514### Remove mod colors from the Desktop app

515

516To take a mod's colors off the Code tab, turn off the mod first. A mod that's still on can set its colors again.

517

518**1. Turn off the mod**

519

520* **Claude wrote the mod**: move its directory out of the [mods folder](https://code.claude.com/docs/en/plugins/mods/create.md#ask-claude-for-a-mod) of the session where Claude wrote it.

521* **You put the mod under `~/.claude/skills/`**: move its directory, such as `~/.claude/skills/paper/`, to a place outside `~/.claude/skills/`.

522* **You installed the mod**: in the Desktop app, [disable or uninstall its plugin](https://code.claude.com/docs/en/desktop.md#install-plugins) from **Manage plugins**. If you don't see **Manage plugins** and you have [the CLI](https://code.claude.com/docs/en/quickstart.md), you can [disable or uninstall a marketplace plugin from your shell](https://code.claude.com/docs/en/plugins/install.md#manage-plugins-from-your-shell).

523

524**2. Start a new session**

525

526Start a new local session in the Code tab.

527

528**3. Remove colors that stay**

529

530If the colors are still there, open **Settings** from the Code tab, and search there for `code appearance`. Open the result, and select **Remove colors**.

442 531

443## Build a tree from elements532## Build a tree from elements

444 533

677 766

678The same keys, or in fullscreen rendering a click on the row, expand the band again. Until then, nothing presses a button in it: no hotkey, no digit typed into an empty prompt, and no keybinding for a button's [`action`](https://code.claude.com/docs/en/plugins/mods/reference#elements). If the band has keyboard focus when the user collapses it, the focus returns to the prompt, and Ctrl+X then Tab skips the band while it's collapsed.767The same keys, or in fullscreen rendering a click on the row, expand the band again. Until then, nothing presses a button in it: no hotkey, no digit typed into an empty prompt, and no keybinding for a button's [`action`](https://code.claude.com/docs/en/plugins/mods/reference#elements). If the band has keyboard focus when the user collapses it, the focus returns to the prompt, and Ctrl+X then Tab skips the band while it's collapsed.

679 768

680The band stays collapsed until the user expands it, even after `/clear`, and is expanded again the next time Claude Code starts. Your mod can't expand it or tell that it's collapsed: the `ui.render` hook keeps running, and nothing in `e.props` says so. Don't make the band the only place your mod shows something the user has to answer.769The band stays collapsed until the user expands it, even after `/clear`, and is expanded again the next time Claude Code starts. Your mod can't expand it. Don't make the band the only place your mod shows something the user has to answer. To show that elsewhere only while the band is collapsed, read `e.props.isCollapsed` in your `ui.render` hook, which keeps running. `isCollapsed` requires Claude Code v2.1.321 or later.

681 770

682### Take typed input and draw a row for each item771### Take typed input and draw a row for each item

683 772

plugins/mods/reference.md +15 −2

Details

212 212

213Some of these events also fire for Claude Code's own actions, so check whether `next.origin.plugin` is `engine` before you refuse one.213Some of these events also fire for Claude Code's own actions, so check whether `next.origin.plugin` is `engine` before you refuse one.

214 214

215#### Fields on Claude Code's own `http.fetch` requests

216

217In an `http.fetch` hook, a [`next.origin`](#the-hook-function) of `{ plugin: 'engine', tier: 'core' }` marks one of Claude Code's own requests, such as a model request, not a mod's `$.http.fetch` call. Where the [built-in guard](https://code.claude.com/docs/en/plugins/mods/admin.md#know-what-happens-by-default) is loaded, your hook doesn't get these events unless your mod [counts as your organization's](https://code.claude.com/docs/en/plugins/mods/admin.md#install-your-organizations-mods).

218

219On these events, `e.init` and the `value` that `next(e)` resolves to can hold these fields, among others:

220

221| Field | What it means |

222| :- | :- |

223| `e.init.compress` | Set when Claude Code compresses the body after your hook. `e.init.body` holds the uncompressed body. To send the body uncompressed, call `next({ ...e, init: { ...e.init, compress: undefined } })`. |

224| `value.isStreaming` | Set to `true` because Claude Code reads the response body itself, so `value.text` is empty. Read `value.status` and `value.headers` instead. To answer with your own `text`, return a `value` without `isStreaming`. |

225

226These events and fields require Claude Code v2.1.321 or later.

227

215## Mods API methods228## Mods API methods

216 229

217The mods API is the `$` argument every hook receives. Its methods are grouped in namespaces, such as `$.ui`. This table lists each namespace's methods by name, so `open` in the `$.ui` row is the call `$.ui.open(...)`. The guides show the common ones in use, and [the types for your build](https://code.claude.com/docs/en/plugins/mods/create.md#get-the-types-for-your-build) document every method with an example.230The mods API is the `$` argument every hook receives. Its methods are grouped in namespaces, such as `$.ui`. This table lists each namespace's methods by name, so `open` in the `$.ui` row is the call `$.ui.open(...)`. The guides show the common ones in use, and [the types for your build](https://code.claude.com/docs/en/plugins/mods/create.md#get-the-types-for-your-build) document every method with an example.

222| [`$.ui`](https://code.claude.com/docs/en/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, [`place`](https://code.claude.com/docs/en/plugins/mods/interface#place-a-row-in-the-transcript), `focus`, `scroll`, `toast`, `notify`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit`, `view`. `view` requires Claude Code v2.1.300 or later and `place` v2.1.314 or later. |235| [`$.ui`](https://code.claude.com/docs/en/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, [`place`](https://code.claude.com/docs/en/plugins/mods/interface#place-a-row-in-the-transcript), `focus`, `scroll`, `toast`, `notify`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit`, `view`. `view` requires Claude Code v2.1.300 or later and `place` v2.1.314 or later. |

223| [`$.theme`](https://code.claude.com/docs/en/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `set`, `clear`: set a backdrop for the Desktop or mobile app to draw, and take the backdrop off. Requires Claude Code v2.1.319 or later. |236| [`$.theme`](https://code.claude.com/docs/en/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `set`, `clear`: set a backdrop for the Desktop or mobile app to draw, and take the backdrop off. Requires Claude Code v2.1.319 or later. |

225| [`$.tool`](https://code.claude.com/docs/en/plugins/mods/api#add-a-tool) | `register`, `call`, `check`, `list` |238| [`$.tool`](https://code.claude.com/docs/en/plugins/mods/api#add-a-tool) | `register`, `call`, `check`, `list`. When a `call` needs a person's approval, such as one a hook or your organization answers with `ask`, it resolves with `{ deny: "<tool> wasn't run: this call needs a person's approval, and a mod's own call can't ask for it." }`, where `<tool>` is the tool's name. |

226| `$.agent` | `register`, `spawn`, `list`. `list()` returns this session's subagents and teammates, each with a `status` of `pending`, `running`, `waiting`, `idle`, `completed`, `failed`, or `killed`, where `idle` and `waiting` require Claude Code v2.1.289 or later. |239| `$.agent` | `register`, `spawn`, `list`. `list()` returns this session's subagents and teammates, each with a `status` of `pending`, `running`, `waiting`, `idle`, `completed`, `failed`, or `killed`, where `idle` and `waiting` require Claude Code v2.1.289 or later. |

228| [`$.prompt`](https://code.claude.com/docs/en/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`, `read`, `fill`, `suggest`, `compose`. Claude reads text from `submit({ text })` after a sentence that names your mod as the sender. `submit({ text, asUser: true })` sends the text as the user's own words, without that sentence. |241| [`$.prompt`](https://code.claude.com/docs/en/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`, `read`, `fill`, `suggest`, `compose`. Claude reads text from `submit({ text })` after a sentence that names your mod as the sender. `submit({ text, asUser: true })` sends the text as the user's own words, without that sentence. |

251| :- | :- | :- | :- |264| :- | :- | :- | :- |

253| [`AbovePrompt`](https://code.claude.com/docs/en/plugins/mods/interface#pick-where-to-draw) | `hasSurvey`, `isWorking`, `maxRows`, `bodyColumns`, `scroll`, `view` | One instance | Terminal, Desktop |266| [`AbovePrompt`](https://code.claude.com/docs/en/plugins/mods/interface#pick-where-to-draw) | `hasSurvey`, [`isCollapsed`](https://code.claude.com/docs/en/plugins/mods/interface#when-the-user-collapses-the-band), `isWorking`, `maxRows`, `bodyColumns`, `scroll`, `view` | One instance | Terminal, Desktop |

254| `AbovePromptList`, the stack of `AbovePrompt` rows | `rows`, a list with one `{ plugin, tree }` for each mod's row, plus the `AbovePrompt` props | One instance | Terminal, Desktop. Requires Claude Code v2.1.323 or later. |267| `AbovePromptList`, the stack of `AbovePrompt` rows | `rows`, a list with one `{ plugin, tree }` for each mod's row, plus the `AbovePrompt` props | One instance | Terminal, Desktop. Requires Claude Code v2.1.323 or later. |

256| [`Backdrop`](https://code.claude.com/docs/en/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `scene`, `plugin`, `glass`, `overrideColorScheme`. Before v2.1.323, `scene` was `id` and `overrideColorScheme` was `colorScheme`. | `backdrop` | `desktop` and `mobile` surfaces. Your hook runs when the Desktop or mobile app asks to draw a backdrop. |269| [`Backdrop`](https://code.claude.com/docs/en/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `scene`, `plugin`, `glass`, `overrideColorScheme`. Before v2.1.323, `scene` was `id` and `overrideColorScheme` was `colorScheme`. | `backdrop` | `desktop` and `mobile` surfaces. Your hook runs when the Desktop or mobile app asks to draw a backdrop. |

plugins/mods/test.md +3 −4

Details

115 115

116### Follow the test kit's rules116### Follow the test kit's rules

117 117

118The test kit has a few rules of its own, and breaking one produces the errors new test authors hit first:

~~119~~

120* **Register every stub before the test's first call on `$`.** Calling `on` after that throws an error such as `on("ui.render") after the test first called $`.118* **Register every stub before the test's first call on `$`.** Calling `on` after that throws an error such as `on("ui.render") after the test first called $`.

121 119

122* **[`session.start`](https://code.claude.com/docs/en/plugins/mods/reference#session) doesn't run by itself.** Each test starts with your module freshly loaded and none of its hooks called, so module-level variables hold their initial values. If a hook depends on what `session.start` sets up, fire it first:120* **[`session.start`](https://code.claude.com/docs/en/plugins/mods/reference#session) doesn't run by itself.** Each test starts with your module freshly loaded and none of its hooks called, so module-level variables hold their initial values. If a hook depends on what `session.start` sets up, fire it first:

132 130

133 The second stub answers the `$.command.register` call that a `session.start` hook such as the [tutorial's](https://code.claude.com/docs/en/plugins/mods/create.md#write-a-mod-yourself) makes. Without it, that call rejects with `no implementation for command.register` and the kit skips your hook, so nothing after the call in the hook runs. The test doesn't fail at that point. The skipped hook is listed under `the engine reported:` only if a later check fails.131 The second stub answers the `$.command.register` call that a `session.start` hook such as the [tutorial's](https://code.claude.com/docs/en/plugins/mods/create.md#write-a-mod-yourself) makes. Without it, that call rejects with `no implementation for command.register` and the kit skips your hook, so nothing after the call in the hook runs. The test doesn't fail at that point. The skipped hook is listed under `the engine reported:` only if a later check fails.

134 132

135* **A hook that returns `next(e)` needs a stub to answer.** When your [`ui.render`](https://code.claude.com/docs/en/plugins/mods/reference#interface) hook returns `next(e)`, for example to draw nothing while Claude is idle, [mounting it](#test-a-drawing) fails with `no implementation for ui.render`. Register a stub that returns an element as plain data:133* **Register a `ui.render` stub to choose what `next(e)` returns.** When your [`ui.render`](https://code.claude.com/docs/en/plugins/mods/reference#interface) hook returns `next(e)`, for example to draw nothing while Claude is idle, the [mount](#test-a-drawing) succeeds with no stub. To make `next(e)` return an element you pick, register a stub that returns it as plain data:

136 134

137 ```typescript theme={null}135 ```typescript theme={null}

138 // Stands for what Claude Code would draw at the site136 // Stands for what Claude Code would draw at the site

139 on('ui.render', () => ({ type: 'Text', props: {}, children: ['drawn by Claude Code'] }))137 on('ui.render', () => ({ type: 'Text', props: {}, children: ['drawn by Claude Code'] }))

140 ```138 ```

141 139

142 With the stub registered, the mount succeeds, and `ui.find({ type: 'Text' })` returns that element whenever your hook returned `next(e)`. On v2.1.323 or later, for the band, pass your mod's name as the second argument to `on`, as in `{ plugin: 'my-mod' }`. Without it, the stub doesn't answer your `next(e)`.140 Where the site [can draw that element](https://code.claude.com/docs/en/plugins/mods/interface.md#change-what-claude-code-already-draws), `ui.find({ type: 'Text' })` returns it when your hook returned `next(e)`. On v2.1.323 or later, for the band, pass your mod's name as the second argument to `on`, as in `{ plugin: 'my-mod' }`. Without it, the stub doesn't answer your `next(e)`. Before v2.1.321, the mount fails with `no implementation for ui.render` unless you register the stub.

143 141

144* **A stub for `turn.step` is an async generator**, and the test reads the stream to its end to get the result:142* **A stub for `turn.step` is an async generator**, and the test reads the stream to its end to get the result:

145 143

316| `press({ key: 'more' })` | Presses the `Button` with that key |314| `press({ key: 'more' })` | Presses the `Button` with that key |

317| `input({ key: 'new-note', text: 'buy milk' })` | Types the text into the `Input` with that key and presses Enter. Add `kind: 'change'` to type without submitting. For a field with `rows`, the text can hold `\n`. |315| `input({ key: 'new-note', text: 'buy milk' })` | Types the text into the `Input` with that key and presses Enter. Add `kind: 'change'` to type without submitting. For a field with `rows`, the text can hold `\n`. |

318| `select({ key: 'size', value: 'large' })` | Picks the option with that value in the `Select` with that key |316| `select({ key: 'size', value: 'large' })` | Picks the option with that value in the `Select` with that key |

317| `keepsBeneath()` | In a test with no `ui.render` stub, it resolves to `true` when the drawing includes what `next(e)` returned, and `false` when your hook left it out. In a test that registers one, use `find` to look for what the stub drew. Requires Claude Code v2.1.321 or later. |

319| `find({ key: 'more' })` or `find({ type: 'Text', text: 'Count: 2' })` | Returns the first matching element as `{ type, props, children }`, or `undefined`. `text` can be a string or a regular expression. |318| `find({ key: 'more' })` or `find({ type: 'Text', text: 'Count: 2' })` | Returns the first matching element as `{ type, props, children }`, or `undefined`. `text` can be a string or a regular expression. |

321 320

sandbox-environments.md +1 −1

Details

41 41

42| You want to | Start with |42| You want to | Start with |

43| :- | :- |43| :- | :- |

~~44| Reduce permission prompts during everyday work on your own machine | The [sandboxed Bash tool](https://code.claude.com/docs/en/sandboxing.md), configured with `/sandbox` |~~44| Reduce permission prompts during everyday work on your own machine | The [sandboxed Bash tool](https://code.claude.com/docs/en/sandboxing.md) in auto-allow mode, configured with `/sandbox` |

45| Let Claude work unattended with `--dangerously-skip-permissions` or auto mode | The preconfigured [dev container](https://code.claude.com/docs/en/devcontainer.md), any container or VM, or the [sandbox runtime](#sandbox-runtime) |45| Let Claude work unattended with `--dangerously-skip-permissions` or auto mode | The preconfigured [dev container](https://code.claude.com/docs/en/devcontainer.md), any container or VM, or the [sandbox runtime](#sandbox-runtime) |

46| Isolate MCP servers and hooks as well as Bash, without Docker | The sandbox runtime |46| Isolate MCP servers and hooks as well as Bash, without Docker | The sandbox runtime |

47| Standardize a sandboxed environment across a team | The preconfigured [dev container](https://code.claude.com/docs/en/devcontainer.md), copied into your repository |47| Standardize a sandboxed environment across a team | The preconfigured [dev container](https://code.claude.com/docs/en/devcontainer.md), copied into your repository |

sandboxing.md +4 −7

Details

6 6

7> Restrict the files and network hosts Claude Code's shell commands can reach with the built-in sandbox. Turn it on, set the boundary, and fix what it breaks.7> Restrict the files and network hosts Claude Code's shell commands can reach with the built-in sandbox. Turn it on, set the boundary, and fix what it breaks.

8 8

9The Bash sandbox is a boundary that the operating system enforces around the shell commands Claude runs on your machine. You set which files and network domains those commands can reach, and the limits apply to Bash, PowerShell, and Monitor commands and the processes they start. Because the operating system applies the limits while a command runs, Claude Code can [run sandboxed commands without asking you](#sandbox-modes) to approve each one.9The Bash sandbox is a boundary that the operating system enforces around the shell commands Claude runs on your machine. You set which files and network domains those commands can reach, and the limits apply to Bash, PowerShell, and Monitor commands and the processes they start. Sandboxed commands still go through the regular permission flow unless you choose [auto-allow mode](#sandbox-modes), which can run them without asking you.

10 10

11The sandbox covers shell commands only. Claude's file tools, MCP servers, and hooks [run outside it](#what-runs-outside-the-sandbox).11The sandbox covers shell commands only. Claude's file tools, MCP servers, and hooks [run outside it](#what-runs-outside-the-sandbox).

12 12

394| `credentials.envVars` `deny` and `mask` entries | Enforced. Environment variable scrubbing is independent of the filesystem layer |394| `credentials.envVars` `deny` and `mask` entries | Enforced. Environment variable scrubbing is independent of the filesystem layer |

395| [`credentials.files` `mask` entries](#mask-credential-files) applied as masks | Enforced: masking is independent of the filesystem layer. An entry that [fell back to `deny`](#mask-credential-files) is not enforced, like any `deny` entry |395| [`credentials.files` `mask` entries](#mask-credential-files) applied as masks | Enforced: masking is independent of the filesystem layer. An entry that [fell back to `deny`](#mask-credential-files) is not enforced, like any `deny` entry |

396 396

397Two other things change:397Sandboxed commands also inherit your shell's `$TMPDIR` instead of the per-user temp directory, because every temp directory is writable and Claude Code no longer redirects commands to the per-user one.

398 398

399* Sandboxed commands inherit your shell's `$TMPDIR` instead of the per-user temp directory, because every temp directory is writable and Claude Code no longer redirects commands to the per-user one.399On Linux the variable is often unset in the parent shell. The Bash tool guidance tells Claude to create scratch directories with `mktemp -d` instead of relying on `$TMPDIR`.

~~400~~

401 On Linux the variable is often unset in the parent shell. The Bash tool guidance tells Claude to create scratch directories with `mktemp -d` instead of relying on `$TMPDIR`.

402* [`autoAllowBashIfSandboxed`](https://code.claude.com/docs/en/settings-reference#sandbox-autoallowbashifsandboxed) still defaults to `true`, so sandboxed commands keep running without prompts. Set it to `false` to prompt for sandboxed commands.

403 400

404### Protect credentials401### Protect credentials

405 402

1095}1092}

1096```1093```

1097 1094

1098This turns on [auto-allow mode](#sandbox-modes). For regular permissions mode, also set [`sandbox.autoAllowBashIfSandboxed`](https://code.claude.com/docs/en/settings-reference#sandbox-autoallowbashifsandboxed) to `false`. The change takes effect in your running session at the next shell command Claude runs, and the **Mode** tab of `/sandbox` then marks the mode in effect.1095This turns on [regular permissions mode](#sandbox-modes). For auto-allow mode, also set [`sandbox.autoAllowBashIfSandboxed`](https://code.claude.com/docs/en/settings-reference#sandbox-autoallowbashifsandboxed) to `true`. The change takes effect in your running session at the next shell command Claude runs, and the **Mode** tab of `/sandbox` then marks the mode in effect.

1099 1096

1100## Limitations1097## Limitations

1101 1098

security.md +2 −2

Details

25 25

26To mitigate risks in agentic systems:26To mitigate risks in agentic systems:

27 27

28* **Sandboxed bash tool**: [Sandbox](https://code.claude.com/docs/en/sandboxing.md) bash commands with filesystem and network isolation, reducing permission prompts while maintaining security. Configure with `/sandbox` to define boundaries where Claude Code can work autonomously28* **Sandboxed Bash tool**: [Sandbox](https://code.claude.com/docs/en/sandboxing.md) Bash commands with filesystem and network isolation. Configure with `/sandbox`

29* **Working directory boundary**: In Manual mode, Claude Code asks you before its file tools read or write outside the folder where it was started and its subfolders. The boundary is a permission prompt, so a Bash command you approve can still write anywhere your user account can29* **Working directory boundary**: In Manual mode, Claude Code asks you before its file tools read or write outside the folder where it was started and its subfolders. The boundary is a permission prompt, so a Bash command you approve can still write anywhere your user account can

30 * To read a folder without the prompt, add it as an [additional directory](https://code.claude.com/docs/en/permissions.md#working-directories)30 * To read a folder without the prompt, add it as an [additional directory](https://code.claude.com/docs/en/permissions.md#working-directories)

31 * To restrict Bash commands at the operating system level, turn on [sandboxing](https://code.claude.com/docs/en/sandboxing.md#filesystem-isolation)31 * To restrict Bash commands at the operating system level, turn on [sandboxing](https://code.claude.com/docs/en/sandboxing.md#filesystem-isolation)

62* **Trust verification**: In an interactive session, Claude Code shows the workspace trust dialog when you start it in a folder you haven't trusted. Servers in a project's `.mcp.json` have their own approval prompt, and [Project scope](https://code.claude.com/docs/en/mcp.md#project-scope) lists the sessions that skip it62* **Trust verification**: In an interactive session, Claude Code shows the workspace trust dialog when you start it in a folder you haven't trusted. Servers in a project's `.mcp.json` have their own approval prompt, and [Project scope](https://code.claude.com/docs/en/mcp.md#project-scope) lists the sessions that skip it

63 * Note: A `-p` session shows neither prompt. [What runs before you trust a folder](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder) lists what a repository's files can run there63 * Note: A `-p` session shows neither prompt. [What runs before you trust a folder](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder) lists what a repository's files can run there

64 * Note: When you start Claude Code directly in your home directory, trust acceptance is held for the current session only and is not written to disk, so the prompt reappears on each launch. There is no setting to persist it. Start Claude Code from a project subdirectory instead, where trust acceptance is saved per directory64 * Note: When you start Claude Code directly in your home directory, trust acceptance is held for the current session only and is not written to disk, so the prompt reappears on each launch. There is no setting to persist it. Start Claude Code from a project subdirectory instead, where trust acceptance is saved per directory

65* **Command injection detection**: In Manual mode, Claude Code asks before running a Bash command it can't fully analyze. An allow rule for part of a command, such as `Bash(git *)`, doesn't skip that prompt. [Sandboxed commands](https://code.claude.com/docs/en/permissions.md#how-permissions-interact-with-sandboxing) can run without it65* **Command injection detection**: In Manual mode, Claude Code asks before running a Bash command it can't fully analyze. An allow rule for part of a command, such as `Bash(git *)`, doesn't skip that prompt. [Sandboxed commands](https://code.claude.com/docs/en/permissions.md#how-permissions-interact-with-sandboxing) in [auto-allow mode](https://code.claude.com/docs/en/sandboxing.md#auto-allow-mode) can run without it

66* **Fail-closed matching**: In Manual mode, unmatched commands require approval by default66* **Fail-closed matching**: In Manual mode, unmatched commands require approval by default

67* **Secure credential storage**: API keys and tokens are stored in the macOS Keychain when available. On Linux they're stored in a file with mode `0600`, and on Windows in a file that inherits the access controls of your user profile directory. See [Credential Management](https://code.claude.com/docs/en/authentication.md#credential-management)67* **Secure credential storage**: API keys and tokens are stored in the macOS Keychain when available. On Linux they're stored in a file with mode `0600`, and on Windows in a file that inherits the access controls of your user profile directory. See [Credential Management](https://code.claude.com/docs/en/authentication.md#credential-management)

68 68

settings-reference.md +10 −10

Details

1355 1355

1356### `sandbox.autoAllowBashIfSandboxed`1356### `sandbox.autoAllowBashIfSandboxed`

1357 1357

1358Let Claude Code run sandboxed Bash commands without a permission prompt. Commands that can't run in the sandbox still go through the regular permission flow, and `deny` rules and content-scoped `ask` rules such as `Bash(git push *)` still apply; a bare `Bash` ask rule is skipped for sandboxed commands. Set it to `false` to send sandboxed commands through the regular permission flow too, which the `/sandbox` **Mode** tab calls regular permissions mode.1358Let Claude Code run sandboxed Bash commands without a permission prompt. Commands that can't run in the sandbox still go through the regular permission flow. `deny` rules and content-scoped `ask` rules such as `Bash(git push *)` still apply, but a bare `Bash` ask rule is skipped for sandboxed commands. To set it to `true` in managed settings, add it to the `sandbox` block of your [highest-ranked managed source](https://code.claude.com/docs/en/managed-settings.md#how-claude-code-combines-managed-sources).

1359 1359

1360* **Scope**: [`Any file`](#scopes)1360* **Scope**: [`Any file`](#scopes)

1361* **Type**: Boolean1361* **Type**: Boolean

1362 * `true`: Claude Code runs sandboxed Bash commands without a permission prompt, except in the cases that [Auto-allow mode](https://code.claude.com/docs/en/sandboxing.md#auto-allow-mode) describes; `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` turns auto-allow off1362 * `true`: Claude Code runs sandboxed Bash commands without a permission prompt, except in the cases that [Auto-allow mode](https://code.claude.com/docs/en/sandboxing.md#auto-allow-mode) describes; `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` turns auto-allow off

1363 * `false`: sandboxed commands go through the regular permission flow, so your allow rules and permission mode decide. The `/sandbox` **Mode** tab calls this regular permissions mode1363 * `false`: sandboxed commands go through the regular permission flow, so your allow rules and permission mode decide. The `/sandbox` **Mode** tab calls this regular permissions mode

1364* **Default**: `true`1364* **Default**: `false`. Before v2.1.324, the default was `true`

1365 1365

1366This keeps the sandbox on and sends sandboxed commands through the regular permission flow:1366To keep the sandbox on and run sandboxed commands without a permission prompt, set both keys in your `sandbox` block:

1367 1367

1368```json settings.json theme={null}1368```json settings.json theme={null}

1369{1369{

1370 "sandbox": {1370 "sandbox": {

1371 "enabled": true,1371 "enabled": true,

1372 "autoAllowBashIfSandboxed": false1372 "autoAllowBashIfSandboxed": true

1373 }1373 }

1374}1374}

1375```1375```

1653}1653}

1654```1654```

1655 1655

1656With the layer off, Claude Code doesn't enforce `denyRead` or `credentials.files` `deny` entries, while `credentials.envVars` entries and applied `mask` entries keep working. [`autoAllowBashIfSandboxed`](#sandbox-autoallowbashifsandboxed) still defaults to `true`, so set it to `false` to keep prompting. See [Disable filesystem isolation](https://code.claude.com/docs/en/sandboxing.md#disable-filesystem-isolation) for the full list of sources that can set it and what changes when isolation is off.1656With the layer off, Claude Code doesn't enforce `denyRead` or `credentials.files` `deny` entries, while `credentials.envVars` entries and applied `mask` entries keep working. See [Disable filesystem isolation](https://code.claude.com/docs/en/sandboxing.md#disable-filesystem-isolation) for the full list of sources that can set it and what changes when isolation is off.

1657 1657

1658### `sandbox.ignoreViolations`1658### `sandbox.ignoreViolations`

1659 1659

5421 5421

5422### `minimumVersion`5422### `minimumVersion`

5423 5423

5424Keep background auto-updates and `claude update` from installing any version below this one, so moving to the `"stable"` channel doesn't downgrade you from a newer `"latest"` build. Claude Code writes this key for you when you choose to stay on your current version while switching channels in `/config`, and clears it when you switch back to `"latest"`.5424Keep background auto-updates and `claude update` from installing any version below the one you set. Claude Code writes this key for you when you choose to stay on your current version while switching channels in `/config`. Claude Code clears the key when you switch back to `"latest"` in `/config`.

5425 5425

5426* **Scope**: [`Any file`](#scopes). Set it in managed settings to pin an organization-wide minimum that user and project settings can't lower.5426* **Scope**: [`Any file`](#scopes). Set this key in managed settings to pin an organization-wide minimum that user and project settings can't override.

5427* **Type**: string, a version number such as `"2.1.100"`; a value that isn't a valid version is ignored5427* **Type**: string, a version number such as `"2.1.323"`; a value that isn't a valid version is ignored

5428* **Default**: unset, so updates can install any version the channel offers5428* **Default**: unset, so updates can install any version the channel offers

5429 5429

5430This example follows the stable channel and refuses to install any version below 2.1.100:5430This example follows the stable channel and refuses to install any version below 2.1.323:

5431 5431

5432```json settings.json theme={null}5432```json settings.json theme={null}

5433{5433{

5434 "autoUpdatesChannel": "stable",5434 "autoUpdatesChannel": "stable",

5435 "minimumVersion": "2.1.100"5435 "minimumVersion": "2.1.323"

5436}5436}

5437```5437```

5438 5438

setup.md +19 −10

Details

40>40>

41> **macOS, Linux, WSL:**41> **macOS, Linux, WSL:**

42>42>

~~43> ```bash theme={null}~~43> ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

44> curl -fsSL https://claude.ai/install.sh | bash44> curl -fsSL https://claude.ai/install.sh | bash

45> ```45> ```

46>46>

48>48>

49> **Windows PowerShell:**49> **Windows PowerShell:**

50>50>

~~51> ```powershell theme={null}~~51> ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

52> irm https://claude.ai/install.ps1 | iex52> irm https://claude.ai/install.ps1 | iex

53> ```53> ```

54>54>

55> **Windows CMD:**55> **Windows CMD:**

56>56>

~~57> ```batch theme={null}~~57> ```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

58> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd58> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

59> ```59> ```

60>60>

72 72

73> [tab] Homebrew73> [tab] Homebrew

74>74>

~~75> ```bash theme={null}~~75> ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

76> brew install --cask claude-code76> brew install --cask claude-code

77> ```77> ```

78>78>

84 84

85> [tab] WinGet85> [tab] WinGet

86>86>

~~87> ```powershell theme={null}~~87> ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

88> winget install Anthropic.ClaudeCode88> winget install Anthropic.ClaudeCode

89> ```89> ```

90>90>

220}220}

221```221```

222 222

223With this setting, a native installation updates to the stable version even when that version is older than yours. To avoid the downgrade, also [pin a minimum version](#pin-a-minimum-version).

224

223A newly launched model can require a Claude Code version newer than the stable channel serves. To run the model now, move to the latest channel.225A newly launched model can require a Claude Code version newer than the stable channel serves. To run the model now, move to the latest channel.

224 226

225For enterprise deployments, you can enforce a consistent release channel across your organization using [managed settings](https://code.claude.com/docs/en/managed-settings.md).227For enterprise deployments, you can enforce a consistent release channel across your organization using [managed settings](https://code.claude.com/docs/en/managed-settings.md).

230 232

231### Pin a minimum version233### Pin a minimum version

232 234

233The `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.235To move a native installation to the `"stable"` [release channel](#configure-release-channel) without a downgrade, set [`minimumVersion`](https://code.claude.com/docs/en/settings-reference#minimumversion) to the version you're running. Background auto-updates and `claude update` refuse to install any version below the minimum.

236

237Set the minimum in `/config` to have Claude Code fill in your current version, or in your settings file to type the number yourself:

234 238

235Switching 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.239* **In `/config`**: switch **Auto-update channel** to stable, then select **Stay on current version**. If you switch back to latest in `/config`, Claude Code clears the minimum.

240* **In your [settings file](https://code.claude.com/docs/en/settings.md)**: run `claude --version` in your shell, and set `minimumVersion` to the number at the start of the output. In the same edit, set `autoUpdatesChannel` to `"stable"`.

236 241

237Add it to your [settings.json file](https://code.claude.com/docs/en/settings.md) to pin a floor explicitly:242This `~/.claude/settings.json` switches an installation on version 2.1.323 to stable:

238 243

239```json theme={null}244```json theme={null}

240{245{

241 "autoUpdatesChannel": "stable",246 "autoUpdatesChannel": "stable",

242 "minimumVersion": "2.1.100"247 "minimumVersion": "2.1.323"

243}248}

244```249```

245 250

246In [managed settings](https://code.claude.com/docs/en/managed-settings.md), this enforces an organization-wide minimum that user and project settings cannot override.251The installation stays on 2.1.323 until the stable channel serves a newer version.

252

253#### Set version limits for your organization

254

255In [managed settings](https://code.claude.com/docs/en/managed-settings.md), `minimumVersion` enforces an organization-wide minimum that user and project settings can't override.

247 256

248The `minimumVersion` pin only constrains updates. To make Claude Code refuse to start outside a version range, use the managed settings `requiredMinimumVersion` and `requiredMaximumVersion` instead. Updates also respect the `requiredMaximumVersion` ceiling. See [`requiredMinimumVersion`](https://code.claude.com/docs/en/settings-reference#requiredminimumversion) and [`requiredMaximumVersion`](https://code.claude.com/docs/en/settings-reference#requiredmaximumversion).257The `minimumVersion` pin only constrains updates. To make Claude Code refuse to start outside a version range, use the managed settings `requiredMinimumVersion` and `requiredMaximumVersion` instead. Updates also respect the `requiredMaximumVersion` ceiling. See [`requiredMinimumVersion`](https://code.claude.com/docs/en/settings-reference#requiredminimumversion) and [`requiredMaximumVersion`](https://code.claude.com/docs/en/settings-reference#requiredmaximumversion).

249 258

sub-agents.md +59 −42

Details

36>36>

37> A fast, read-only agent optimized for searching and analyzing codebases.37> A fast, read-only agent optimized for searching and analyzing codebases.

38>38>

~~39> * **Model**: the main conversation's model. When the main conversation runs Fable, Explore's model depends on how you connect:~~39> * **Model**: the [parent conversation's](#which-model-a-nested-subagent-runs-on) model. When the parent conversation runs Fable, Explore runs on Opus or stays on Fable, based on how you connect.

40> * With a Claude subscription, an Anthropic Console account, or an [LLM gateway](https://code.claude.com/docs/en/llm-gateway) reached through `ANTHROPIC_BASE_URL`, Explore runs on the Opus model that the [`opus` alias](https://code.claude.com/docs/en/model-config#model-aliases) resolves to.40> * With a Claude subscription, an Anthropic Console account, or an [LLM gateway](https://code.claude.com/docs/en/llm-gateway) reached through `ANTHROPIC_BASE_URL`, Explore runs on the Opus model that the [`opus` alias](https://code.claude.com/docs/en/model-config#model-aliases) resolves to.

41> * On Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, [Claude Platform on AWS](https://code.claude.com/docs/en/claude-platform-on-aws.md), or a [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway), Explore stays on the main conversation's model.41> * On Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, [Claude Platform on AWS](https://code.claude.com/docs/en/claude-platform-on-aws.md), or a [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway), Explore stays on Fable.

42> * **Tools**: read-only tools; Write and Edit are denied42> * **Tools**: read-only tools; Write and Edit are denied

43> * **Purpose**: file discovery, code search, codebase exploration43> * **Purpose**: file discovery, code search, codebase exploration

44>44>

52>52>

53> A research agent used during [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) to gather context before presenting a plan.53> A research agent used during [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) to gather context before presenting a plan.

54>54>

~~55> * **Model**: inherits from the main conversation, unless you set `CLAUDE_CODE_SUBAGENT_MODEL` and [force it onto every subagent](#run-every-subagent-on-one-model)~~55> * **Model**: inherits from the [parent conversation](#which-model-a-nested-subagent-runs-on), unless you set `CLAUDE_CODE_SUBAGENT_MODEL` and [force it onto every subagent](#run-every-subagent-on-one-model)

56> * **Tools**: read-only tools; Write and Edit are denied56> * **Tools**: read-only tools; Write and Edit are denied

57> * **Purpose**: codebase research for planning57> * **Purpose**: codebase research for planning

58>58>

62>62>

63> A capable agent for complex, multi-step tasks that require both exploration and action.63> A capable agent for complex, multi-step tasks that require both exploration and action.

64>64>

65> * **Model**: the [`CLAUDE_CODE_SUBAGENT_MODEL`](#choose-a-model) model if you set one and nothing assigns a model another way, otherwise the main conversation's model; [Choose a model](#choose-a-model) states the full order, and [Run every subagent on one model](#run-every-subagent-on-one-model) shows how to make the variable override those sources65> * **Model**: the parent conversation's model by default, following the [model order](#choose-a-model)

66> * **Tools**: every tool [available to subagents](#available-tools)66> * **Tools**: every tool [available to subagents](#available-tools)

67> * **Purpose**: complex research, multi-step operations, code modifications67> * **Purpose**: complex research, multi-step operations, code modifications

68>68>

346 346

347### Choose a model347### Choose a model

348 348

349The `model` field controls which model the subagent uses:349By default, a subagent you define runs on the same model as the conversation that starts it. To choose its model yourself, set the [`model`](#supported-frontmatter-fields) field in its definition to one of these values:

350 350

351* **Model alias**: use one of the available aliases: `sonnet`, `opus`, `haiku`, or `fable`351* **Model alias**: `sonnet`, `opus`, `haiku`, or `fable`

352* **Full model ID**: use a full model ID such as `claude-opus-5-5` or `claude-sonnet-5`. Accepts the same values as the `--model` flag352* **Full model ID**: a value the [`--model`](https://code.claude.com/docs/en/cli-reference#cli-flags) flag accepts, such as `claude-opus-5-5` or `claude-sonnet-5`

353* **inherit**: use the same model as the main conversation353* **`inherit`**: the main conversation's model, or the spawning subagent's model for a [nested subagent](#which-model-a-nested-subagent-runs-on)

354 354

355When Claude invokes a subagent, it can also pass a `model` parameter for that specific invocation. On an Agent tool call, that parameter takes a model alias: `sonnet`, `opus`, `haiku`, or `fable`. Claude can't pass a full model ID or `inherit` on that call. Claude Code resolves the subagent's model in this order:355When more than one source sets a model, Claude Code uses the first in this order:

356 356

3571. The per-invocation `model` parameter3571. The per-invocation `model` parameter, which Claude can pass when it starts the subagent. On an Agent tool call, the parameter takes a model alias, not a full model ID or `inherit`.

3582. The subagent definition's `model` frontmatter, where `inherit` selects the main conversation's model3582. The `model` field in the subagent's definition, including `inherit`

3593. The [`CLAUDE_CODE_SUBAGENT_MODEL`](https://code.claude.com/docs/en/model-config#environment-variables) environment variable, when you set it to a model alias or model ID3593. The [`CLAUDE_CODE_SUBAGENT_MODEL`](https://code.claude.com/docs/en/model-config#environment-variables) environment variable

3604. The main conversation's model3604. The main conversation's model, or the spawning subagent's model for a nested subagent

361 361

362If an installed [mod](https://code.claude.com/docs/en/plugins/mods/overview.md) sets a model in its [`agent.spawn`](https://code.claude.com/docs/en/plugins/mods/reference#subagents) hook, Claude Code uses that model in place of the per-invocation parameter.362If Claude passed an alias, the subagent keeps that alias when it [resumes or receives a follow-up message](#resume-subagents). If an installed [mod](https://code.claude.com/docs/en/plugins/mods/overview.md) sets a model in its [`agent.spawn`](https://code.claude.com/docs/en/plugins/mods/reference#subagents) hook, Claude Code uses that model in place of the per-invocation parameter.

~~363~~

364In two cases, a family alias such as `opus` in the per-invocation parameter or the frontmatter resolves to the main conversation's model instead of the [version the alias points to](https://code.claude.com/docs/en/model-config.md#model-aliases):

~~365~~

366* **The main conversation's model belongs to that family**: the subagent runs on the main conversation's exact model, including any `[1m]` suffix, so it gets the same [extended context](https://code.claude.com/docs/en/model-config.md#extended-context) window as the main conversation.

367* **Claude Code can't tell the main conversation's model family, on [a provider other than the Anthropic API](https://code.claude.com/docs/en/third-party-integrations.md)**: this can happen with an [application inference profile ARN](https://code.claude.com/docs/en/amazon-bedrock.md#iam-configuration) on Amazon Bedrock that Claude Code hasn't resolved to a backing model. This case covers only the `opus` alias, and doesn't apply when you set [`ANTHROPIC_DEFAULT_OPUS_MODEL`](https://code.claude.com/docs/en/model-config#environment-variables), since `opus` then resolves to the model you set.

~~368~~

369An alias in `CLAUDE_CODE_SUBAGENT_MODEL` always resolves to the version the alias points to, even when it names the main conversation's family. Setting the variable to `inherit` is the same as leaving it unset.

370 363

371Setting `CLAUDE_CODE_SUBAGENT_MODEL` by itself doesn't change the model the built-in Explore and Plan subagents run on. To change it, see [Run every subagent on one model](#run-every-subagent-on-one-model).364Setting `CLAUDE_CODE_SUBAGENT_MODEL` by itself doesn't change the model the built-in Explore and Plan subagents run on. To change it, see [Run every subagent on one model](#run-every-subagent-on-one-model).

372 365

373Before v2.1.251, `CLAUDE_CODE_SUBAGENT_MODEL` came first in this order and overrode both the per-invocation parameter and the frontmatter, including `model: inherit`.366#### Which model a nested subagent runs on

374 367

375Claude Code checks the per-invocation parameter, frontmatter, and environment variable values against your organization's [`availableModels`](https://code.claude.com/docs/en/model-config#restrict-model-selection) allowlist. For a blocked value, it substitutes another model:368By default, a [nested subagent](#let-subagents-spawn-their-own-subagents) you define runs on the model of its parent, the subagent that spawned it. To run the nested subagent on another model, set its `model` field to that model.

376 369

377* When the blocked value is a family alias such as `opus`, Claude Code runs the subagent on the newest version of that family the allowlist permits, following the same [substitution rules and provider scope](https://code.claude.com/docs/en/model-config.md#restrict-model-selection) as `/model`. Before v2.1.222, Claude Code ran the subagent on the inherited model for a blocked family alias as well.370For example, suppose your main conversation runs on Opus and starts a reviewer subagent on Haiku. By default, these subagents run on Haiku, not Opus, when the reviewer spawns them:

378* For any other blocked value, on providers where that substitution doesn't operate, or when the allowlist permits no version of the family, Claude Code runs the subagent on the inherited model instead. If you set `CLAUDE_CODE_SUBAGENT_MODEL`, Claude Code tries that model first, under these same rules.

379 371

380In interactive sessions, Claude Code shows a warning naming the requested model and the model the subagent runs on, for either substitution.372* A subagent with `model: inherit` or no `model` field

373* The built-in Explore, Plan, and general-purpose subagents

374* A [fork](#fork-the-current-conversation)

381 375

382To check which model a subagent is running on, run [`/tasks`](https://code.claude.com/docs/en/commands). Claude Code names the model on the subagent's row, and adds the [effort level](https://code.claude.com/docs/en/model-config.md#adjust-effort-level) set for that subagent, if any. Requires Claude Code v2.1.242 or later.376In plan mode, these subagents run on Opus if you set your session's model to [`opusplan`](https://code.claude.com/docs/en/model-config#opusplan-model-setting), or on Sonnet if you set it to `haiku`.

383 377

384A per-invocation `model` parameter also applies when the subagent is [resumed or sent a follow-up message](#resume-subagents), so the subagent stays on that model.378#### Check a subagent's model

385 379

386As of v2.1.198, subagents also inherit the main conversation's [extended thinking](https://code.claude.com/docs/en/model-config.md#extended-thinking) configuration: if thinking is on in your session, it's on for the subagent, and if it's off, it stays off. There is no per-subagent thinking setting. Before v2.1.198, subagents ran with extended thinking disabled regardless of the main conversation's setting.380To check which model a subagent is running on, run [`/tasks`](https://code.claude.com/docs/en/commands). Claude Code names the model on the subagent's row, and adds the [effort level](https://code.claude.com/docs/en/model-config.md#adjust-effort-level) set for that subagent, if any. Requires Claude Code v2.1.242 or later.

387 381

388#### Run every subagent on one model382#### Run every subagent on one model

389 383

390`CLAUDE_CODE_SUBAGENT_MODEL` is a default, so a subagent's definition or a model Claude passes still takes precedence over it. To apply one model to every subagent, [teammate](https://code.claude.com/docs/en/agent-teams.md#specify-teammates-and-models), and [workflow agent](https://code.claude.com/docs/en/workflows.md), also set `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` to `1`. Requires Claude Code v2.1.257 or later.384To apply one model to every subagent, [teammate](https://code.claude.com/docs/en/agent-teams.md#specify-teammates-and-models), and [workflow agent](https://code.claude.com/docs/en/workflows.md), set `CLAUDE_CODE_SUBAGENT_MODEL` to that model and `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` to `1`. Requires Claude Code v2.1.257 or later.

~~391~~

392* If you set both variables, subagents run on the model in `CLAUDE_CODE_SUBAGENT_MODEL`.

393* If you set only `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`, subagents run on the main conversation's model, except that the built-in Explore subagent runs on the [model listed for it under Built-in subagents](#built-in-subagents).

394 385

395For example, to run every subagent on Haiku, set both variables in the `env` block of a [settings file](https://code.claude.com/docs/en/settings.md):386For example, to run every subagent on Haiku, set both variables in the `env` block of a [settings file](https://code.claude.com/docs/en/settings.md):

396 387

405 396

406To check that the setting took effect, run [`/tasks`](https://code.claude.com/docs/en/commands) while a subagent is running. The subagent's row shows the model it runs on.397To check that the setting took effect, run [`/tasks`](https://code.claude.com/docs/en/commands) while a subagent is running. The subagent's row shows the model it runs on.

407 398

408While `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` is [on](https://code.claude.com/docs/en/env-vars.md), Claude Code ignores the `model` field in subagent definitions, and Claude can't pass a model when it starts a subagent. These subagents still run on the main conversation's model:399While `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` is [on](https://code.claude.com/docs/en/env-vars.md), Claude Code ignores the `model` field in subagent definitions, and Claude can't pass a model when it starts a subagent. The following subagents still run on their parent conversation's model:

409 400

410* A [fork](#fork-the-current-conversation)401* A [fork](#fork-the-current-conversation)

411* A [skill that runs in a subagent](https://code.claude.com/docs/en/skills.md#run-skills-in-a-subagent) with `model: inherit`402* A [skill that runs in a subagent](https://code.claude.com/docs/en/skills.md#run-skills-in-a-subagent) with `model: inherit`

412 403

404If you set only `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`, subagents run on the main conversation's model, except that the built-in Explore subagent runs on the [model listed for it under Built-in subagents](#built-in-subagents).

405

406#### Which version a model alias selects

407

408By default, a subagent with a model alias runs on the [version the alias points to](https://code.claude.com/docs/en/model-config.md#model-aliases). With a family alias such as `opus` in the `model` field or per-invocation parameter, the subagent runs on its parent conversation's model in two cases:

409

410* **Same family**: for example, if your main conversation runs on `claude-opus-4-7`, a subagent with `model: opus` runs on that version too. To run another version, set a full model ID in the `model` field.

411* **Unknown family**: Claude Code can't tell the parent model's family, such as with an Amazon Bedrock ARN it [can't look up](https://code.claude.com/docs/en/amazon-bedrock.md#iam-configuration). This case applies only to the `opus` alias on [a provider other than the Anthropic API](https://code.claude.com/docs/en/third-party-integrations.md). To choose the Opus version, set [`ANTHROPIC_DEFAULT_OPUS_MODEL`](https://code.claude.com/docs/en/model-config#environment-variables).

412

413#### When an allowlist blocks a subagent model

414

415If your organization's [`availableModels`](https://code.claude.com/docs/en/model-config#restrict-model-selection) allowlist blocks the model set for a subagent, the subagent runs on the first of these that applies:

416

4171. For a blocked family alias, the newest permitted version in that family, on [providers that support this substitution](https://code.claude.com/docs/en/model-config.md#restrict-model-selection)

4182. The model in `CLAUDE_CODE_SUBAGENT_MODEL`, if you set it, under these same rules

4193. The main conversation's model, or the spawning subagent's model for a nested subagent

420

421For a top-level subagent in an interactive session, a warning names the requested model and its replacement. To run a particular model, change the blocked value to one the allowlist permits.

422

423### Extended thinking in subagents

424

425Subagents inherit your main conversation's [extended thinking](https://code.claude.com/docs/en/model-config.md#extended-thinking) configuration. There is no per-subagent thinking setting.

426

413### Choose an effort level427### Choose an effort level

414 428

415To run a subagent at its own [effort level](https://code.claude.com/docs/en/model-config.md#adjust-effort-level), set the [`effort`](#supported-frontmatter-fields) field in its definition.429To run a subagent at its own [effort level](https://code.claude.com/docs/en/model-config.md#adjust-effort-level), set the [`effort`](#supported-frontmatter-fields) field in its definition.

426 440

427#### Available tools441#### Available tools

428 442

429Subagents inherit the [built-in tools](https://code.claude.com/docs/en/tools-reference.md) and MCP tools available in the main conversation, narrowed by two filters: the first removes a short list of tools from every subagent, and the second reduces the built-in tool set for subagents that run in the [background](#run-subagents-in-foreground-or-background), which is the default. On macOS, Linux, and WSL, a subagent can also receive the Glob and Grep tools when the main conversation doesn't have them, as described under [Glob tool behavior](https://code.claude.com/docs/en/tools-reference.md#glob-tool-behavior). [Forks](#fork-the-current-conversation) skip both filters and receive the main conversation's exact tool pool. The first filter removes these tools, even when listed in the `tools` field:443Subagents inherit the [built-in tools](https://code.claude.com/docs/en/tools-reference.md) and MCP tools available in the main conversation, narrowed by two filters. The first removes a short list of tools from every subagent. The second reduces the built-in tool set for subagents that run in the [background](#run-subagents-in-foreground-or-background), which is the default.

444

445On macOS, Linux, and WSL, a subagent can also receive the Glob and Grep tools when the main conversation doesn't have them, as described under [Glob tool behavior](https://code.claude.com/docs/en/tools-reference.md#glob-tool-behavior). [Forks](#fork-the-current-conversation) skip both filters and receive their parent conversation's exact tool pool. The first filter removes these tools, even when listed in the `tools` field:

430 446

431* `Agent`, when the subagent is at the [depth limit](#let-subagents-spawn-their-own-subagents); in a [fork](#fork-the-current-conversation) the tool stays listed but returns an error instead of spawning447* `Agent`, when the subagent is at the [depth limit](#let-subagents-spawn-their-own-subagents); in a [fork](#fork-the-current-conversation) the tool stays listed but returns an error instead of spawning

432* `AskUserQuestion`448* `AskUserQuestion`

1077 1093

1078With this value, your subagents can delegate to a second layer of their own, and that second layer can't delegate further. Set `1` to turn nesting off.1094With this value, your subagents can delegate to a second layer of their own, and that second layer can't delegate further. Set `1` to turn nesting off.

1079 1095

1080A nested subagent is configured the same way as a top-level one and resolves from the same [scopes](#choose-the-subagent-scope). To keep one subagent from spawning while nesting is on, such as a reviewer that should stay read-only, omit `Agent` from its [`tools`](#available-tools) list or add it to `disallowedTools`.1096Define a nested subagent in the same [scopes](#choose-the-subagent-scope) as a top-level one. By default, a nested subagent you define runs on the [spawning subagent's model](#which-model-a-nested-subagent-runs-on). To keep one subagent from spawning while nesting is on, such as a reviewer that should stay read-only, omit `Agent` from its [`tools`](#available-tools) list or add it to `disallowedTools`.

1081 1097

1082In the terminal, Claude Code shows nested subagents as a tree in the subagent panel below the prompt input and marks each row that still has descendants in the panel with a `(+N)` count of them. Open a row to see that subagent's siblings and direct children with a path back to `main`.1098In the terminal, Claude Code shows nested subagents as a tree in the subagent panel below the prompt input and marks each row that still has descendants in the panel with a `(+N)` count of them. Open a row to see that subagent's siblings and direct children with a path back to `main`.

1083 1099

1221>1237>

1222> When [agent view is turned off](https://code.claude.com/docs/en/agent-view.md#turn-off-agent-view), `/subtask` isn't available and `/fork` starts the forked subagent instead; otherwise `/fork` copies the whole session into a new [background session](https://code.claude.com/docs/en/agent-view.md#from-inside-a-session).1238> When [agent view is turned off](https://code.claude.com/docs/en/agent-view.md#turn-off-agent-view), `/subtask` isn't available and `/fork` starts the forked subagent instead; otherwise `/fork` copies the whole session into a new [background session](https://code.claude.com/docs/en/agent-view.md#from-inside-a-session).

1223 1239

1224A fork is a subagent that inherits the entire conversation so far instead of starting fresh. This drops the input isolation that subagents otherwise provide: a fork sees the same system prompt, tools, model, and message history as the main session, so you can hand it a side task without re-explaining the situation. The fork's own tool calls still stay out of your conversation and only its final result comes back, so your main context window stays clean. Use a fork when any other subagent would need too much background to be useful, or when you want to try several approaches in parallel from the same starting point.1240A fork is a subagent that inherits the entire conversation so far instead of starting fresh. Use a fork when any other subagent would need too much background to be useful, or when you want to try several approaches in parallel from the same starting point.

1241

1242* **Input**: a fork sees the same system prompt, tools, [model](#which-model-a-nested-subagent-runs-on), and message history as its parent conversation

1243* **Output**: the fork's own tool calls stay out of its parent conversation and only its final result comes back

1225 1244

1226Claude can start a fork on its own while fork mode is on, as it is by default. To stop forks, see [Turn fork mode off](#turn-fork-mode-on-or-off).1245Claude can start a fork on its own while fork mode is on, as it is by default. To stop forks, see [Turn fork mode off](#turn-fork-mode-on-or-off).

1227 1246

1257 1276

1258### How forks differ from other subagents1277### How forks differ from other subagents

1259 1278

1260A fork inherits everything the main session has at the moment it spawns. Any other subagent starts fresh from its definition.

~~1261~~

1262| | Fork | Non-fork subagent |1279| | Fork | Non-fork subagent |

1263| :- | :- | :- |1280| :- | :- | :- |

1268 1285

1269Because a fork's system prompt and tool definitions are identical to the parent, its first request reuses the parent's [prompt cache](https://code.claude.com/docs/en/prompt-caching.md#subagents-and-the-cache). Because of that reuse, a fork costs less than a fresh subagent for tasks that need the same context.1286Because a fork's system prompt and tool definitions are identical to the parent, its first request reuses the parent's [prompt cache](https://code.claude.com/docs/en/prompt-caching.md#subagents-and-the-cache). Because of that reuse, a fork costs less than a fresh subagent for tasks that need the same context.

1270 1287

workflows.md +1 −1

Details

454* Check `/model` before a large run if you usually switch to a smaller model for routine work454* Check `/model` before a large run if you usually switch to a smaller model for routine work

455* Ask Claude to use a smaller model for stages that don't need the strongest one when you describe the task455* Ask Claude to use a smaller model for stages that don't need the strongest one when you describe the task

456 456

457When your organization's [`availableModels` allowlist](https://code.claude.com/docs/en/model-config#restrict-model-selection) blocks a model the script requests for an agent, that agent runs on a substituted model instead, following the same [substitution rules as subagents](https://code.claude.com/docs/en/sub-agents.md#choose-a-model).457When your organization's [`availableModels` allowlist](https://code.claude.com/docs/en/model-config#restrict-model-selection) blocks a model the script requests for an agent, that agent runs on a substituted model instead, following the same [substitution rules as subagents](https://code.claude.com/docs/en/sub-agents.md#when-an-allowlist-blocks-a-subagent-model).

458 458

459### Set a size guideline459### Set a size guideline

460 460

worktrees.md +5 −2

Details

232 232

233With the default `"fresh"` [base](#choose-the-base-branch), a reopened worktree resets to the repository's default branch instead of continuing at its old tip when all of the following hold:233With the default `"fresh"` [base](#choose-the-base-branch), a reopened worktree resets to the repository's default branch instead of continuing at its old tip when all of the following hold:

234 234

235* It has no uncommitted changes or untracked files.235* The [sandbox](https://code.claude.com/docs/en/sandboxing.md#filesystem-isolation) isn't restricting file writes in your session, and neither the worktree's nor the main checkout's `.claude` settings files enable the sandbox.

236* The worktree has no uncommitted changes or untracked files.

236* It is still on the branch Claude Code created for it.237* It is still on the branch Claude Code created for it.

237* It has no commits of its own, or its pull request or merge request was merged and its remote branch deleted.238* It has no commits of its own, or its pull request or merge request was merged and its remote branch deleted.

238 239

240 241

241In every other case, Claude Code reopens the worktree at its old tip:242In every other case, Claude Code reopens the worktree at its old tip:

242 243

243* The worktree fails any of the conditions.244* The worktree or session fails any of the conditions.

244* Claude Code can't verify the worktree's state.245* Claude Code can't verify the worktree's state.

245* `worktree.baseRef` is `"head"`.246* `worktree.baseRef` is `"head"`.

246* The name is a pull request or merge request reference.247* The name is a pull request or merge request reference.

247 248

249If you use the sandbox with the `"fresh"` base, run `git fetch origin`, then pass a new name to `--worktree` to start from the latest default branch.

250

248### Replace worktree creation with a hook251### Replace worktree creation with a hook

249 252

250Configure a [`WorktreeCreate` hook](https://code.claude.com/docs/en/hooks#worktreecreate) to replace the default `git worktree` logic entirely, including placing worktrees somewhere other than `.claude/worktrees/`. For a complete example, see [Non-git version control](#non-git-version-control).253Configure a [`WorktreeCreate` hook](https://code.claude.com/docs/en/hooks#worktreecreate) to replace the default `git worktree` logic entirely, including placing worktrees somewhere other than `.claude/worktrees/`. For a complete example, see [Non-git version control](#non-git-version-control).

Documentation 2026-11-13 23:02 UTC to 2026-11-14 03:01 UTC