Documentation — Spybara

admin-setup.md +1 −1

Details

96| [Managed policy CLAUDE.md](https://code.claude.com/docs/en/memory.md#deploy-organization-wide-claude-md) | Organization-wide behavioral guidance for Claude rather than a client-enforced rule | File at the managed policy path |96| [Managed policy CLAUDE.md](https://code.claude.com/docs/en/memory.md#deploy-organization-wide-claude-md) | Organization-wide behavioral guidance for Claude rather than a client-enforced rule | File at the managed policy path |

97| [MCP server control](https://code.claude.com/docs/en/managed-mcp.md) | Restrict which MCP servers users can add or connect to, deploy a fixed set, or provide remote servers to every user alongside their own | `allowedMcpServers`, `deniedMcpServers`, `allowManagedMcpServersOnly`, `managedMcpServers`, or a deployed `managed-mcp.json` file |97| [MCP server control](https://code.claude.com/docs/en/managed-mcp.md) | Restrict which MCP servers users can add or connect to, deploy a fixed set, or provide remote servers to every user alongside their own | `allowedMcpServers`, `deniedMcpServers`, `allowManagedMcpServersOnly`, `managedMcpServers`, or a deployed `managed-mcp.json` file |

98| [Plugin marketplace control](https://code.claude.com/docs/en/plugins/org.md#restrict-what-users-can-install) | Restrict which marketplace sources users can add and install from, and reject the CLI flags that sideload plugins, agents, and MCP servers for a single run. Block [`command` plugin sources](https://code.claude.com/docs/en/plugins/marketplace-reference#command-plugin-source), and allowlist which marketplaces' plugins can be suggested in the terminal | `strictKnownMarketplaces`, `blockedMarketplaces`, `disableSideloadFlags`, `disableCommandPluginSources`, `pluginSuggestionMarketplaces` |98| [Plugin marketplace control](https://code.claude.com/docs/en/plugins/org.md#restrict-what-users-can-install) | Restrict which marketplace sources users can add and install from, and reject the CLI flags that sideload plugins, agents, and MCP servers for a single run. Block [`command` plugin sources](https://code.claude.com/docs/en/plugins/marketplace-reference#command-plugin-source), and allowlist which marketplaces' plugins can be suggested in the terminal | `strictKnownMarketplaces`, `blockedMarketplaces`, `disableSideloadFlags`, `disableCommandPluginSources`, `pluginSuggestionMarketplaces` |

99| [Customization lockdown](https://code.claude.com/docs/en/settings-reference.md#strictpluginonlycustomization) | Block skills, agents, hooks, and MCP servers from user and project sources, so they can only come from plugins or managed settings. Locking skills also stops the [skills your developers enable on claude.ai](https://code.claude.com/docs/en/skills.md#where-synced-skills-load) from syncing | `strictPluginOnlyCustomization` |99| [Customization lockdown](https://code.claude.com/docs/en/settings-reference.md#strictpluginonlycustomization) | Block skills, agents, hooks, and MCP servers from user and project sources. Locking skills also stops the [skills your developers enable on claude.ai](https://code.claude.com/docs/en/skills.md#where-synced-skills-load) from syncing | `strictPluginOnlyCustomization` |

100| [Disable claude.ai sync](https://code.claude.com/docs/en/settings-reference.md#syncclaudeaiskills) | Stop Claude Code from loading the [skills](https://code.claude.com/docs/en/skills.md#how-synced-skills-behave) and [plugins](https://code.claude.com/docs/en/plugins/loading.md#synced-plugins) your developers enable on claude.ai. If you turn off Skills for your organization on claude.ai, Claude Code stops syncing both, and on v2.1.273 or later it also removes the ones it already synced. To stop either one without turning Skills off, set its key to `false` in managed settings | `syncClaudeAiSkills`, `syncClaudeAiPlugins` |100| [Disable claude.ai sync](https://code.claude.com/docs/en/settings-reference.md#syncclaudeaiskills) | Stop Claude Code from loading the [skills](https://code.claude.com/docs/en/skills.md#how-synced-skills-behave) and [plugins](https://code.claude.com/docs/en/plugins/loading.md#synced-plugins) your developers enable on claude.ai. If you turn off Skills for your organization on claude.ai, Claude Code stops syncing both, and on v2.1.273 or later it also removes the ones it already synced. To stop either one without turning Skills off, set its key to `false` in managed settings | `syncClaudeAiSkills`, `syncClaudeAiPlugins` |

101| [Hook restrictions](https://code.claude.com/docs/en/settings-reference.md#allowmanagedhooksonly) | Restrict which hooks run and restrict HTTP hook URLs; see [what runs under `allowManagedHooksOnly`](https://code.claude.com/docs/en/settings-reference#what-runs-under-allowmanagedhooksonly) for the full effect list | `allowManagedHooksOnly`, `allowedHttpHookUrls` |101| [Hook restrictions](https://code.claude.com/docs/en/settings-reference.md#allowmanagedhooksonly) | Restrict which hooks run and restrict HTTP hook URLs; see [what runs under `allowManagedHooksOnly`](https://code.claude.com/docs/en/settings-reference#what-runs-under-allowmanagedhooksonly) for the full effect list | `allowManagedHooksOnly`, `allowedHttpHookUrls` |

102| [Login enforcement](https://code.claude.com/docs/en/settings-reference.md#forceloginmethod) | Restrict login to a specific method or Anthropic organization. The method restriction applies across the VS Code extension, Agent SDK, `claude setup-token`, and `/install-github-app`, and the terminal's interactive login screen, reached by `/login` or first-run onboarding, pre-selects the method without enforcing it; Claude Code verifies the organization for claude.ai account logins in the terminal, VS Code extension, and Agent SDK, and doesn't check it for Claude Console logins or for [gateway](https://code.claude.com/docs/en/claude-apps-gateway) sign-in. Before v2.1.212, only terminal logins applied either key. When set, sessions authenticated by `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or `apiKeyHelper` are blocked at startup; cloud provider sessions aren't affected unless one of those credentials, or an API key saved by an earlier Claude Console login, is also present | `forceLoginMethod`, `forceLoginOrgUUID` |102| [Login enforcement](https://code.claude.com/docs/en/settings-reference.md#forceloginmethod) | Restrict login to a specific method or Anthropic organization. The method restriction applies across the VS Code extension, Agent SDK, `claude setup-token`, and `/install-github-app`, and the terminal's interactive login screen, reached by `/login` or first-run onboarding, pre-selects the method without enforcing it; Claude Code verifies the organization for claude.ai account logins in the terminal, VS Code extension, and Agent SDK, and doesn't check it for Claude Console logins or for [gateway](https://code.claude.com/docs/en/claude-apps-gateway) sign-in. Before v2.1.212, only terminal logins applied either key. When set, sessions authenticated by `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or `apiKeyHelper` are blocked at startup; cloud provider sessions aren't affected unless one of those credentials, or an API key saved by an earlier Claude Console login, is also present | `forceLoginMethod`, `forceLoginOrgUUID` |

advisor.md +5 −6

Details

8 8

9> [!NOTE]9> [!NOTE]

10>10>

11> The advisor tool is experimental and requires the Anthropic API. It is not available on Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, or Microsoft Foundry. Behavior, pricing, and availability may change.11> The advisor tool is experimental and requires the Anthropic API or [Claude Platform on AWS](https://code.claude.com/docs/en/claude-platform-on-aws.md). On Claude Platform on AWS, it requires Claude Code v2.1.300 or later. It isn't available on Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry. Behavior, pricing, and availability may change.

12 12

13The advisor tool lets Claude consult a second, typically stronger model at key moments during a task, such as before committing to an approach, when stuck on a recurring error, or before declaring a task complete. The advisor receives the full conversation, including every tool call and result, and returns guidance that Claude applies before continuing.13The advisor tool lets Claude consult a second, typically stronger model at key moments during a task, such as before committing to an approach, when stuck on a recurring error, or before declaring a task complete. The advisor receives the full conversation, including every tool call and result, and returns guidance that Claude applies before continuing.

14 14

160* **API billing**: you pay the advisor model's input and output rates for advisor tokens160* **API billing**: you pay the advisor model's input and output rates for advisor tokens

161* **Subscription plans**: advisor usage counts toward your plan's usage limits, except that a Fable advisor bills to [usage credits](https://code.claude.com/docs/en/model-config.md#fable-and-usage-credits) on plans where Fable usage does161* **Subscription plans**: advisor usage counts toward your plan's usage limits, except that a Fable advisor bills to [usage credits](https://code.claude.com/docs/en/model-config.md#fable-and-usage-credits) on plans where Fable usage does

162 162

163If your account requires the usage-credits consent, a Fable advisor bills nothing before you give it, because Claude Code [doesn't apply the selection](#fable-advisor-and-usage-credits) until then.163For how a Fable advisor works with usage credits, see [Fable advisor and usage credits](#fable-advisor-and-usage-credits).

164 164

165Claude calls the advisor at decision points rather than on every turn, so pairing a faster main model with a stronger advisor typically costs less than running the stronger model throughout. Advisor usage counts toward the session totals shown by [`/usage`](https://code.claude.com/docs/en/costs#track-your-costs).165Claude calls the advisor at decision points rather than on every turn, so pairing a faster main model with a stronger advisor typically costs less than running the stronger model throughout. Advisor usage counts toward the session totals shown by [`/usage`](https://code.claude.com/docs/en/costs#track-your-costs).

166 166

174 174

175## Requirements175## Requirements

176 176

177The advisor tool requires all of the following:177* **Provider**: the Anthropic API or [Claude Platform on AWS](https://code.claude.com/docs/en/claude-platform-on-aws.md), not Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry. On Claude Platform on AWS, the advisor requires Claude Code v2.1.300 or later.

~~178~~ 178* **LLM gateway**: through an [LLM gateway](https://code.claude.com/docs/en/llm-gateway) configured with `ANTHROPIC_BASE_URL`, availability depends on whether the gateway forwards the request intact to the Anthropic API. If the gateway or its upstream doesn't recognize the advisor tool, see [Automatic retry and error forwarding](https://code.claude.com/docs/en/llm-gateway-protocol.md#automatic-retry-and-error-forwarding) for how Claude Code responds.

179* **Anthropic API only**: the advisor is a server-executed tool. It is not available on Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, or Microsoft Foundry. Through an [LLM gateway](https://code.claude.com/docs/en/llm-gateway) configured with `ANTHROPIC_BASE_URL`, availability depends on whether the gateway forwards the request intact to the Anthropic API. If the gateway or its upstream doesn't recognize the advisor tool, see [Automatic retry and error forwarding](https://code.claude.com/docs/en/llm-gateway-protocol.md#automatic-retry-and-error-forwarding) for how Claude Code responds.

180* **Supported main model**: Fable, Opus 4.6 or later, Sonnet 4.6 or later, Haiku 4.5, or Haiku 5.5. See [Choose an advisor model](#choose-an-advisor-model) for which advisors each accepts.179* **Supported main model**: Fable, Opus 4.6 or later, Sonnet 4.6 or later, Haiku 4.5, or Haiku 5.5. See [Choose an advisor model](#choose-an-advisor-model) for which advisors each accepts.

181* **Feature-flag fetching**: Claude Code turns the advisor on through a feature flag it fetches from Anthropic. In a session where a variable that turns flag fetching off is set, such as `DISABLE_TELEMETRY`, the advisor stays off. See [Features that need feature-flag fetching](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching).180* **Feature-flag fetching**: unless you're on Claude Platform on AWS, the advisor needs a feature flag fetched from Anthropic. A session with a variable that turns fetching off, such as `DISABLE_TELEMETRY`, doesn't have that flag. To check your session, see [which sessions skip the fetch or start without the flag](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching).

182 181

183## Turn the advisor off182## Turn the advisor off

184 183

agent-sdk/hooks.md +1 −1

Details

247* **Top-level fields** are accepted on every event: `systemMessage` shows a message to the user, and `continue` (`continue_` in Python) determines whether the agent keeps running after this hook. Some events discard them or deliver them elsewhere. Each [event's section](https://code.claude.com/docs/en/hooks.md#hook-events) on the hooks page says where they land.247* **Top-level fields** are accepted on every event: `systemMessage` shows a message to the user, and `continue` (`continue_` in Python) determines whether the agent keeps running after this hook. Some events discard them or deliver them elsewhere. Each [event's section](https://code.claude.com/docs/en/hooks.md#hook-events) on the hooks page says where they land.

248* **`hookSpecificOutput`** controls the current operation. The fields you set inside depend on the hook event type:248* **`hookSpecificOutput`** controls the current operation. The fields you set inside depend on the hook event type:

249 * For `PreToolUse` hooks, this is where you set `permissionDecision` (`"allow"`, `"deny"`, `"ask"`, or `"defer"`), `permissionDecisionReason`, and `updatedInput`. If you return `"defer"`, the turn ends with a result message whose `stop_reason` is `"tool_deferred"`, so you can [resume the call later](https://code.claude.com/docs/en/hooks.md#defer-a-tool-call-for-later).249 * For `PreToolUse` hooks, this is where you set `permissionDecision` (`"allow"`, `"deny"`, `"ask"`, or `"defer"`), `permissionDecisionReason`, and `updatedInput`. If you return `"defer"`, the turn ends with a result message whose `stop_reason` is `"tool_deferred"`, so you can [resume the call later](https://code.claude.com/docs/en/hooks.md#defer-a-tool-call-for-later).

250 * For `PostToolUse` hooks, you can set `additionalContext` to append information to the tool result. To replace the tool's output before Claude sees it, set `updatedToolOutput`, which works for any tool in both SDKs. The older `updatedMCPToolOutput` field replaces MCP tool output only.250 * For `PostToolUse` hooks, you can set `additionalContext` to append information to the tool result. To replace the tool's output before Claude sees it, set `updatedToolOutput`, which works for built-in and MCP tools in both SDKs. The older `updatedMCPToolOutput` field replaces MCP tool output only.

251 * In the TypeScript SDK, a `PostToolUse` callback can also return `classifierContext`, a short note about the tool call's result for the [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) permission classifier. Because your callback runs in your application's own process, the classifier may weigh a user statement you relay in the note as user intent. The field requires TypeScript Agent SDK v0.3.236 or later. [Annotate a result for the auto mode classifier](https://code.claude.com/docs/en/hooks.md#annotate-a-result-for-the-auto-mode-classifier) covers the length cap, the synchronous-only rule, and what not to put in the note.251 * In the TypeScript SDK, a `PostToolUse` callback can also return `classifierContext`, a short note about the tool call's result for the [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) permission classifier. Because your callback runs in your application's own process, the classifier may weigh a user statement you relay in the note as user intent. The field requires TypeScript Agent SDK v0.3.236 or later. [Annotate a result for the auto mode classifier](https://code.claude.com/docs/en/hooks.md#annotate-a-result-for-the-auto-mode-classifier) covers the length cap, the synchronous-only rule, and what not to put in the note.

252 252

253Return `{}` to allow the operation without changes. SDK callback hooks use the same JSON output format as [Claude Code shell command hooks](https://code.claude.com/docs/en/hooks.md#json-output), which documents every field and event-specific option. For the SDK type definitions, see the [TypeScript](https://code.claude.com/docs/en/agent-sdk/typescript.md#synchookjsonoutput) and [Python](https://code.claude.com/docs/en/agent-sdk/python.md#synchookjsonoutput) SDK references.253Return `{}` to allow the operation without changes. SDK callback hooks use the same JSON output format as [Claude Code shell command hooks](https://code.claude.com/docs/en/hooks.md#json-output), which documents every field and event-specific option. For the SDK type definitions, see the [TypeScript](https://code.claude.com/docs/en/agent-sdk/typescript.md#synchookjsonoutput) and [Python](https://code.claude.com/docs/en/agent-sdk/python.md#synchookjsonoutput) SDK references.

agent-sdk/observability.md +2 −3

Details

227After you attach end-user identity, these events become a per-user audit trail you can forward to a Security Information and Event Management (SIEM) platform:227After you attach end-user identity, these events become a per-user audit trail you can forward to a Security Information and Event Management (SIEM) platform:

228 228

229* `tool_decision` and `tool_result`: each tool call, whether it was allowed or denied, and its result229* `tool_decision` and `tool_result`: each tool call, whether it was allowed or denied, and its result

230* `safety_event`: which check refused a tool call or required a permission prompt for it, such as a permission rule or the auto mode classifier. Some calls [have no safety event](https://code.claude.com/docs/en/monitoring-usage.md#calls-without-a-safety-event). Requires Claude Code v2.1.307 or later

231* `mcp_server_connection`: MCP server connections and connection failures230* `mcp_server_connection`: MCP server connections and connection failures

232* `permission_mode_changed`: permission mode changes231* `permission_mode_changed`: permission mode changes

233 232

234These events export as log records named with a `claude_code.` prefix, such as `claude_code.safety_event`. See [Audit security events](https://code.claude.com/docs/en/monitoring-usage.md#audit-security-events) in the Monitoring reference for the full list of security-relevant events and the attributes each one carries.233These events export as log records named with a `claude_code.` prefix, such as `claude_code.tool_decision`. See [Audit security events](https://code.claude.com/docs/en/monitoring-usage.md#audit-security-events) in the Monitoring reference for the full list of security-relevant events and the attributes each one carries.

235 234

236## Control sensitive data in exports235## Control sensitive data in exports

237 236

240| Variable | Adds |239| Variable | Adds |

241| - | - |240| - | - |

243| `OTEL_LOG_TOOL_DETAILS=1` | Tool input arguments such as file paths, shell commands, and search patterns on `claude_code.tool_result` events, and real agent, skill, plugin, and MCP server names on the [cost and token metrics](https://code.claude.com/docs/en/monitoring-usage.md#cost-counter). The built-in rule the auto mode classifier named when it blocked a call, as [`classifier_category`](https://code.claude.com/docs/en/monitoring-usage#tool-decision-event) on `claude_code.tool_decision` and `claude_code.safety_event` events |242| `OTEL_LOG_TOOL_DETAILS=1` | Tool input arguments such as file paths, shell commands, and search patterns on `claude_code.tool_result` events, and real agent, skill, plugin, and MCP server names on the [cost and token metrics](https://code.claude.com/docs/en/monitoring-usage.md#cost-counter). The built-in rule the auto mode classifier named when it blocked a call, as [`classifier_category`](https://code.claude.com/docs/en/monitoring-usage#tool-decision-event) on `claude_code.tool_decision` events |

244| `OTEL_LOG_TOOL_CONTENT=1` | A [`tool.output` span event](https://code.claude.com/docs/en/monitoring-usage#tool-output-span-event) on `claude_code.tool` with file contents, Bash output, and what MCP tools, WebFetch, and WebSearch return, truncated at 60 KB by default, configurable via `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH`, which requires Claude Code v2.1.214 or later. Results from MCP tools, WebFetch, and WebSearch require Claude Code v2.1.283 or later. Requires [tracing](#read-agent-traces) to be enabled. Span attributes carry tool content under [their own gates](https://code.claude.com/docs/en/monitoring-usage.md#new-context-gates) |243| `OTEL_LOG_TOOL_CONTENT=1` | A [`tool.output` span event](https://code.claude.com/docs/en/monitoring-usage#tool-output-span-event) on `claude_code.tool` with file contents, Bash output, and what MCP tools, WebFetch, and WebSearch return, truncated at 60 KB by default, configurable via `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH`, which requires Claude Code v2.1.214 or later. Results from MCP tools, WebFetch, and WebSearch require Claude Code v2.1.283 or later. Requires [tracing](#read-agent-traces) to be enabled. Span attributes carry tool content under [their own gates](https://code.claude.com/docs/en/monitoring-usage.md#new-context-gates) |

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

246 245

agent-sdk/python.md +2 −2

Details

1858 1858

1859### `TaskStartedMessage`1859### `TaskStartedMessage`

1860 1860

1861Emitted when a background task starts. A background task is anything tracked outside the main turn: a backgrounded Bash command, a [Monitor](#monitor) watch, a subagent spawned via the Agent tool, or a remote agent. The `task_type` field tells you which. This naming is unrelated to the `Task`-to-`Agent` tool rename.1861Emitted when a background task starts. A background task is anything tracked outside the main turn, such as a backgrounded Bash command, a [Monitor](#monitor) watch, a subagent spawned via the Agent tool, or a remote agent. This naming is unrelated to the `Task`-to-`Agent` tool rename.

1862 1862

1863```python theme={null}1863```python theme={null}

1864@dataclass1864@dataclass

1878| `uuid` | `str` | Unique message identifier |1878| `uuid` | `str` | Unique message identifier |

1879| `session_id` | `str` | Session identifier |1879| `session_id` | `str` | Session identifier |

1881| `task_type` | `str \| None` | Which kind of background task: `"local_bash"` for background Bash and Monitor watches, `"local_agent"`, or `"remote_agent"` |1881| `task_type` | `str \| None` | Which kind of background task, such as `"local_bash"` for background Bash and Monitor watches, `"local_agent"` for subagents, `"mcp_task"` for [background MCP tool calls](https://code.claude.com/docs/en/mcp.md#automatic-backgrounding-of-long-tool-calls), or `"remote_agent"` |

1882 1882

1883### `TaskUsage`1883### `TaskUsage`

1884 1884

agent-sdk/structured-outputs.md +34 −13

Details

81 }81 }

82 })) {82 })) {

83 // The result message contains structured_output with validated data83 // The result message contains structured_output with validated data

~~84 if (message.type === "result" && message.subtype === "success" && message.structured_output) {~~84 if (message.type === "result" && message.subtype === "success" && !message.is_error && message.structured_output) {

85 console.log(message.structured_output);85 console.log(message.structured_output);

86 // { company_name: "Anthropic", founded_year: 2021, headquarters: "San Francisco, CA" }86 // { company_name: "Anthropic", founded_year: 2021, headquarters: "San Francisco, CA" }

87 }87 }

118 ),118 ),

119 ):119 ):

120 # The result message contains structured_output with validated data120 # The result message contains structured_output with validated data

121 if isinstance(message, ResultMessage) and message.structured_output:121 if (

122 isinstance(message, ResultMessage)

123 and not message.is_error

124 and message.structured_output

125 ):

122 print(message.structured_output)126 print(message.structured_output)

123 # {'company_name': 'Anthropic', 'founded_year': 2021, 'headquarters': 'San Francisco, CA'}127 # {'company_name': 'Anthropic', 'founded_year': 2021, 'headquarters': 'San Francisco, CA'}

124 except Exception as error:128 except Exception as error:

173 }177 }

174 }178 }

175 })) {179 })) {

176 if (message.type === "result" && message.subtype === "success" && message.structured_output) {180 if (message.type === "result" && message.subtype === "success" && !message.is_error && message.structured_output) {

177 // Validate and get fully typed result181 // Validate and get fully typed result

178 const parsed = FeaturePlan.safeParse(message.structured_output);182 const parsed = FeaturePlan.safeParse(message.structured_output);

179 if (parsed.success) {183 if (parsed.success) {

223 }227 }

224 ),228 ),

225 ):229 ):

226 if isinstance(message, ResultMessage) and message.structured_output:230 if (

231 isinstance(message, ResultMessage)

232 and not message.is_error

233 and message.structured_output

234 ):

227 # Validate and get fully typed result235 # Validate and get fully typed result

228 plan = FeaturePlan.model_validate(message.structured_output)236 plan = FeaturePlan.model_validate(message.structured_output)

229 print(f"Feature: {plan.feature_name}")237 print(f"Feature: {plan.feature_name}")

297 }305 }

298 }306 }

299 })) {307 })) {

300 if (message.type === "result" && message.subtype === "success" && message.structured_output) {308 if (message.type === "result" && message.subtype === "success" && !message.is_error && message.structured_output) {

301 const data = message.structured_output as { total_count: number; todos: Array<{ file: string; line: number; text: string; author?: string; date?: string }> };309 const data = message.structured_output as { total_count: number; todos: Array<{ file: string; line: number; text: string; author?: string; date?: string }> };

302 console.log(`Found ${data.total_count} TODOs`);310 console.log(`Found ${data.total_count} TODOs`);

303 data.todos.forEach((todo) => {311 data.todos.forEach((todo) => {

352 output_format={"type": "json_schema", "schema": todo_schema}360 output_format={"type": "json_schema", "schema": todo_schema}

353 ),361 ),

354 ):362 ):

355 if isinstance(message, ResultMessage) and message.structured_output:363 if (

364 isinstance(message, ResultMessage)

365 and not message.is_error

366 and message.structured_output

367 ):

356 data = message.structured_output368 data = message.structured_output

357 print(f"Found {data['total_count']} TODOs")369 print(f"Found {data['total_count']} TODOs")

358 for todo in data["todos"]:370 for todo in data["todos"]:

383 395

384Structured output generation can fail when the agent cannot produce valid JSON matching your schema. This typically happens when the schema is too complex for the task, the task itself is ambiguous, or the agent hits its retry limit trying to fix validation errors. It can also happen without any validation failure: a [model fallback](https://code.claude.com/docs/en/model-config.md#automatic-model-fallback) can retract an already-completed output mid-stream, and if no retry replaces it the run ends with the same error. Check the `errors` list on the error result message to tell the two causes apart before debugging your schema.396Structured output generation can fail when the agent cannot produce valid JSON matching your schema. This typically happens when the schema is too complex for the task, the task itself is ambiguous, or the agent hits its retry limit trying to fix validation errors. It can also happen without any validation failure: a [model fallback](https://code.claude.com/docs/en/model-config.md#automatic-model-fallback) can retract an already-completed output mid-stream, and if no retry replaces it the run ends with the same error. Check the `errors` list on the error result message to tell the two causes apart before debugging your schema.

385 397

386When an error occurs, the result message has a `subtype` indicating what went wrong:398Check the result message's `subtype`:

387 399

388| Subtype | Meaning |400| Subtype | Meaning |

389| - | - |401| - | - |

391| `error_max_structured_output_retries` | No valid output remained after multiple attempts (validation failures, or a model-fallback retraction with no successful retry) |403| `error_max_structured_output_retries` | No valid output remained after multiple attempts (validation failures, or a model-fallback retraction with no successful retry) |

392 404

393A result can also end with subtype `success` but no `structured_output` value, for example when the run completes without the agent producing a structured output. Treat that case as a failure as well. The troubleshooting entry [structured\_output is None but the result says success](https://code.claude.com/docs/en/agent-sdk/troubleshooting.md#structured_output-is-none-but-the-result-says-success) covers this case. The example below treats a result as successful only when the `subtype` is `success` and `structured_output` is present, and handles every other result as a failure:405A `success` subtype doesn't by itself mean the run produced an answer. Treat a result as a failure when the result's `is_error` is `true` or `structured_output` is absent:

406

407* **`is_error` on the result is `true`**: for example, the final model request ended in an API error or a refusal. Don't use a `structured_output` value on such a result.

408* **`structured_output` is absent**: to find the cause, see [structured\_output is None but the result says success](https://code.claude.com/docs/en/agent-sdk/troubleshooting.md#structured_output-is-none-but-the-result-says-success)

409

410The example below applies these checks:

394 411

395```typescript TypeScript theme={null}412```typescript TypeScript theme={null}

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

415 }432 }

416 })) {433 })) {

417 if (msg.type === "result") {434 if (msg.type === "result") {

418 if (msg.subtype === "success" && msg.structured_output) {435 if (msg.subtype === "success" && !msg.is_error && msg.structured_output) {

419 // Use the validated output436 // Use the validated output

420 console.log(msg.structured_output);437 console.log(msg.structured_output);

421 } else if (msg.subtype === "error_max_structured_output_retries") {438 } else if (msg.subtype === "error_max_structured_output_retries") {

422 console.error("Could not produce valid output");439 console.error("Could not produce valid output");

423 } else {440 } else {

424 console.error("Run ended without a structured output");441 console.error("Run ended with an error or without a structured output");

425 }442 }

426 }443 }

427 }444 }

456 ),473 ),

457 ):474 ):

458 if isinstance(message, ResultMessage):475 if isinstance(message, ResultMessage):

459 if message.subtype == "success" and message.structured_output:476 if (

477 message.subtype == "success"

478 and not message.is_error

479 and message.structured_output

480 ):

460 # Use the validated output481 # Use the validated output

461 print(message.structured_output)482 print(message.structured_output)

462 elif message.subtype == "error_max_structured_output_retries":483 elif message.subtype == "error_max_structured_output_retries":

463 print("Could not produce valid output")484 print("Could not produce valid output")

464 else:485 else:

465 print("Run ended without a structured output")486 print("Run ended with an error or without a structured output")

466 except Exception as error:487 except Exception as error:

467 # A single-shot query() raises after yielding an error result. If the488 # A single-shot query() raises after yielding an error result. If the

468 # failure was an error result, the error subtype branches above have489 # failure was an error result, the error subtype branches above have

agent-sdk/troubleshooting.md +1 −1

Details

142 142

143A result message can end with `subtype: "success"` while `structured_output` is `None` in Python or `undefined` in TypeScript. The run completes, but no validated output exists.143A result message can end with `subtype: "success"` while `structured_output` is `None` in Python or `undefined` in TypeScript. The run completes, but no validated output exists.

144 144

145Treat this result as a failure in application code. Check both that `subtype` is `success` and that `structured_output` is present before using it. The [Error handling](https://code.claude.com/docs/en/agent-sdk/structured-outputs.md#error-handling) section shows this pattern for both SDKs. Then check for these causes:145Treat this result as a failure in application code. The [Error handling](https://code.claude.com/docs/en/agent-sdk/structured-outputs.md#error-handling) section shows this pattern for both SDKs. Then check for these causes:

146 146

147* **A request that Claude declined**: to detect this case in your code, check the result message's `stop_reason` for `"refusal"`. For what to try next, see [Usage Policy refusal](https://code.claude.com/docs/en/errors.md#usage-policy-refusal).147* **A request that Claude declined**: to detect this case in your code, check the result message's `stop_reason` for `"refusal"`. For what to try next, see [Usage Policy refusal](https://code.claude.com/docs/en/errors.md#usage-policy-refusal).

148* **A schema no output can satisfy**: for example, a string whose `minLength` is greater than its `maxLength`. If `structured_output` is missing repeatedly with a schema you believe is correct, look for constraints that contradict each other. If you find none, simplify the schema until outputs validate, then reintroduce your constraints one at a time.148* **A schema no output can satisfy**: for example, a string whose `minLength` is greater than its `maxLength`. If `structured_output` is missing repeatedly with a schema you believe is correct, look for constraints that contradict each other. If you find none, simplify the schema until outputs validate, then reintroduce your constraints one at a time.

agent-sdk/typescript.md +8 −5

Details

1924| `network_error` | The [availability check](https://code.claude.com/docs/en/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) couldn't reach `api.anthropic.com` |1924| `network_error` | The [availability check](https://code.claude.com/docs/en/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) couldn't reach `api.anthropic.com` |

1927| `disabled_by_env` | [`CLAUDE_CODE_DISABLE_FAST_MODE`](https://code.claude.com/docs/en/env-vars) is set |1927| `disabled_by_env` | [`CLAUDE_CODE_DISABLE_FAST_MODE`](https://code.claude.com/docs/en/env-vars) is set, or the model's region on [Google Cloud's Agent Platform](https://code.claude.com/docs/en/fast-mode.md#use-fast-mode-on-agent-platform) doesn't offer fast mode |

1928| `model_not_allowed` | The fast mode Opus model isn't in the organization's [`availableModels`](https://code.claude.com/docs/en/model-config#restrict-model-selection) allowlist |1928| `model_not_allowed` | The fast mode model isn't in the organization's [`availableModels`](https://code.claude.com/docs/en/model-config#restrict-model-selection) allowlist, or the provider refused fast mode for the session's model |

1929| `sdk_opt_in_required` | The session hasn't opted in to fast mode: pass `fastMode: true` in the [`settings`](#options) option or through [`applyFlagSettings()`](#applyflagsettings) |1929| `sdk_opt_in_required` | The session hasn't opted in to fast mode: pass `fastMode: true` in the [`settings`](#options) option or through [`applyFlagSettings()`](#applyflagsettings) |

1931 1931

2007 2007

2008#### `startup_failure_reason`2008#### `startup_failure_reason`

2009 2009

2010Why Claude Code refused to start, so your application can offer the fix instead of a retry. Claude Code sets it on the `error_during_execution` result it writes before exiting on a known startup failure. That result carries zeroed totals, and its `errors` array carries the same text as stderr. The field is absent on every other result. Requires Agent SDK v0.3.274 or later.2010Why Claude Code refused to start, so your application can offer the fix instead of a retry. Claude Code sets it on the `error_during_execution` result it writes before exiting on a known startup failure. That result carries zeroed totals, and its `errors` array carries the failure message. The field is absent on every other result. Requires Agent SDK v0.3.274 or later.

2011 2011

2012Set `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` to `1` in [`env`](#options) to receive this result for every `SDKStartupFailureReason` value. Without that variable, Claude Code writes the result only for these failures, and the rest end with stderr output, a non-zero exit, and no result message:2012Set `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` to `1` in [`env`](#options) to receive this result for every `SDKStartupFailureReason` value. Without that variable, Claude Code writes the result only for these failures, and the rest end with stderr output, a non-zero exit, and no result message:

2013 2013

5711 5711

5712### `SDKTaskStartedMessage`5712### `SDKTaskStartedMessage`

5713 5713

5714Emitted when a task begins. The `task_type` field is `"local_bash"` for Bash commands and [Monitor](#monitor) watches, `"local_agent"` for subagents, or `"remote_agent"`.5714Emitted when a task begins. `task_type` names the kind of task, such as `"local_bash"` for Bash commands and [Monitor](#monitor) watches, `"local_agent"` for subagents, `"mcp_task"` for [background MCP tool calls](https://code.claude.com/docs/en/mcp.md#automatic-backgrounding-of-long-tool-calls), or `"remote_agent"`.

5715 5715

5716```typescript theme={null}5716```typescript theme={null}

5717type SDKTaskStartedMessage = {5717type SDKTaskStartedMessage = {

5920 errorCode?: "credits_required";5920 errorCode?: "credits_required";

5921 canUserPurchaseCredits?: boolean;5921 canUserPurchaseCredits?: boolean;

5922 hasChargeableSavedPaymentMethod?: boolean;5922 hasChargeableSavedPaymentMethod?: boolean;

5923 overageEnabled?: boolean;

5923 };5924 };

5924 uuid: UUID;5925 uuid: UUID;

5925 session_id: string;5926 session_id: string;

5928 5929

5929When `errorCode` is `"credits_required"`, the rejection is from a claude.ai subscription whose included usage is exhausted, and the session cannot continue until the user buys usage credits. `canUserPurchaseCredits` indicates whether the authenticated user can buy credits for the account, and `hasChargeableSavedPaymentMethod` indicates whether a saved payment method is on file. All three fields are absent on rate-limit events that are not credits-required rejections. Requires Claude Code v2.1.181 or later.5930When `errorCode` is `"credits_required"`, the rejection is from a claude.ai subscription whose included usage is exhausted, and the session cannot continue until the user buys usage credits. `canUserPurchaseCredits` indicates whether the authenticated user can buy credits for the account, and `hasChargeableSavedPaymentMethod` indicates whether a saved payment method is on file. All three fields are absent on rate-limit events that are not credits-required rejections. Requires Claude Code v2.1.181 or later.

5930 5931

5932On a warning about a plan usage limit, where `status` is `"allowed_warning"`, `overageEnabled` reports whether the account has [usage credits](https://code.claude.com/docs/en/costs.md#add-usage-credits-to-your-subscription) turned on. Requires Claude Code v2.1.295 or later.

5933

5931### `SDKLocalCommandOutputMessage`5934### `SDKLocalCommandOutputMessage`

5932 5935

5933Claude Code doesn't emit this message type. When you send a command such as `/context` or `/usage` as a prompt, its output arrives as an [`SDKAssistantMessage`](#sdkassistantmessage).5936Claude Code doesn't emit this message type. When you send a command such as `/context` or `/usage` as a prompt, its output arrives as an [`SDKAssistantMessage`](#sdkassistantmessage).

agent-teams.md +1 −1

Details

8 8

9> [!WARNING]9> [!WARNING]

10>10>

11> Agent teams are experimental and disabled by default. Enable them by setting `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in your [settings.json](https://code.claude.com/docs/en/settings.md) or environment. Without that variable, no team is set up at session start, no team directories are written, and Claude does not spawn or propose teammates. Agent teams have [known limitations](#limitations) around session resumption, task coordination, and shutdown behavior.11> Agent teams are experimental and disabled by default. Enable them by setting `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in your [settings.json](https://code.claude.com/docs/en/settings.md) or environment. Agent teams have [known limitations](#limitations) around session resumption, task coordination, and shutdown behavior.

12 12

13Agent teams let you coordinate multiple Claude Code instances working together. One session acts as the team lead, coordinating work, assigning tasks, and synthesizing results. Teammates work independently, each in its own context window, and communicate directly with each other. You can also talk to any teammate directly without going through the lead.13Agent teams let you coordinate multiple Claude Code instances working together. One session acts as the team lead, coordinating work, assigning tasks, and synthesizing results. Teammates work independently, each in its own context window, and communicate directly with each other. You can also talk to any teammate directly without going through the lead.

14 14

agent-view.md +3 −3

Details

169 169

170When the list is [grouped by directory](#organize-the-list), the summary opens with the session's state as a colored word, such as `Needs input · double jump or wall climb?`. In the default state grouping, the group header already names the state, so the row shows only the summary.170When the list is [grouped by directory](#organize-the-list), the summary opens with the session's state as a colored word, such as `Needs input · double jump or wall climb?`. In the default state grouping, the group header already names the state, so the row shows only the summary.

171 171

172The end-of-turn summary and each mid-turn rewrite are one short Haiku-class request through your normal provider, billed and handled under the same [data usage terms](https://code.claude.com/docs/en/data-usage.md) as the session itself. The 15-second updates between model rewrites reuse the session's own output and don't send a request. On a third-party provider or gateway with no Haiku-class model configured, the request uses the session's main model instead; set [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](https://code.claude.com/docs/en/model-config#environment-variables) to choose one.172#### Cost of row summaries

173

174The end-of-turn summary and each mid-turn rewrite are one short request through your normal provider, billed and handled under the same [data usage terms](https://code.claude.com/docs/en/data-usage.md) as the session itself. On a third-party provider or gateway, summaries use the model you set in [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](https://code.claude.com/docs/en/model-config#environment-variables). With it unset, they use your provider's model for background tasks: see [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md#4-pin-model-versions), [Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md#5-pin-model-versions), [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md#4-pin-model-versions), or your [gateway](https://code.claude.com/docs/en/llm-gateway-protocol.md#requests-and-defaults-by-connection-method).

173 175

174### Pull request status176### Pull request status

175 177

892 894

893The command also warns when the running supervisor is on a different version than the `claude` you invoked, which happens after an update the supervisor hasn't restarted into yet. The warning shows both versions and tells you to run `claude daemon stop --any` to pick up the new version.895The command also warns when the running supervisor is on a different version than the `claude` you invoked, which happens after an update the supervisor hasn't restarted into yet. The warning shows both versions and tells you to run `claude daemon stop --any` to pick up the new version.

894 896

895Sessions survive that version mismatch intact: an older Claude Code version that updates a session's `state.json` preserves fields it doesn't recognize and keeps the session listed. The session list in `roster.json` follows the same rule, so sessions started by the newer version stay reachable and keep accepting input after the supervisor restarts.

~~896~~

897### Turn off agent view897### Turn off agent view

898 898

899To turn off background agents and agent view entirely, set the `disableAgentView` [setting](https://code.claude.com/docs/en/settings.md) to `true` or set the `CLAUDE_CODE_DISABLE_AGENT_VIEW` environment variable. Administrators can enforce this through [managed settings](https://code.claude.com/docs/en/managed-settings.md).899To turn off background agents and agent view entirely, set the `disableAgentView` [setting](https://code.claude.com/docs/en/settings.md) to `true` or set the `CLAUDE_CODE_DISABLE_AGENT_VIEW` environment variable. Administrators can enforce this through [managed settings](https://code.claude.com/docs/en/managed-settings.md).

amazon-bedrock.md +1 −1

Details

367| `ap-*` | `apac.` |367| `ap-*` | `apac.` |

369 369

370Set `ANTHROPIC_BEDROCK_REGION_PREFIX` to choose the prefix Claude Code tries first; when Claude Code can check profile availability and finds no matching profile for a model, it falls back as described in the resolution order below. Valid values are `us`, `eu`, `apac`, `jp`, `au`, and `global`. For example, set it to `global` when your account has `global.` profiles enabled but Claude Code would derive a geography-specific one from your AWS region. Requires Claude Code v2.1.224 or later.370Set `ANTHROPIC_BEDROCK_REGION_PREFIX` to choose the prefix Claude Code tries first. Valid values are `us`, `eu`, `apac`, `jp`, `au`, and `global`. For example, set it to `global` when your account has `global.` profiles enabled but Claude Code would derive a geography-specific one from your AWS region.

371 371

372This example routes the default models through `global.` profiles:372This example routes the default models through `global.` profiles:

373 373

artifacts.md +19 −2

Details

64| :- | :- |64| :- | :- |

65| The session is in [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) | Asks before the first publish of each artifact |65| The session is in [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) | Asks before the first publish of each artifact |

66| The publish declares runtime capabilities for the page, such as [connector calls](#pull-live-data-with-mcp-connectors) or [file downloads](#offer-a-file-download) | Asks before that publish |66| The publish declares runtime capabilities for the page, such as [connector calls](#pull-live-data-with-mcp-connectors) or [file downloads](#offer-a-file-download) | Asks before that publish |

~~67| You shared the artifact publicly | Asks once per conversation before changing it |~~67| You shared the artifact publicly | Asks once per conversation before changing it, and before each reply to a comment on it |

68| Claude publishes in a turn that a [session-scoped scheduled task](https://code.claude.com/docs/en/scheduled-tasks.md) firing in your session started, rather than a prompt you typed | Asks before the first publish of each artifact |68| Claude publishes in a turn that a [session-scoped scheduled task](https://code.claude.com/docs/en/scheduled-tasks.md) firing in your session started, rather than a prompt you typed | Asks before the first publish of each artifact |

69| Claude can't read the file without your approval | Asks before publishing it. An allow rule for the `Artifact` tool doesn't skip this prompt |69| Claude can't read the file without your approval | Asks before publishing it. An allow rule for the `Artifact` tool doesn't skip this prompt |

70| In [Manual](https://code.claude.com/docs/en/permission-modes.md) or `acceptEdits` mode, Claude makes a small change to an artifact's file it can't edit without your approval, such as a project file in Manual mode | Asks before publishing the change. You're asked even if an allow rule covers the `Artifact` tool, because the edit to the file needs your approval |70| In [Manual](https://code.claude.com/docs/en/permission-modes.md) or `acceptEdits` mode, Claude makes a small change to an artifact's file it can't edit without your approval, such as a project file in Manual mode | Asks before publishing the change. You're asked even if an allow rule covers the `Artifact` tool, because the edit to the file needs your approval |

89Update https://claude.ai/code/artifact/5fbea6f3-... with today's numbers.89Update https://claude.ai/code/artifact/5fbea6f3-... with today's numbers.

90```90```

91 91

92### Turn off one-step artifact updates

94A one-step update is a small change Claude makes to an artifact's file as part of a publish, instead of through an `Edit` or `Write` call.

96To turn one-step updates off, set [`CLAUDE_CODE_ARTIFACT_PUBLISH_EDITS`](https://code.claude.com/docs/en/env-vars) to `0`. This example adds the variable to the `env` block in `~/.claude/settings.json`:

98```json theme={null}

99{

100 "env": {

101 "CLAUDE_CODE_ARTIFACT_PUBLISH_EDITS": "0"

102 }

103}

104```

105

106Then quit and relaunch Claude Code, because a running session doesn't reread the variable.

107

92## Find an artifact again108## Find an artifact again

93 109

94Run `/artifacts` in Claude Code to list the artifacts you own and the ones shared with you. The current session's artifacts come first, under **This session**.110Run `/artifacts` in Claude Code to list the artifacts you own and the ones shared with you. The current session's artifacts come first, under **This session**.

111Who you can share with depends on your plan:127Who you can share with depends on your plan:

112 128

113* **Within your organization**: on Team and Enterprise plans, grant access to specific people in your organization, or to everyone in it. Viewers sign in to claude.ai as members of your organization to see the page.129* **Within your organization**: on Team and Enterprise plans, grant access to specific people in your organization, or to everyone in it. Viewers sign in to claude.ai as members of your organization to see the page.

130* **People with access to a shared folder**: on Team and Enterprise plans, move the artifact to a folder that you own or are an editor of. Move it from the [Artifacts page](https://claude.ai/artifacts), which is available if you can use claude.ai chat. Everyone with access to the folder can then open it, and the folder's owner and editors can change it.

114* **Publicly**: share a link that anyone on the internet can open, with no claude.ai sign-in required. On Team and Enterprise plans, public sharing is off until an Owner [enables it for the organization](#control-public-sharing).131* **Publicly**: share a link that anyone on the internet can open, with no claude.ai sign-in required. On Team and Enterprise plans, public sharing is off until an Owner [enables it for the organization](#control-public-sharing).

115 132

116### Link to a specific view133### Link to a specific view

178Your [permission mode](https://code.claude.com/docs/en/permission-modes.md) decides what Claude does when a sent comment arrives:195Your [permission mode](https://code.claude.com/docs/en/permission-modes.md) decides what Claude does when a sent comment arrives:

179 196

180* **Claude replies on its own**: if you're in a permission mode that lets Claude post the reply without asking you, Claude reads the thread and replies. You see `Auto-replied to comment thread on Artifact: <name>`.197* **Claude replies on its own**: if you're in a permission mode that lets Claude post the reply without asking you, Claude reads the thread and replies. You see `Auto-replied to comment thread on Artifact: <name>`.

181* **Claude waits for you**: outside plan mode, when posting the reply would need your approval, you see `Comments are waiting on Artifact: <name>`. Claude then asks you for approval to read the thread, and again to post the reply.198* **Claude waits for you**: outside plan mode, when posting the reply [would need your approval](#when-claude-code-asks-before-publishing), you see `Comments are waiting on Artifact: <name>`. Claude then asks you for approval to read the thread, and again to post the reply.

182* **Claude pauses in plan mode**: you see `Comments are waiting on Artifact: <name>`, and Claude doesn't reply until you leave plan mode and ask it to read and reply.199* **Claude pauses in plan mode**: you see `Comments are waiting on Artifact: <name>`, and Claude doesn't reply until you leave plan mode and ask it to read and reply.

183 200

184Claude also stops replying on its own to an artifact after it handles 60 sent comments or thread activations on that artifact within an hour. You see `Comments are waiting on Artifact: <name>` once, and Claude picks up again as that hour's comments age out.201Claude also stops replying on its own to an artifact after it handles 60 sent comments or thread activations on that artifact within an hour. You see `Comments are waiting on Artifact: <name>` once, and Claude picks up again as that hour's comments age out.

auto-mode-classifier-billing.md +1 −1

Details

34* **Requests**: to let the checks through, the gateway forwards both the `anthropic-beta` header and the `safeguards` body field unchanged, because [the two travel as a pair](https://code.claude.com/docs/en/llm-gateway-protocol.md#beta-header-and-body-field-pairs). On the [Amazon Bedrock InvokeModel format](https://code.claude.com/docs/en/llm-gateway-protocol.md#api-formats), it forwards the `anthropic_beta` body field in place of the header.34* **Requests**: to let the checks through, the gateway forwards both the `anthropic-beta` header and the `safeguards` body field unchanged, because [the two travel as a pair](https://code.claude.com/docs/en/llm-gateway-protocol.md#beta-header-and-body-field-pairs). On the [Amazon Bedrock InvokeModel format](https://code.claude.com/docs/en/llm-gateway-protocol.md#api-formats), it forwards the `anthropic_beta` body field in place of the header.

35* **Responses**: the gateway returns responses and streaming events without dropping fields or rewriting tool-use IDs. To let the checks' results through, it keeps the `safeguard_results` field.35* **Responses**: the gateway returns responses and streaming events without dropping fields or rewriting tool-use IDs. To let the checks' results through, it keeps the `safeguard_results` field.

36 36

~~37A gateway that passes traffic through this way keeps working with this feature and with future ones. New sessions then use the server's checks again.~~37Once your gateway does this, new sessions use the server's checks again.

38 38

39If you already know that your gateway can't provide the server's checks, tell Claude Code not to ask for them there by setting `CLAUDE_CODE_AUTO_MODE_SERVER` to `0` before you start the session, in your shell or in the [`env` settings key](https://code.claude.com/docs/en/settings-reference#env):39If you already know that your gateway can't provide the server's checks, tell Claude Code not to ask for them there by setting `CLAUDE_CODE_AUTO_MODE_SERVER` to `0` before you start the session, in your shell or in the [`env` settings key](https://code.claude.com/docs/en/settings-reference#env):

40 40

auto-mode-config.md +4 −4

Details

180 180

181Claude Code scans in the background, then shows you the draft. You accept or discard it as a whole, so edit `~/.claude/settings.json` afterwards to adjust single entries. When you accept, Claude Code writes the draft and reconciles it with the settings you already have:181Claude Code scans in the background, then shows you the draft. You accept or discard it as a whole, so edit `~/.claude/settings.json` afterwards to adjust single entries. When you accept, Claude Code writes the draft and reconciles it with the settings you already have:

182 182

183* Claude Code writes the `environment` list without `"$defaults"`, because the draft spells out the built-in entries it left unchanged183* If you chose to add to the `environment` list in `~/.claude/settings.json`, you keep any `"$defaults"` entry in it. If you chose to replace that list, you lose that entry, so add `"$defaults"` back if you want the default entries

184* Claude Code includes `"$defaults"` in each of the `allow`, `soft_deny`, and `hard_deny` lists the draft adds entries to, unless you already wrote an `allow` list without it, so the [built-in rules](#override-the-block-and-allow-rules) you haven't replaced stay in effect184* Claude Code includes `"$defaults"` in each of the `allow`, `soft_deny`, and `hard_deny` lists the draft adds entries to, unless you already wrote an `allow` list without it, so the [built-in rules](#override-the-block-and-allow-rules) you haven't replaced stay in effect

185* After saving, Claude Code offers to remove `permissions.allow` rules in `~/.claude/settings.json` that auto mode ignores, such as `Bash(*)`, or that auto-approve destructive commands185* After saving, Claude Code offers to remove `permissions.allow` rules in `~/.claude/settings.json` that auto mode ignores, such as `Bash(*)`, or that auto-approve destructive commands

186 186

216 216

217Three additional fields let you replace the classifier's built-in rule lists:217Three additional fields let you replace the classifier's built-in rule lists:

218 218

219* `autoMode.hard_deny`: unconditional security boundaries219* `autoMode.hard_deny`: actions to block even when the user asks for them

220* `autoMode.soft_deny`: destructive actions that user intent can clear220* `autoMode.soft_deny`: destructive actions that user intent can clear

221* `autoMode.allow`: exceptions to soft block rules221* `autoMode.allow`: exceptions to soft block rules

222 222

231 231

232General requests don't count as explicit intent. Asking Claude to "clean up the repo" doesn't authorize force-pushing, but asking Claude to "force-push this branch" does.232General requests don't count as explicit intent. Asking Claude to "clean up the repo" doesn't authorize force-pushing, but asking Claude to "force-push this branch" does.

233 233

234To loosen, add to `allow` when the classifier repeatedly flags a routine pattern the default exceptions don't cover. To tighten, add to `soft_deny` for destructive risks specific to your environment that the defaults miss, or to `hard_deny` for security boundaries that must never be crossed.234To loosen, add to `allow` when the classifier repeatedly flags a routine pattern the default exceptions don't cover. To tighten, add to `soft_deny` for destructive risks specific to your environment that the defaults miss, or to `hard_deny` for actions to block even when the user asks for them.

235 235

236To keep the built-in rules while adding your own, include the literal string `"$defaults"` in the array. The default rules are spliced in at that position, so your custom rules can go before or after them, and you continue to inherit updates as the built-in list changes across releases.236To keep the built-in rules while adding your own, include the literal string `"$defaults"` in the array. The default rules are spliced in at that position, so your custom rules can go before or after them, and you continue to inherit updates as the built-in list changes across releases.

237 237

252 "soft_deny": [252 "soft_deny": [

253 "$defaults",253 "$defaults",

254 "Never run database migrations outside the migrations CLI, even against dev databases",254 "Never run database migrations outside the migrations CLI, even against dev databases",

255 "Never modify files under infra/terraform/prod/: production infrastructure changes go through the review workflow"255 "Running terraform apply in infra/terraform/prod/ needs an explicit request: production infrastructure changes go through the review workflow"

256 ],256 ],

257 "hard_deny": [257 "hard_deny": [

258 "$defaults",258 "$defaults",

claude-apps-gateway.md +1 −1

Details

313>313>

314> `gatewayInternalNetworks` is for internal networks that happen to be numbered from public address space. It doesn't make it safe to expose a gateway to the internet: a trusted gateway can push settings that run commands on developer machines.314> `gatewayInternalNetworks` is for internal networks that happen to be numbered from public address space. It doesn't make it safe to expose a gateway to the internet: a trusted gateway can push settings that run commands on developer machines.

315>315>

316> Keep the gateway unreachable from outside your network with your firewall or load balancer rules. Set the gateway's [`access_control.allow_cidrs`](https://code.claude.com/docs/en/claude-apps-gateway-config#http-tuning) to the same blocks you declare here, so the gateway itself refuses clients from anywhere else. Behind a load balancer or ingress, set `listen.trusted_proxies` to that front end as well, because the gateway otherwise matches `allow_cidrs` against the front end's own address rather than the developer's.316> Keep the gateway unreachable from outside your network with your firewall or load balancer rules. Set the gateway's [`access_control.allow_cidrs`](https://code.claude.com/docs/en/claude-apps-gateway-config#http-tuning) to the same blocks you declare here. If a load balancer or ingress [belongs in `listen.trusted_proxies`](https://code.claude.com/docs/en/claude-apps-gateway-config#listen), list it there as well, because the gateway otherwise matches `allow_cidrs` against the frontend's own address rather than the developer's.

317 317

318Add the key to the same managed settings source as the login keys: the managed settings file, MDM profile, or registry policy. Claude Code ignores it in user, project, and server-managed settings.318Add the key to the same managed settings source as the login keys: the managed settings file, MDM profile, or registry policy. Claude Code ignores it in user, project, and server-managed settings.

319 319

claude-apps-gateway-config.md +6 −2

Details

59| `port` | No | Bind port. Default `8080`. |59| `port` | No | Bind port. Default `8080`. |

60| `public_url` | Unless `host` is loopback | The externally visible `https://` origin, used to build the IdP `redirect_uri` and discovery metadata. Required whenever `host` isn't a loopback address, whether TLS terminates at a proxy such as an ALB, Ingress, or Cloud Run or at the gateway itself through `tls`, because the gateway never derives its own origin from `X-Forwarded-*` headers; they are client-spoofable. Boot fails without it. `trusted_proxies` below governs client-IP resolution only. Also required to enable [telemetry](#telemetry), because the gateway builds the OTLP endpoint it pushes to clients from this URL. |60| `public_url` | Unless `host` is loopback | The externally visible `https://` origin, used to build the IdP `redirect_uri` and discovery metadata. Required whenever `host` isn't a loopback address, whether TLS terminates at a proxy such as an ALB, Ingress, or Cloud Run or at the gateway itself through `tls`, because the gateway never derives its own origin from `X-Forwarded-*` headers; they are client-spoofable. Boot fails without it. `trusted_proxies` below governs client-IP resolution only. Also required to enable [telemetry](#telemetry), because the gateway builds the OTLP endpoint it pushes to clients from this URL. |

61| `tls.cert` / `tls.key` | No | PEM paths if the gateway terminates TLS itself |61| `tls.cert` / `tls.key` | No | PEM paths if the gateway terminates TLS itself |

62| `trusted_proxies` | No | CIDRs or IPs of load balancers in front of the gateway. When set, the gateway trusts `X-Forwarded-For` only from these peers and records the real client IP for per-IP rate limiting and audit. Equivalent to nginx `set_real_ip_from`. `X-Forwarded-For` entries written as `ipv4:port` or `[ipv6]:port`, as some load balancers do, are read with the port dropped. An IPv6 address with a port appended and no brackets may be read as a different address or not read at all, so turn off the port option on any proxy that writes that form. |62| `trusted_proxies` | No | CIDRs or IPs of the frontends to trust. When set, the gateway trusts `X-Forwarded-For` only from these peers and records the real client IP for per-IP rate limiting and audit. |

64List a frontend in `trusted_proxies` only if the last `X-Forwarded-For` entry that it passes on is one that no developer wrote. List no address or range that developers connect from. A frontend that appends the address of each connection it receives qualifies. One that passes the header on as developers send it doesn't.

66`X-Forwarded-For` entries written as `ipv4:port` or `[ipv6]:port`, as some load balancers do, are read with the port dropped. An IPv6 address with a port appended and no brackets may be read as a different address or not read at all. Turn off the port option on any proxy that writes that form.

63 67

64### `oidc`68### `oidc`

65 69

1659 1663

1660Both signals use the client address as the gateway resolves it. If a load balancer, port-forward, or tunnel relays traffic and isn't listed in `listen.trusted_proxies`, the gateway sees the relay's address, which is usually private, so neither the runtime warning nor a private allow list catches traffic relayed through it.1664Both signals use the client address as the gateway resolves it. If a load balancer, port-forward, or tunnel relays traffic and isn't listed in `listen.trusted_proxies`, the gateway sees the relay's address, which is usually private, so neither the runtime warning nor a private allow list catches traffic relayed through it.

1661 1665

1662Behind such a front end, set [`listen.trusted_proxies`](#listen) first so the gateway sees real client addresses, and keep the gateway and everything in front of it unreachable from the public internet regardless.1666If the relay [belongs in `listen.trusted_proxies`](#listen), list it there. Keep the gateway and everything in front of it unreachable from the public internet regardless.

1663 1667

1664### `load_test_mode`1668### `load_test_mode`

1665 1669

claude-apps-gateway-deploy.md +2 −2

Details

131 131

132Sign-in is rate limited per client IP address, and the defaults suit a small team. Each address gets 30 sign-in starts and 10 code submissions every 10 minutes. A rollout to thousands of developers can reach those limits on the first morning, for one of two reasons:132Sign-in is rate limited per client IP address, and the defaults suit a small team. Each address gets 30 sign-in starts and 10 code submissions every 10 minutes. A rollout to thousands of developers can reach those limits on the first morning, for one of two reasons:

133 133

134* **The gateway can't see past your load balancer.** Without [`listen.trusted_proxies`](https://code.claude.com/docs/en/claude-apps-gateway-config#listen), every developer appears to come from the load balancer's address and shares one limit. Set it before anything else. The gateway logs a warning the first time it ignores an `X-Forwarded-For` header.134* **The gateway can't see past your load balancer.** Without [`listen.trusted_proxies`](https://code.claude.com/docs/en/claude-apps-gateway-config#listen), every developer appears to come from the load balancer's address and shares one limit. The gateway logs a warning the first time it ignores an `X-Forwarded-For` header. If the load balancer [belongs in `listen.trusted_proxies`](https://code.claude.com/docs/en/claude-apps-gateway-config#listen), list it before you change anything else. If developers still share one address, raise [`rate_limits`](https://code.claude.com/docs/en/claude-apps-gateway-config#http-tuning).

135* **Many developers share a few NAT or VPN egress addresses.** They share those addresses' limits even when `trusted_proxies` is right. Raise [`rate_limits`](https://code.claude.com/docs/en/claude-apps-gateway-config#http-tuning) to fit.135* **Many developers share a few NAT or VPN egress addresses.** They share those addresses' limits even when `trusted_proxies` is right. Raise [`rate_limits`](https://code.claude.com/docs/en/claude-apps-gateway-config#http-tuning) to fit.

136 136

137To size `max`, divide the developers by the egress addresses they share. Estimate how many of those sign in within one `window_seconds` period, which is 10 minutes by default. Then double it to cover retries and developers who sign in to both Claude Code and Claude Desktop.137To size `max`, divide the developers by the egress addresses they share. Estimate how many of those sign in within one `window_seconds` period, which is 10 minutes by default. Then double it to cover retries and developers who sign in to both Claude Code and Claude Desktop.

418| Startup shows `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | The installed Claude Code build predates gateway support | Have the developer update Claude Code to a release that includes Cloud gateway support |418| Startup shows `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | The installed Claude Code build predates gateway support | Have the developer update Claude Code to a release that includes Cloud gateway support |

419| Startup exits with `Administrator policy requires a Cloud gateway sign-in on this machine` | The developer's environment sets `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN`, their settings configure an [`apiKeyHelper`](https://code.claude.com/docs/en/settings-reference#apikeyhelper), or an API key from an earlier Claude Console login is still saved | Have the developer clear each that applies: unset the variable, remove the `apiKeyHelper` entry, or run `claude auth logout` to remove the saved key. A session that selects a cloud provider with `CLAUDE_CODE_USE_*` then starts with no sign-in; for every other session, have them start `claude` and sign in with `/login`. See also [Administrator policy requires a Cloud gateway sign-in](https://code.claude.com/docs/en/errors.md#administrator-policy-requires-a-cloud-gateway-sign-in). |419| Startup exits with `Administrator policy requires a Cloud gateway sign-in on this machine` | The developer's environment sets `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN`, their settings configure an [`apiKeyHelper`](https://code.claude.com/docs/en/settings-reference#apikeyhelper), or an API key from an earlier Claude Console login is still saved | Have the developer clear each that applies: unset the variable, remove the `apiKeyHelper` entry, or run `claude auth logout` to remove the saved key. A session that selects a cloud provider with `CLAUDE_CODE_USE_*` then starts with no sign-in; for every other session, have them start `claude` and sign in with `/login`. See also [Administrator policy requires a Cloud gateway sign-in](https://code.claude.com/docs/en/errors.md#administrator-policy-requires-a-cloud-gateway-sign-in). |

420| Startup or `/login` reports `Claude Code may not be enabled for your organization` after a 403 on the managed settings load | The gateway, or something in front of it, answered the `/managed/settings` request with 403. The gateway's own settings route never answers 403. The status comes from the [`access_control`](https://code.claude.com/docs/en/claude-apps-gateway-config#http-tuning) IP checks or from a proxy or WAF in front of the gateway. The audit log records an IP-check denial as `access.denied` with the reason. The developer stays signed in. | Check the audit log for `access.denied` at the time of the failure and fix the `access_control` lists or the front end, then have the developer start `claude` again |420| Startup or `/login` reports `Claude Code may not be enabled for your organization` after a 403 on the managed settings load | The gateway, or something in front of it, answered the `/managed/settings` request with 403. The gateway's own settings route never answers 403. The status comes from the [`access_control`](https://code.claude.com/docs/en/claude-apps-gateway-config#http-tuning) IP checks or from a proxy or WAF in front of the gateway. The audit log records an IP-check denial as `access.denied` with the reason. The developer stays signed in. | Check the audit log for `access.denied` at the time of the failure and fix the `access_control` lists or the front end, then have the developer start `claude` again |

421| CLI `/login`: `The gateway is limiting sign-in attempts right now`, or `Request failed with status code 429` on older versions. The `/device` page may show `Too many attempts` to developers who haven't tried before | The per-IP sign-in rate limit was reached. Either `listen.trusted_proxies` doesn't cover the load balancer, so every developer shares its address, or many developers share a NAT or VPN egress address. Audit events with `result: rate_limited` show the same one or few `client_ip` values. | Set `listen.trusted_proxies` to the load balancer's source ranges first, then raise `rate_limits` if developers still share addresses. See [Large rollouts](#large-rollouts). |421| CLI `/login`: `The gateway is limiting sign-in attempts right now`, or `Request failed with status code 429` on older versions. The `/device` page may show `Too many attempts` to developers who haven't tried before | The per-IP sign-in rate limit was reached. Either `listen.trusted_proxies` doesn't cover the load balancer, so every developer shares its address, or many developers share a NAT or VPN egress address. Audit events with `result: rate_limited` show the same one or few `client_ip` values. | If the load balancer [belongs in `listen.trusted_proxies`](https://code.claude.com/docs/en/claude-apps-gateway-config#listen), list it first. Then raise `rate_limits` if developers still share addresses. See [Large rollouts](#large-rollouts). |

422| CLI `/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | The gateway hostname resolves to at least one public IP address. Claude Code checks each resolved address and requires every one to be private. A common cause is a dual-stack name where one family resolves to a public address, including AWS internal dual-stack load balancers, which return public-range AAAA addresses. | Have the gateway name resolve only to private addresses on developer machines. For a dual-stack name, drop the public-range record or serve a separate internal-only DNS name. See the [private-network prerequisite](https://code.claude.com/docs/en/claude-apps-gateway#prerequisites). If the address is public space your organization owns and uses internally, [declare that block](https://code.claude.com/docs/en/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own) instead. |422| CLI `/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | The gateway hostname resolves to at least one public IP address. Claude Code checks each resolved address and requires every one to be private. A common cause is a dual-stack name where one family resolves to a public address, including AWS internal dual-stack load balancers, which return public-range AAAA addresses. | Have the gateway name resolve only to private addresses on developer machines. For a dual-stack name, drop the public-range record or serve a separate internal-only DNS name. See the [private-network prerequisite](https://code.claude.com/docs/en/claude-apps-gateway#prerequisites). If the address is public space your organization owns and uses internally, [declare that block](https://code.claude.com/docs/en/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own) instead. |

423| CLI `/login`: `Gateway login would go through proxy <proxy>, which is not on a private network` | An `HTTPS_PROXY` or `HTTP_PROXY` applies to the gateway host and the proxy's hostname resolves to a public address. A proxy whose host resolves only to private addresses is allowed and doesn't trigger this error | Add the gateway host to `NO_PROXY` on the developer's machine so the connection is direct, or use a proxy whose hostname resolves to private addresses. The message names the exact `NO_PROXY` entry to add |423| CLI `/login`: `Gateway login would go through proxy <proxy>, which is not on a private network` | An `HTTPS_PROXY` or `HTTP_PROXY` applies to the gateway host and the proxy's hostname resolves to a public address. A proxy whose host resolves only to private addresses is allowed and doesn't trigger this error | Add the gateway host to `NO_PROXY` on the developer's machine so the connection is direct, or use a proxy whose hostname resolves to private addresses. The message names the exact `NO_PROXY` entry to add |

424| CLI `/login`: `Claude Code only signs in to <host> from inside its declared network <block> (managed settings), and this machine is connecting from <ip>, outside it` | The gateway is on a block declared in [`gatewayInternalNetworks`](https://code.claude.com/docs/en/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own), and the developer's machine reached it from an address outside that block: a VPN address pool, a container or WSL2 NAT segment, or a network that isn't yours | Have the developer run `/login` from the host OS on your network. If the address shown is also your organization's own public space, replace the gateway's entry with a block that covers both, up to `/8`; a second, overlapping entry is refused. If no block covers both, see [Choose an address for the gateway](#choose-an-address-for-the-gateway) |424| CLI `/login`: `Claude Code only signs in to <host> from inside its declared network <block> (managed settings), and this machine is connecting from <ip>, outside it` | The gateway is on a block declared in [`gatewayInternalNetworks`](https://code.claude.com/docs/en/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own), and the developer's machine reached it from an address outside that block: a VPN address pool, a container or WSL2 NAT segment, or a network that isn't yours | Have the developer run `/login` from the host OS on your network. If the address shown is also your organization's own public space, replace the gateway's entry with a block that covers both, up to `/8`; a second, overlapping entry is refused. If no block covers both, see [Choose an address for the gateway](#choose-an-address-for-the-gateway) |

claude-apps-gateway-spend-limits.md +1 −1

Details

763. List price for the [`models[].id`](https://code.claude.com/docs/en/claude-apps-gateway-config#models) you mapped to that upstream ID, for upstream strings that carry no model name, such as an Amazon Bedrock application-inference-profile ARN or a Microsoft Foundry deployment name. Requires v2.1.218 or later.763. List price for the [`models[].id`](https://code.claude.com/docs/en/claude-apps-gateway-config#models) you mapped to that upstream ID, for upstream strings that carry no model name, such as an Amazon Bedrock application-inference-profile ARN or a Microsoft Foundry deployment name. Requires v2.1.218 or later.

774. The unknown-model tier of \$5/\$25 per million input/output tokens, so an ID the meter can't place is never free. The gateway warns at boot and once per ID at runtime when it uses this tier.774. The unknown-model tier of \$5/\$25 per million input/output tokens, so an ID the meter can't place is never free. The gateway warns at boot and once per ID at runtime when it uses this tier.

78 78

~~79Whichever rate applies, the meter then multiplies the amount by [`pricing.multiplier`](https://code.claude.com/docs/en/claude-apps-gateway-config#pricing), default `1`.~~79Whichever rate applies, the meter then multiplies the amount by [`pricing.multiplier`](https://code.claude.com/docs/en/claude-apps-gateway-config#pricing), default `1`. Requires a gateway server running Claude Code v2.1.227 or later.

80 80

81Client aborts are billed too. When a stream ends without the upstream's final usage frame, the meter bills a floor estimate of about four characters per output token for the text already sent to the client, so aborting requests early doesn't evade a cap.81Client aborts are billed too. When a stream ends without the upstream's final usage frame, the meter bills a floor estimate of about four characters per output token for the text already sent to the client, so aborting requests early doesn't evade a cap.

82 82

claude-code-on-the-web.md +2 −5

Details

36 36

37Every cloud session runs in a [cloud environment](https://code.claude.com/docs/en/cloud-environments.md), the saved configuration that controls network access, environment variables, and setup scripts.37Every cloud session runs in a [cloud environment](https://code.claude.com/docs/en/cloud-environments.md), the saved configuration that controls network access, environment variables, and setup scripts.

38 38

39* **Your first environment**: if you don't have one yet, onboarding sets up a **Default** environment with [**Trusted** network access](https://code.claude.com/docs/en/cloud-environments.md#access-levels), either by creating it for you or by asking you to create it. See [The Default environment](https://code.claude.com/docs/en/cloud-environments.md#the-default-environment) for which of those happens on your plan39* **Your first environment**: if you don't have one yet, onboarding sets up a **Default** environment with [**Limited** network access](https://code.claude.com/docs/en/cloud-environments.md#access-levels). See [The Default environment](https://code.claude.com/docs/en/cloud-environments.md#the-default-environment) for how that works on your plan

40* **Which environment a session uses**: see [The Default environment](https://code.claude.com/docs/en/cloud-environments.md#the-default-environment) for how sessions choose an environment when you have more than one40* **Which environment a session uses**: see [The Default environment](https://code.claude.com/docs/en/cloud-environments.md#the-default-environment) for how sessions choose an environment when you have more than one

41* **Change what sessions can reach or run at startup**: see [Configure cloud environments](https://code.claude.com/docs/en/cloud-environments.md)41* **Change what sessions can reach or run at startup**: see [Configure cloud environments](https://code.claude.com/docs/en/cloud-environments.md)

42* **What's installed without any configuration**: see [Installed tools](https://code.claude.com/docs/en/cloud-environments.md#installed-tools)42* **What's installed without any configuration**: see [Installed tools](https://code.claude.com/docs/en/cloud-environments.md#installed-tools)

205* **Using `/teleport`**: inside an existing CLI session, run `/teleport` or `/tp` to open the same session picker without restarting Claude Code.205* **Using `/teleport`**: inside an existing CLI session, run `/teleport` or `/tp` to open the same session picker without restarting Claude Code.

206* **From `/tasks`**: run `/tasks` to see your background sessions, then press `t` to teleport into one.206* **From `/tasks`**: run `/tasks` to see your background sessions, then press `t` to teleport into one.

207* **From claude.ai/code**: select **Open in > Terminal** from the session menu to copy a command you can paste into your terminal.207* **From claude.ai/code**: select **Open in > Terminal** from the session menu to copy a command you can paste into your terminal.

208* **From inside the cloud session**: type `/teleport` and Claude Code replies with the exact `claude --teleport <session-id>` command for that session, ready to run from a checkout of the repository. Requires Claude Code v2.1.223 or later in the session's environment.208* **From inside the cloud session**: type `/teleport` and Claude Code replies with the exact `claude --teleport <session-id>` command for that session, ready to run from a checkout of the repository.

209 209

210When you teleport a session, Claude verifies you're in the correct repository, fetches and checks out the branch from the cloud session, and loads the conversation into your terminal.210When you teleport a session, Claude verifies you're in the correct repository, fetches and checks out the branch from the cloud session, and loads the conversation into your terminal.

211 211

499* **Repository authentication**: you can only pull a cloud session into your terminal when you are authenticated to the same account499* **Repository authentication**: you can only pull a cloud session into your terminal when you are authenticated to the same account

500* **Platform restrictions**: repository cloning in Anthropic-hosted environments and pull request creation require GitHub. Self-hosted [GitHub Enterprise Server](https://code.claude.com/docs/en/github-enterprise-server.md) instances are supported for Team and Enterprise plans. You can send a GitLab, Bitbucket, or other non-GitHub repository to a cloud session as a [local bundle](#send-local-repositories-without-github) by setting `CCR_FORCE_BUNDLE=1`, but the session can't push results back to that remote500* **Platform restrictions**: repository cloning in Anthropic-hosted environments and pull request creation require GitHub. Self-hosted [GitHub Enterprise Server](https://code.claude.com/docs/en/github-enterprise-server.md) instances are supported for Team and Enterprise plans. You can send a GitLab, Bitbucket, or other non-GitHub repository to a cloud session as a [local bundle](#send-local-repositories-without-github) by setting `CCR_FORCE_BUNDLE=1`, but the session can't push results back to that remote

501 * **Self-hosted environments**: for a repository on another git host, see the [requirements for starting a session with `--environment`](https://code.claude.com/docs/en/self-hosted-environments-deploy#start-a-session-on-a-repository-outside-github).501 * **Self-hosted environments**: for a repository on another git host, see the [requirements for starting a session with `--environment`](https://code.claude.com/docs/en/self-hosted-environments-deploy#start-a-session-on-a-repository-outside-github).

502* **Organization IP allowlist**: cloud sessions call the Anthropic API from Anthropic-managed infrastructure, not your network, while sessions in a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments) call it from your own network. If your organization has [IP allowlisting](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting) enabled, every Anthropic-hosted cloud session fails with an authentication error.

503 * **Code Review and scheduled tasks**: the same applies to [Code Review](https://code.claude.com/docs/en/code-review.md) and to [cloud scheduled tasks](https://code.claude.com/docs/en/routines.md) that run on Anthropic-hosted environments. A scheduled task routed to a self-hosted environment calls the API from your own network.

504 * **Getting an exemption**: contact [Anthropic support](https://support.claude.com/) to exempt Anthropic-hosted services from your organization's IP allowlist.

505 502

506## Related resources503## Related resources

507 504

claude-directory.md +4 −1

Details

142Session files in `sessions/`, auto memory, and Claude Desktop and Cowork transcripts each follow their own retention rule:142Session files in `sessions/`, auto memory, and Claude Desktop and Cowork transcripts each follow their own retention rule:

143 143

144* **`sessions/`**: holds one small file per running session, used to detect concurrent sessions and crashes. It isn't part of the age-based sweep: Claude Code removes each file when its session exits and clears crash leftovers on the next launch.144* **`sessions/`**: holds one small file per running session, used to detect concurrent sessions and crashes. It isn't part of the age-based sweep: Claude Code removes each file when its session exits and clears crash leftovers on the next launch.

145* **`seed-admin/`**: scratch git directories Claude Code makes while packaging your repository for an [ultrareview](https://code.claude.com/docs/en/ultrareview.md) or a [cloud session upload](https://code.claude.com/docs/en/claude-code-on-the-web.md#send-local-repositories-without-github). When an upload ends, or in a later session if it was interrupted, Claude Code removes that upload's directory and leaves `seed-admin/` in place.

145* **Auto memory**: the sweep doesn't delete the memory files in a project's [auto memory](https://code.claude.com/docs/en/memory.md#auto-memory) directory, `projects/<project>/memory/`. Claude Code removes that directory only if it has been empty for the whole retention period. Before v2.1.228, the sweep treated folders inside the memory directory as session data and could delete old files beneath it.146* **Auto memory**: the sweep doesn't delete the memory files in a project's [auto memory](https://code.claude.com/docs/en/memory.md#auto-memory) directory, `projects/<project>/memory/`. Claude Code removes that directory only if it has been empty for the whole retention period. Before v2.1.228, the sweep treated folders inside the memory directory as session data and could delete old files beneath it.

146* **Claude Desktop and Cowork transcripts**: Claude Code keeps the transcript of a session you started or most recently continued in Claude Desktop or Cowork at any age. To give these transcripts an age limit, set [`desktopSessionCleanupPeriodDays`](https://code.claude.com/docs/en/settings-reference#desktopsessioncleanupperioddays). Requires Claude Code v2.1.248 or later; earlier versions delete them after `cleanupPeriodDays`.147* **Claude Desktop and Cowork transcripts**: Claude Code keeps the transcript of a session you started or most recently continued in Claude Desktop or Cowork at any age. To give these transcripts an age limit, set [`desktopSessionCleanupPeriodDays`](https://code.claude.com/docs/en/settings-reference#desktopsessioncleanupperioddays). Requires Claude Code v2.1.248 or later; earlier versions delete them after `cleanupPeriodDays`.

147 148

153Claude Code skips the age-based sweep in these cases:154Claude Code skips the age-based sweep in these cases:

154 155

155* **Bare mode**: when you run `claude -p` with [`--bare`](https://code.claude.com/docs/en/headless#start-faster-with-bare-mode), Claude Code doesn't run the sweep in that session.156* **Bare mode**: when you run `claude -p` with [`--bare`](https://code.claude.com/docs/en/headless#start-faster-with-bare-mode), Claude Code doesn't run the sweep in that session.

156* **Paused sweep**: if Claude Code can't safely determine the retention period, it pauses the retention cleanup sweep; the [`retention_sweep` event](https://code.claude.com/docs/en/monitoring-usage#retention-sweep-event) lists each configuration that pauses it. When the cause is a settings file that can't be read or parsed, or settings errors with `cleanupPeriodDays` or `desktopSessionCleanupPeriodDays` explicitly set, Claude Code also shows a warning in `/status` until you fix the settings errors. When [managed settings](https://code.claude.com/docs/en/server-managed-settings.md) provide `cleanupPeriodDays`, Claude Code runs the sweep at the managed value in either case.157* **Paused sweep**: if Claude Code can't safely determine the retention period, it pauses the sweep; the [`retention_sweep` event](https://code.claude.com/docs/en/monitoring-usage#retention-sweep-event) lists each configuration that pauses it. When the cause is a settings file that can't be read or parsed, or settings errors with `cleanupPeriodDays` or `desktopSessionCleanupPeriodDays` set, `/status` shows a warning until you fix the cause.

158

159When [managed settings](https://code.claude.com/docs/en/managed-settings.md) provide `cleanupPeriodDays`, Claude Code runs the sweep at the managed value even when a lower-priority settings file has errors.

157 160

158To check that the machines in your organization run the sweep with the retention period you set, see [Check the retention sweep](https://code.claude.com/docs/en/monitoring-usage.md#check-the-retention-sweep).161To check that the machines in your organization run the sweep with the retention period you set, see [Check the retention sweep](https://code.claude.com/docs/en/monitoring-usage.md#check-the-retention-sweep).

159 162

claude-platform-on-aws.md +2 −2

Details

8 8

9Claude Platform on AWS is the Anthropic-operated Claude API with AWS authentication, IAM access control, and AWS Marketplace billing. Requests reach Anthropic's API directly, so you get the same models and API features as the [Claude API](https://platform.claude.com/docs) on the same release schedule. You authenticate with AWS credentials or a workspace API key, and you pay through AWS Marketplace.9Claude Platform on AWS is the Anthropic-operated Claude API with AWS authentication, IAM access control, and AWS Marketplace billing. Requests reach Anthropic's API directly, so you get the same models and API features as the [Claude API](https://platform.claude.com/docs) on the same release schedule. You authenticate with AWS credentials or a workspace API key, and you pay through AWS Marketplace.

10 10

11Client-side features that Claude Code turns on through Anthropic's feature-flag service are off by default, and the [advisor tool](https://code.claude.com/docs/en/advisor.md) isn't available. See the [feature availability matrix](https://code.claude.com/docs/en/feature-availability.md#summary-by-provider) for the full list.

13Use this guide to point Claude Code at a workspace you've already provisioned through Claude Platform on AWS. For the AWS subscription and workspace setup that comes before this, see the [Claude Platform on AWS documentation](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws).11Use this guide to point Claude Code at a workspace you've already provisioned through Claude Platform on AWS. For the AWS subscription and workspace setup that comes before this, see the [Claude Platform on AWS documentation](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws).

14 12

15> [!NOTE]13> [!NOTE]

16>14>

17> Subscribing through AWS Marketplace provisions a new Anthropic organization tied to your AWS account. This organization is separate from any organization you already have with Anthropic, and credentials don't transfer between them. Use the workspace ID and API keys from the AWS-linked organization, not from a pre-existing Claude Console account.15> Subscribing through AWS Marketplace provisions a new Anthropic organization tied to your AWS account. This organization is separate from any organization you already have with Anthropic, and credentials don't transfer between them. Use the workspace ID and API keys from the AWS-linked organization, not from a pre-existing Claude Console account.

18 16

17Some Claude Code features are unavailable or work differently on Claude Platform on AWS. See the [feature availability matrix](https://code.claude.com/docs/en/feature-availability.md#summary-by-provider) and the [features that need feature-flag fetching](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching).

19## Prerequisites19## Prerequisites

20 20

21Before configuring Claude Code, you need:21Before configuring Claude Code, you need:

claude-projects.md +24 −26

Details

20 20

21* **Send work to one place**: paste a bug report, a stack trace, or a list of tasks into the conversation whenever one comes up. Claude starts a thread for each piece of work or passes it to the thread already working in that area, and answers quick questions in place.21* **Send work to one place**: paste a bug report, a stack trace, or a list of tasks into the conversation whenever one comes up. Claude starts a thread for each piece of work or passes it to the thread already working in that area, and answers quick questions in place.

22* **Set context once**: every new thread starts with the project's instructions, so a rule you state once, such as which branch to target, reaches all of them.22* **Set context once**: every new thread starts with the project's instructions, so a rule you state once, such as which branch to target, reaches all of them.

23* **Walk away and come back to finished work**: when you come back an hour later or the next morning, the **Overview** pane shows which threads finished, which pull requests are ready for review, and which thread is waiting for your answer.23* **Walk away and come back to finished work**: the Overview pane shows which threads finished, which pull requests are ready for review, and which thread is waiting for your answer.

24 24

25If you already know the work you want a project to run, go straight to [Create a project](#create-a-project).25If you already know the work you want a project to run, go straight to [Create a project](#create-a-project).

26 26

28 28

29A project is worth creating when the work has a goal that outlasts one session and keeps producing tasks. These kinds of work suit a project well:29A project is worth creating when the work has a goal that outlasts one session and keeps producing tasks. These kinds of work suit a project well:

30 30

31* **One goal across many repositories**: "Bring every service up to the new lint config." Claude can run a thread per repository, each with its own pull request, and the [**Overview** pane](#see-what-needs-you-in-overview) shows which ones are ready for review.31* **One goal across many repositories**: "Bring every service up to the new lint config." Claude can run a thread per repository, each with its own pull request, and the [Overview pane](#see-what-needs-you-in-overview) shows which ones are ready for review.

32* **An area you keep feeding**: the bugs, stack traces, and review requests for one service, pasted into the conversation as they reach you. A pitfall you tell Claude to remember after one fix is in [project memory](#give-a-project-standing-context) for the next.32* **An area you keep feeding**: the bugs, stack traces, and review requests for one service, pasted into the conversation as they reach you. A pitfall you tell Claude to remember after one fix is in [project memory](#give-a-project-standing-context) for the next.

33* **A build or migration bigger than a session**: "Build what `docs/spec.md` describes" or "Move the app off the deprecated ORM." The work splits into threads that each take a part, decisions you ask Claude to remember early on reach the later cloud threads, and the spec changes and bugs you find during the build go into the same conversation.33* **A build or migration bigger than a session**: "Build what `docs/spec.md` describes" or "Move the app off the deprecated ORM." The work splits into threads that each take a part, decisions you ask Claude to remember early on reach the later cloud threads, and the spec changes and bugs you find during the build go into the same conversation.

34* **Work that isn't code**: a folder of contracts or a support-ticket export you keep coming back to with new questions, such as "find the ten most common integration mistakes in these tickets." Upload the documents instead of adding a repository, and threads deliver each write-up as a file on the project's [**Library** tab](#see-what-needs-you-in-overview).34* **Work that isn't code**: a folder of contracts or a support-ticket export you keep coming back to with new questions, such as "find the ten most common integration mistakes in these tickets." Upload the documents instead of adding a repository, and threads deliver each write-up as a file in the project's [**Library**](#see-what-needs-you-in-overview).

35 35

36In any of them you can send a batch of tasks, tell Claude to start without asking you to confirm, and walk away. When you're back, you can find the threads that need you under [**Waiting on you**](#see-what-needs-you-in-overview). You can also ask Claude to put part of the work on a schedule as a [cloud scheduled task](https://code.claude.com/docs/en/routines.md). If one of these is your situation, [create a project](#create-a-project).36In any of them you can send a batch of tasks, tell Claude to start without asking you to confirm, and walk away. When you're back, you can find the threads that need you under [**Waiting on you**](#see-what-needs-you-in-overview). You can also ask Claude to put part of the work on a schedule as a [cloud scheduled task](https://code.claude.com/docs/en/routines.md). If one of these is your situation, [create a project](#create-a-project).

37 37

57 * The `CLAUDE.md` in [each of the project's repositories](#what-threads-pick-up-from-your-repositories), but not the repositories' skills, `.claude/settings.json`, or `.mcp.json`57 * The `CLAUDE.md` in [each of the project's repositories](#what-threads-pick-up-from-your-repositories), but not the repositories' skills, `.claude/settings.json`, or `.mcp.json`

58 * The [connectors](#get-skills-plugins-connectors-and-tools-into-threads) on your claude.ai account58 * The [connectors](#get-skills-plugins-connectors-and-tools-into-threads) on your claude.ai account

59 * A [cloud environment](#choose-an-environment-for-threads) that sets its network access, environment variables, network secrets, and installed tools59 * A [cloud environment](#choose-an-environment-for-threads) that sets its network access, environment variables, network secrets, and installed tools

60* **The Overview pane**: where you [see all the threads at once](#see-what-needs-you-in-overview) and which of them need you. Its other tabs are **Library** for the files you added and the files threads produced, **Pull requests** for the ones threads opened, and **Scheduled tasks** for scheduled work in the project.60* **The Overview pane**: where you [see all the threads at once](#see-what-needs-you-in-overview) and which of them need you.

61 61

62Cloud threads don't pick up anything from the Claude Code setup on your own machine. [Get skills, plugins, connectors, and tools into threads](#get-skills-plugins-connectors-and-tools-into-threads) covers how to give them what they'd otherwise be missing.62Cloud threads don't pick up anything from the Claude Code setup on your own machine. [Get skills, plugins, connectors, and tools into threads](#get-skills-plugins-connectors-and-tools-into-threads) covers how to give them what they'd otherwise be missing.

63 63

~~64Here is how those parts connect, from you through the conversation to the threads doing the work, with **Overview** tracking their state:~~64Here is how those parts connect, from you through the conversation to the threads doing the work, with Overview tracking their state:

65 65

66![Diagram of a project. You write in the project conversation, where Claude answers or starts a thread. Each cloud thread works on its own branch and pull request. The Overview pane lists threads by state, such as ready for review, waiting on you, and working.](https://mintcdn.com/claude-code/e8CLbxM17eD7cAiv/images/claude-projects-overview.svg?fit=max\&auto=format\&n=e8CLbxM17eD7cAiv\&q=85\&s=dbf446f69f0bbdb9961d21af207cb93b)66![Diagram of a project. You write in the project conversation, where Claude answers or starts a thread. Each cloud thread works on its own branch and pull request. The Overview pane lists threads by state, such as ready for review, waiting on you, and working.](https://mintcdn.com/claude-code/e8CLbxM17eD7cAiv/images/claude-projects-overview.svg?fit=max\&auto=format\&n=e8CLbxM17eD7cAiv\&q=85\&s=dbf446f69f0bbdb9961d21af207cb93b)

67 67

96 96

97* **Name**: how the project appears in the **Projects** list.97* **Name**: how the project appears in the **Projects** list.

98* **What do you want to work on?** (optional): one line that becomes the project's goal, such as "Hold p95 API latency under 200 ms". Claude in the conversation works toward it. Without a goal, Claude works from the tasks you send, and you can add a goal later in **Project settings > General**.98* **What do you want to work on?** (optional): one line that becomes the project's goal, such as "Hold p95 API latency under 200 ms". Claude in the conversation works toward it. Without a goal, Claude works from the tasks you send, and you can add a goal later in **Project settings > General**.

99* **Context** (optional): the GitHub repositories this project works on, plus any files, folders, or Google Drive folders threads should read. Click **Add** for each. Add the repositories most tasks need rather than every one the work might touch; [Decide which repositories to add](#decide-which-repositories-to-add) covers the choice, and you can add more later in **Project settings > Environment**.99* **Context** (optional): the GitHub repositories this project works on, plus any files, folders, or Google Drive folders threads should read. Click **+** for each. Add the repositories most tasks need rather than every one the work might touch; [Decide which repositories to add](#decide-which-repositories-to-add) covers the choice, and you can add more later in **Project settings > Environment**.

100 100

101Standing rules for how threads should work go in [project instructions](#give-a-project-standing-context), which you set after the project exists.101Standing rules for how threads should work go in [project instructions](#give-a-project-standing-context), which you set after the project exists.

102 102

109* Start one thread that explores the repository without changing anything and proposes next steps, if the project has a repository it can read.109* Start one thread that explores the repository without changing anything and proposes next steps, if the project has a repository it can read.

110* Post **Setup recommendations** drawn from your recent cloud sessions: repositories to add, scheduled tasks to create, and threads it could start. Every recommended repository and scheduled task starts switched on. Switch off the ones you don't want, then click **Update setup** to add the rest, or ignore the recommendations and describe work yourself.110* Post **Setup recommendations** drawn from your recent cloud sessions: repositories to add, scheduled tasks to create, and threads it could start. Every recommended repository and scheduled task starts switched on. Switch off the ones you don't want, then click **Update setup** to add the rest, or ignore the recommendations and describe work yourself.

111 111

112The project is now listed under **Projects** in the sidebar, and its conversation is open. [Your first batch](#your-first-batch) covers what to set up before you send it work.112The project is now in the sidebar, and its conversation is open. [Your first batch](#your-first-batch) covers what to set up before you send it work.

113 113

114### Start from an existing session114### Start from an existing session

115 115

168 168

169If Claude routes something differently than you wanted, say so. [Tune how Claude runs a project](#tune-how-claude-runs-a-project) lists things you can tell it, such as reusing an existing thread for follow-ups or answering in place instead of starting a thread.169If Claude routes something differently than you wanted, say so. [Tune how Claude runs a project](#tune-how-claude-runs-a-project) lists things you can tell it, such as reusing an existing thread for follow-ups or answering in place instead of starting a thread.

170 170

171A thread's full results stay in the thread, and you open its card in the conversation to read them. Files a thread produced are also on the **Library** tab in **Overview**.171A thread's full results stay in the thread, and you open its card in the conversation to read them. Files a thread produced are also in the project's [**Library**](#see-what-needs-you-in-overview).

172 172

173Sometimes Claude proposes threads instead of starting them, in a **Suggested threads** list. Click the arrow on a suggestion to start that thread. When several are listed, a button under the list starts all of them.173Sometimes Claude proposes threads instead of starting them, in a **Suggested threads** list. Click the arrow on a suggestion to start that thread. When several are listed, a button under the list starts all of them.

174 174

190 190

191### See what needs you in Overview191### See what needs you in Overview

192 192

193The **Overview** pane beside the conversation tracks the project's threads. It's already open the first time you open a new project. The **Overview** button in the project header closes and reopens it, and shows a dot when a thread is waiting on you.193The Overview pane beside the conversation tracks the project's threads. It's already open the first time you open a new project. To reopen it after you close it, click the **Threads** button in the project header. The button shows a dot when a thread is waiting on you.

194 194

195In the desktop app, you also get a desktop notification when Claude posts in the conversation, a thread hits an error, or a thread needs your input, so you don't have to keep the project open to find out. To also get one each time a thread finishes a turn, or to turn them off for a project, choose **Notifications** in the project's sidebar menu. These notifications are desktop-only: in a browser, check the dot on the **Overview** button.195In the desktop app, a notification appears by default when Claude posts in the conversation, a thread hits an error, or a thread needs your input. None appears while you're viewing the project. To also get one each time a thread finishes a turn, or to turn them off for a project, choose **Notifications** in the project's sidebar menu. In a browser, check the dot on the **Threads** button.

196 196

197The pane's **Threads** tab groups threads by state:197The pane's **Threads** view groups threads by state:

198 198

199| Group | What's in it |199| Group | What's in it |

200| :- | :- |200| :- | :- |

205| **Idle** | Threads that finished and aren't waiting on anything |205| **Idle** | Threads that finished and aren't waiting on anything |

206| **Resolved** | Threads marked done: by you from the thread's menu, by Claude once you've taken the last step, such as merging its pull request, or automatically after a week with no activity. You can reopen one from the same menu |206| **Resolved** | Threads marked done: by you from the thread's menu, by Claude once you've taken the last step, such as merging its pull request, or automatically after a week with no activity. You can reopen one from the same menu |

207 207

208The pane's other tabs are:208Open the project's files and scheduled tasks in the pane from the project header:

209 209

210* **Library**: the files and folders you added and the files threads produced210* **Library**: the files and folders you added and the files that threads produced. Click the **Library** button beside **Threads**.

211* **Pull requests**: shown once threads have opened any211* **Scheduled tasks**: the [cloud scheduled tasks](https://code.claude.com/docs/en/routines.md) Claude set up from this project. Select it in the header's **⋯** menu.

212* **Scheduled tasks**: the [cloud scheduled tasks](https://code.claude.com/docs/en/routines.md) Claude set up from this project

213 212

214### Open a thread when you need control213### Open a thread when you need control

215 214

216Click a thread's card in the conversation or its row in **Overview** to open its transcript in the Overview pane. From there you can:215Click a thread's card in the conversation or its row in Overview to open its transcript in the Overview pane. From there you can:

217 216

218* Read what Claude did, step by step.217* Read what Claude did, step by step.

219* Steer the task by writing in the thread's own message box. A message there goes straight to that thread, while a follow-up in the project conversation reaches it only when Claude matches the follow-up to that thread.218* Steer the task by writing in the thread's own message box. A message there goes straight to that thread, while a follow-up in the project conversation reaches it only when Claude matches the follow-up to that thread.

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

291| Project memory | Notes Claude keeps about the project, such as requirements, decisions, and pitfalls, stored as files. Every cloud thread reads the index file `MEMORY.md` when it starts and opens the other files when it needs them | Ask Claude in the project conversation or any cloud thread to remember a requirement, a decision, or a pitfall, or to forget one. Read, edit, and delete the files in **Project settings > Memory** |290| Project memory | Notes Claude keeps about the project, such as requirements, decisions, and pitfalls, stored as files. Every cloud thread reads the index file `MEMORY.md` when it starts and opens the other files when it needs them | Ask Claude in the project conversation or any cloud thread to remember a requirement, a decision, or a pitfall, or to forget one. Read, edit, and delete the files in **Project settings > Memory** |

292| Project instructions | Text sent to each new thread and to Claude in the project conversation, up to 16,000 characters. [Write project instructions](#write-project-instructions) covers what to put in it | **Project settings > Memory > Project instructions**, or ask Claude to change the instructions |291| Project instructions | Text sent to each new thread and to Claude in the project conversation, up to 16,000 characters. [Write project instructions](#write-project-instructions) covers what to put in it | **Project settings > Memory > Project instructions**, or ask Claude to change the instructions |

293| Repositories, files, and environment | The repositories every cloud thread clones, the folders and files it can read under `/mnt/project-files`, and the cloud environment it runs in | Repositories and environment in **Project settings > Environment**, or ask Claude in the conversation to add a repository to the project. [Files and folders](#add-files-and-folders) from **Add** on the **Library** tab in **Overview** |292| Repositories, files, and environment | The repositories every cloud thread clones, the folders and files it can read under `/mnt/project-files`, and the cloud environment it runs in | Repositories and environment in **Project settings > Environment**, or ask Claude in the conversation to add a repository to the project. [Files and folders](#add-files-and-folders) from **Add** in the project's [**Library**](#see-what-needs-you-in-overview) |

294 293

295**Project settings > Memory** lists these files under **Auto memory**, because Claude writes them itself as it works in the project. They're separate from the [auto memory](https://code.claude.com/docs/en/memory.md) Claude Code keeps on your machine, even though both use a `MEMORY.md` index. Project memory is also separate from the `CLAUDE.md` files in the project's repositories. Each cloud thread still reads those `CLAUDE.md` files from its clone when it starts, so put instructions about a repository in its `CLAUDE.md` and notes about the project in project memory.294**Project settings > Memory** lists these files under **Auto memory**, because Claude writes them itself as it works in the project. They're separate from the [auto memory](https://code.claude.com/docs/en/memory.md) Claude Code keeps on your machine, even though both use a `MEMORY.md` index. Project memory is also separate from the `CLAUDE.md` files in the project's repositories. Each cloud thread still reads those `CLAUDE.md` files from its clone when it starts, so put instructions about a repository in its `CLAUDE.md` and notes about the project in project memory.

296 295

297### Write project instructions296### Write project instructions

298 297

299Project instructions are the brief every new thread starts from. Click the gear icon in the project header to open **Project settings**, then go to **Memory > Project instructions**. A useful brief covers:298Project instructions are the brief every new thread starts from. Select **Settings** in the **⋯** menu in the project header to open **Project settings**, then go to **Memory > Project instructions**. A useful brief covers:

300 299

301* What the project is for300* What the project is for

302* Where the work happens: which repositories, which branch to start from, how to name pull requests301* Where the work happens: which repositories, which branch to start from, how to name pull requests

324* **Add it to the project**, in the **New project** dialog, in **Project settings > Environment**, or by asking Claude in the conversation to add it to the project. Every cloud thread from then on clones it and starts with its `CLAUDE.md` loaded, whether or not the task touches it.323* **Add it to the project**, in the **New project** dialog, in **Project settings > Environment**, or by asking Claude in the conversation to add it to the project. Every cloud thread from then on clones it and starts with its `CLAUDE.md` loaded, whether or not the task touches it.

325* **Leave it off and let threads add it when needed.** A cloud thread whose task needs a repository the project doesn't have can add it to itself, and a note in the thread says it was added to this thread only. The clone happens partway through the task, so that repository's `CLAUDE.md` wasn't there when the thread started. The next thread starts without it. A repository added this way needs the same [prerequisites](#check-the-prerequisites) as a project repository: the Claude GitHub App installed on it and push access from your GitHub account.324* **Leave it off and let threads add it when needed.** A cloud thread whose task needs a repository the project doesn't have can add it to itself, and a note in the thread says it was added to this thread only. The clone happens partway through the task, so that repository's `CLAUDE.md` wasn't there when the thread started. The next thread starts without it. A repository added this way needs the same [prerequisites](#check-the-prerequisites) as a project repository: the Claude GitHub App installed on it and push access from your GitHub account.

326 325

327A project doesn't need a repository at all. Its cloud threads can still research, write documents, and write and run code in their own sandbox, and they deliver files to the **Library** tab. Any of its cloud threads can still add a repository to itself when a task calls for one.326A project doesn't need a repository at all. Its cloud threads can still research, write documents, and write and run code in their own sandbox. They deliver files to the project's **Library**. Any of its cloud threads can still add a repository to itself when a task calls for one.

328 327

329Once the project has repositories, Claude can only add repositories from a GitHub owner the project already uses, whether it adds one to the project or a thread adds one to itself. To bring in a repository from a different owner, add it to the project yourself in **Project settings > Environment**.328Once the project has repositories, Claude can only add repositories from a GitHub owner the project already uses, whether it adds one to the project or a thread adds one to itself. To bring in a repository from a different owner, add it to the project yourself in **Project settings > Environment**.

330 329

332 331

333### Add files and folders332### Add files and folders

334 333

335Add the files and folders you want threads to read in the **New project** dialog's **Context** field, or afterward with **Add** on the **Library** tab in **Overview**. These limits apply to what you add:334Add the files and folders you want threads to read in the **New project** dialog's **Context** field, or afterward with **Add** in the project's [**Library**](#see-what-needs-you-in-overview). These limits apply to what you add:

336 335

337* **Library tab**: up to 100 files and 2 GB in one pick, with a single file up to 480 MB.336* **Files you upload at claude.ai/code or in the desktop app**: up to 1,000 files and 2 GB at a time, with a single file up to 480 MB.

338* **New project dialog**: files over 30 MB are skipped, so add larger files from the **Library** tab after you create the project.337* **Folders you upload**: hidden files and `node_modules` aren't added. A project holds up to 10 folders and Google Drive folders combined, and single files don't count toward that limit.

339* **Folders**: when you add a folder from either place, the project receives a copy of its first 100 files up to 200 MB, without any files over 30 MB, hidden files, or `node_modules`. A project holds up to 10 folders and Google Drive folders combined, and single files don't count toward that limit.

340* **Changes after upload**: uploads are copies, so a change you make on your computer afterward doesn't reach the project until you upload the file again and choose **Replace** when asked about the existing name.338* **Changes after upload**: uploads are copies, so a change you make on your computer afterward doesn't reach the project until you upload the file again and choose **Replace** when asked about the existing name.

341 339

342### What threads pick up from your repositories340### What threads pick up from your repositories

373 371

374## Project settings reference372## Project settings reference

375 373

376You change project settings at claude.ai/code or in the desktop app, not in `settings.json`. Open **Project settings** from **Settings** in the project's sidebar menu or from the gear icon in the project header.374You change project settings at claude.ai/code or in the desktop app, not in `settings.json`. Open **Project settings** from **Settings** in the project's sidebar menu or in the project header's **⋯** menu.

377 375

378Settings save as you change them; a text field you're editing, such as the goal or instructions, shows **Save changes** and **Discard** until you leave it. Changes to instructions, repositories, plugins, and environment in **Project settings** reach new threads, not threads already running.376Settings save as you change them; a text field you're editing, such as the goal or instructions, shows **Save changes** and **Discard** until you leave it. Changes to instructions, repositories, plugins, and environment in **Project settings** reach new threads, not threads already running.

379 377

434 432

435 Projects are on Pro, Max, and Ultra. A project is yours alone: you're the only one who sends it work or sees its threads, and it uses your own GitHub access and connectors. [How Claude Tag differs from Cowork and Claude Code](https://claude.com/docs/claude-tag/concepts/how-it-works#how-claude-tag-differs-from-cowork-and-claude-code) has the side-by-side.433 Projects are on Pro, Max, and Ultra. A project is yours alone: you're the only one who sends it work or sees its threads, and it uses your own GitHub access and connectors. [How Claude Tag differs from Cowork and Claude Code](https://claude.com/docs/claude-tag/concepts/how-it-works#how-claude-tag-differs-from-cowork-and-claude-code) has the side-by-side.

436* **Cloud sessions**: every thread is a [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md) unless you ask Claude to run it on your machine. Either way, Claude starts and tracks it instead of you. You can also bring the work of a cloud session you started yourself into a project: choose [**Continue in project**](#start-from-an-existing-cloud-session) in that session's sidebar menu.434* **Cloud sessions**: every thread is a [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md) unless you ask Claude to run it on your machine. Either way, Claude starts and tracks it instead of you. You can also bring the work of a cloud session you started yourself into a project: choose [**Continue in project**](#start-from-an-existing-cloud-session) in that session's sidebar menu.

437* **Scheduled tasks**: when you ask for scheduled work in a project, Claude creates a [cloud scheduled task](https://code.claude.com/docs/en/routines.md) that runs as threads in that project and appears on its **Scheduled tasks** tab. Scheduled tasks you create outside a project keep working on their own.435* **Scheduled tasks**: when you ask for scheduled work in a project, Claude creates a [cloud scheduled task](https://code.claude.com/docs/en/routines.md) that runs as threads in that project and appears in its **Scheduled tasks** view. Scheduled tasks you create outside a project keep working on their own.

438* **Remote Control**: [Remote Control](https://code.claude.com/docs/en/remote-control.md) connects claude.ai to a Claude Code session running on your machine. When you ask Claude in a project to run a thread on your computer, the project [uses Remote Control to do it](#run-a-thread-on-your-own-computer).436* **Remote Control**: [Remote Control](https://code.claude.com/docs/en/remote-control.md) connects claude.ai to a Claude Code session running on your machine. When you ask Claude in a project to run a thread on your computer, the project [uses Remote Control to do it](#run-a-thread-on-your-own-computer).

439* **Local sessions and agent view**: a session you start yourself in your terminal, IDE, or the desktop app's local environment stays outside your projects, though you can [bring its work into one](#start-from-an-existing-cloud-session). [Agent view](https://code.claude.com/docs/en/agent-view.md) is a screen for tracking several local sessions side by side, and you still start each one and give it its task yourself.437* **Local sessions and agent view**: a session you start yourself in your terminal, IDE, or the desktop app's local environment stays outside your projects, though you can [bring its work into one](#start-from-an-existing-cloud-session). [Agent view](https://code.claude.com/docs/en/agent-view.md) is a screen for tracking several local sessions side by side, and you still start each one and give it its task yourself.

440* **Worktrees**: a [worktree](https://code.claude.com/docs/en/worktrees.md) gives each local session its own working copy of a repository. Cloud threads don't need them: each clones its repositories into its own cloud sandbox and works on its own branch.438* **Worktrees**: a [worktree](https://code.claude.com/docs/en/worktrees.md) gives each local session its own working copy of a repository. Cloud threads don't need them: each clones its repositories into its own cloud sandbox and works on its own branch.

466When several threads come back having assumed something wrong, worked around missing access, or stopped with "blocked", the cause is usually the same gap in the project's setup rather than a problem with each task. Sort out which threads are sound before you fix anything:464When several threads come back having assumed something wrong, worked around missing access, or stopped with "blocked", the cause is usually the same gap in the project's setup rather than a problem with each task. Sort out which threads are sound before you fix anything:

467 465

4681. Ask Claude in the conversation: "For every open thread, list what you asked it to do, what it assumed or couldn't reach, and what it's waiting on." Claude reads each thread and answers in the conversation.4661. Ask Claude in the conversation: "For every open thread, list what you asked it to do, what it assumed or couldn't reach, and what it's waiting on." Claude reads each thread and answers in the conversation.

4692. For threads that started from a wrong assumption, open the thread from **Overview** and mark it resolved from its menu, or tell it what to do instead in its message box. Its branch and any pull request stay on GitHub until you delete them.4672. For threads that started from a wrong assumption, open the thread from Overview and mark it resolved from its menu, or tell it what to do instead. Its branch and any pull request stay on GitHub until you delete them.

4703. Fix the gap once, in [project instructions](#give-a-project-standing-context) or the [environment](#choose-an-environment-for-threads), then send one thread before sending the rest of the work again as new threads.4683. Fix the gap once, in [project instructions](#give-a-project-standing-context) or the [environment](#choose-an-environment-for-threads), then send one thread before sending the rest of the work again as new threads.

471 469

472### Claude hasn't responded470### Claude hasn't responded

claude-security.md +4 −4

Details

71 71

72**2. Choose what to scan**72**2. Choose what to scan**

73 73

74The plugin reads your repository first, then offers the whole repository or a focused area, with each option's file count and relative cost stated. Pick the whole repository, or answer "I don't know" and the plugin picks a sensible default for your repository's size.74The plugin reads your repository first, then offers the whole repository or a focused area. Pick the whole repository, or answer "I don't know" and the plugin picks a sensible default for your repository's size.

75 75

76**3. Confirm the run**76**3. Confirm the run**

77 77

95 95

96When your branch has commits its base doesn't, the `/claude-security` menu offers to scan only that diff, so you can check a branch before merging. You can also scan one of your open pull requests, or a single commit by asking for it, such as "scan commit abc1234". Only committed changes are scanned: commit or stash in-progress edits first, or run a full scan, which reads the working tree.96When your branch has commits its base doesn't, the `/claude-security` menu offers to scan only that diff, so you can check a branch before merging. You can also scan one of your open pull requests, or a single commit by asking for it, such as "scan commit abc1234". Only committed changes are scanned: commit or stash in-progress edits first, or run a full scan, which reads the working tree.

97 97

98Change scans need a git repository; full scans of an unversioned directory still work. Finding your open pull requests is the one step that reaches the network, and it's offered only when your session already has permission to run the GitHub CLI and `gh` is signed in.98Change scans need a git repository; full scans of an unversioned directory still work. Finding your open pull requests is offered only when your session already has permission to run the GitHub CLI and `gh` is signed in.

99 99

100### Scope large repositories100### Scope large repositories

101 101

120* **`CLAUDE-SECURITY-RESULTS.md`**: the report, with each finding's ID, such as `F1`, plus its impact, exploit scenario, severity, confidence, and recommendation120* **`CLAUDE-SECURITY-RESULTS.md`**: the report, with each finding's ID, such as `F1`, plus its impact, exploit scenario, severity, confidence, and recommendation

121* **`CLAUDE-SECURITY-RESULTS.jsonl`**: the same findings in machine-readable form, one JSON object per line121* **`CLAUDE-SECURITY-RESULTS.jsonl`**: the same findings in machine-readable form, one JSON object per line

122* **`CLAUDE-SECURITY-RESULTS.sarif`**: the same findings as a [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) log for GitHub code scanning and any other tool that reads the standard. The scan classifies findings under their [CWE](https://cwe.mitre.org/) weakness categories122* **`CLAUDE-SECURITY-RESULTS.sarif`**: the same findings as a [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) log for GitHub code scanning and any other tool that reads the standard. The scan classifies findings under their [CWE](https://cwe.mitre.org/) weakness categories

123* **`CLAUDE-SECURITY-REVISION-<commit>.json`**: the revision stamp, recording which commit was scanned, at what [scan effort](#choose-a-scan-effort), whether uncommitted changes were part of the scanned tree, and how thoroughly the run was verified, so a report is always tied to the code it describes. A scan outside version control stamps `UNVERSIONED` in place of the commit123* **`CLAUDE-SECURITY-REVISION-<commit>.json`**: the revision stamp, recording which commit was scanned, at what [scan effort](#choose-a-scan-effort), whether uncommitted changes were part of the scanned tree, and how thoroughly the run was verified. A scan outside version control stamps `UNVERSIONED` in place of the commit

124 124

125That directory is the only change a scan makes to your checkout, and it carries its own `.gitignore`, so a stray `git add` never sweeps a report into a commit. To keep a report in history for an audit trail, delete that one `.gitignore` file and commit the directory like any other.125That directory is the only change a scan makes to your checkout, and it carries its own `.gitignore`, so a stray `git add` never sweeps a report into a commit. To keep a report in history for an audit trail, delete that one `.gitignore` file and commit the directory like any other.

126 126

127Findings only appear in the report after independent verifier agents analyze them, which keeps reports short and worth reading. Scans are nondeterministic: two scans of the same code can surface different findings. Run scans regularly, and use the revision stamps to attribute each report to the exact code and settings it covered.127Findings only appear in the report after independent verifier agents analyze them, which keeps reports short and worth reading. Scans are nondeterministic: two scans of the same code can surface different findings. Run scans regularly.

128 128

129## Fix findings129## Fix findings

130 130

cloud-environments.md +18 −14

Details

37 37

38**Default** carries no configuration of its own:38**Default** carries no configuration of its own:

39 39

~~40* [**Trusted** network access](#access-levels): sessions reach package registries and other [allowlisted domains](#default-allowed-domains), and nothing else through the session's network.~~40* [**Limited** network access](#access-levels): sessions reach package registries and other [allowlisted domains](#default-allowed-domains).

41* No other configuration: **Default** defines no environment variables or setup script, so sessions start with just the [pre-installed tools](#installed-tools).41* No other configuration: **Default** defines no environment variables or setup script, so sessions start with just the [pre-installed tools](#installed-tools).

42 42

43With only **Default** available, every session runs in it. When you have more than one environment, sessions choose one per surface:43With only **Default** available, every session runs in it. When you have more than one environment, sessions choose one per surface:

102* **Role**: on every plan, you can add and delete secrets on your own environments whatever your role. On Team and Enterprise, Owners hold an organization admin role in your claude.ai organization and Admins don't, which changes what you see in these cases:102* **Role**: on every plan, you can add and delete secrets on your own environments whatever your role. On Team and Enterprise, Owners hold an organization admin role in your claude.ai organization and Admins don't, which changes what you see in these cases:

103 * **Your own environment**: without an organization admin role, **Add secret** opens a [shorter form](#add-a-secret-without-the-role)103 * **Your own environment**: without an organization admin role, **Add secret** opens a [shorter form](#add-a-secret-without-the-role)

104 * **A shared environment**: Owners [add and delete its secrets](#add-a-credential) from admin settings. Without an organization admin role, ask an Owner to add the secret, because the environment's dialog has no **Network secrets** section104 * **A shared environment**: Owners [add and delete its secrets](#add-a-credential) from admin settings. Without an organization admin role, ask an Owner to add the secret, because the environment's dialog has no **Network secrets** section

105* **Environment type**: an Anthropic-hosted cloud environment that already exists. A [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments) doesn't have network secrets105* **Environment type**: an Anthropic-hosted cloud environment. A [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments) doesn't have network secrets

106* **API reachability**: the API accepts connections from the internet, because requests leave from Anthropic's network106* **API reachability**: the API accepts connections from the internet, because requests leave from Anthropic's network

107* **Encryption keys**: if your organization uses customer-managed encryption keys, you can't save network secrets107* **Encryption keys**: if your organization uses customer-managed encryption keys, you can't save network secrets

108 108

198 198

199## Network access199## Network access

200 200

201Each environment sets one network access level, which controls the outbound connections its sessions can make. The default level, **Trusted**, allows package registries and other [allowlisted domains](#default-allowed-domains); **Custom** takes your own domain list.201Each environment sets one network access level, which controls the outbound connections its sessions can make. A new environment starts at **Limited** with **Allow package managers** checked, so its sessions reach package registries and other [allowlisted domains](#default-allowed-domains).

202 202

203To change an environment's network access, [open it for editing](#configure-your-environment) and use the **Network access** selector in the dialog. A [shared environment](#organization-shared-environments) opens read-only there, so an Owner changes its network access from the **Cloud environments** page in [admin settings](https://claude.ai/admin-settings) instead. The control that opens the selector appears on the app surfaces listed under [The Default environment](#the-default-environment) and in the [cloud scheduled task editor](https://code.claude.com/docs/en/routines.md#environments-and-network-access). Personal environments don't have a separate page in your claude.ai account settings.203To change an environment's network access, [open it for editing](#configure-your-environment) and use the **Network access** selector in the dialog. A [shared environment](#organization-shared-environments) opens read-only there, so an Owner changes its network access from the **Cloud environments** page in [admin settings](https://claude.ai/admin-settings) instead. The control that opens the selector appears on the app surfaces listed under [The Default environment](#the-default-environment) and in the [cloud scheduled task editor](https://code.claude.com/docs/en/routines.md#environments-and-network-access). Personal environments don't have a separate page in your claude.ai account settings.

204 204

210 210

211### Access levels211### Access levels

212 212

213The **Network access** field in the [environment dialog](#configure-your-environment) takes one of four levels:213The **Network access** field in the [environment dialog](#configure-your-environment) takes one of three levels:

214 214

215| Level | Outbound connections |215| Level | Outbound connections |

216| :- | :- |216| :- | :- |

217| **None** | No outbound network access through the session's network |217| **None** | No outbound network access through the session's network |

218| **Trusted** | [Allowlisted domains](#default-allowed-domains) only: package registries, GitHub, cloud SDKs |218| **Limited** | The [default allowlist](#default-allowed-domains) of package registries, GitHub, and cloud SDKs while **Allow package managers** is checked, plus any [domains you list](#allow-specific-domains). See [what a blocked request looks like](https://code.claude.com/docs/en/errors.md#host-not-allowed-in-a-cloud-session). |

219| **Full** | Any domain |219| **Full** | Any domain |

220| **Custom** | Your own allowlist, optionally including the defaults |

221 220

222Whichever level you pick, sessions can still reach these, because each one takes a path that doesn't go through the session's network allowlist:221Whichever level you pick, sessions can still reach these, because each one takes a path that doesn't go through the session's network allowlist:

223 222

226* The hosts you listed on the environment's [network secrets](#add-network-secrets), except the [hosts that never get the secret](#requests-that-never-get-the-credential)225* The hosts you listed on the environment's [network secrets](#add-network-secrets), except the [hosts that never get the secret](#requests-that-never-get-the-credential)

227* The Anthropic API, for Claude Code's own requests, even at **None**, as noted under [Security and isolation](https://code.claude.com/docs/en/claude-code-on-the-web.md#security-and-isolation)226* The Anthropic API, for Claude Code's own requests, even at **None**, as noted under [Security and isolation](https://code.claude.com/docs/en/claude-code-on-the-web.md#security-and-isolation)

228 227

228An environment saved as **Trusted** or **Custom** keeps reaching the same hosts and opens this way:

229

230* **Saved as Trusted**: opens as **Limited** with **Allow package managers** checked

231* **Saved as Custom**: opens as **Limited** with its **Allowed domains** list and **Allow package managers** as you set them, or as **Full** if the list contained a bare `*`

232

229### Allow specific domains233### Allow specific domains

230 234

231To allow domains that aren't in the Trusted list, select **Custom** in the environment's network access settings, then list one domain per line in the **Allowed domains** field. This example allows three hosts an internal project might need.235To allow domains that aren't in the [default allowlist](#default-allowed-domains), select **Limited** in the environment's **Network access** selector, then list one domain per line in the **Allowed domains** field. A leading `*.` matches every subdomain. This example allows three hosts an internal project might need.

232 236

233```text theme={null}237```text theme={null}

234api.example.com238api.example.com

236registry.example.com240registry.example.com

237```241```

238 242

239Sessions in this environment can now reach `api.example.com`, any subdomain of `internal.example.com`, and `registry.example.com`, and no other domains through the session's network. [GitHub traffic](#github-proxy), [MCP connector traffic](#network-access), and requests to the hosts of the environment's [network secrets](#add-network-secrets), other than the [hosts that never get the secret](#requests-that-never-get-the-credential), don't go through this allowlist. A leading `*.` matches every subdomain. To keep the [Trusted domains](#default-allowed-domains) too, check **Also include default list of common package managers**; leave it unchecked to allow only what you list.243While **Allow package managers** is checked, sessions in this environment reach the [default allowlist](#default-allowed-domains) as well as the domains you list. Clear the checkbox to leave the default allowlist out. [GitHub traffic](#github-proxy), [MCP connector traffic](#network-access), and requests to the hosts of the environment's [network secrets](#add-network-secrets), other than the [hosts that never get the secret](#requests-that-never-get-the-credential), don't go through this allowlist.

240 244

241If your organization uses [artifacts](https://code.claude.com/docs/en/artifacts.md#availability), you don't need `*.frame.claudeusercontent.com` in the list for sessions to read them. When the list leaves that host out, Claude Code reads artifact content through the session's connection to Anthropic instead. Keep the host in an allowlist in two situations:245If your organization uses [artifacts](https://code.claude.com/docs/en/artifacts.md#availability), you don't need `*.frame.claudeusercontent.com` in the list for sessions to read them. When the list leaves that host out, Claude Code reads artifact content through the session's connection to Anthropic instead. Keep the host in an allowlist in two situations:

242 246

243* **Sessions in this environment open another organization's public artifacts**: Claude Code fetches those from the host directly, so add it to this list.247* **Sessions in this environment open another organization's public artifacts**: Claude Code fetches those from the host directly, so add it to this list.

244* **You're configuring the local CLI or a self-hosted runner**: keep the host in that allowlist. See [network access requirements](https://code.claude.com/docs/en/network-config.md#network-access-requirements) and the self-hosted [network requirements](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#network-requirements).248* **You're configuring the local CLI or a self-hosted runner**: keep the host in that allowlist. See [network access requirements](https://code.claude.com/docs/en/network-config.md#network-access-requirements) and the self-hosted [network requirements](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#network-requirements).

245 249

246Each environment has its own allowed-domains list; there's no organization-level allowlist that admins can push to every member's environments. No [server-managed setting](https://code.claude.com/docs/en/server-managed-settings.md) adds domains to an environment's network allowlist either. To give a team one standard list, an Owner can create an [organization-shared environment](#organization-shared-environments) with **Custom** network access and that list.250Each environment has its own allowed-domains list; there's no organization-level allowlist that admins can push to every member's environments. No [server-managed setting](https://code.claude.com/docs/en/server-managed-settings.md) adds domains to an environment's network allowlist either. To give a team one standard list, an Owner can create an [organization-shared environment](#organization-shared-environments) with **Limited** network access and that list.

247 251

248### GitHub proxy252### GitHub proxy

249 253

255* **Repository scope**: the proxy serves GitHub API requests for the repositories attached to the session. An API request for another repository gets a 403 whose message starts with `GitHub access to` and contains `is not enabled for this session`. A source archive you fetch over a `github.com/{owner}/{repo}/archive/` or `codeload.github.com` URL gets that same 403 when the repository isn't attached, even a public one.259* **Repository scope**: the proxy serves GitHub API requests for the repositories attached to the session. An API request for another repository gets a 403 whose message starts with `GitHub access to` and contains `is not enabled for this session`. A source archive you fetch over a `github.com/{owner}/{repo}/archive/` or `codeload.github.com` URL gets that same 403 when the repository isn't attached, even a public one.

256* **GraphQL restrictions**: the proxy rejects requests to GitHub's GraphQL endpoint with a 403 whose message starts with `GitHub GraphQL is not available from Claude Code sessions` and names the REST fallback, `gh api repos/{owner}/{repo}/...`. `gh` subcommands that use GraphQL, such as `gh pr` and `gh issue`, get the same 403. The restriction applies to every request through the proxy regardless of the credentials you supply, so a `GH_TOKEN` you set gets the same 403. Claude can't reach GitHub APIs that exist only in GraphQL, such as Projects v2, through the proxy.260* **GraphQL restrictions**: the proxy rejects requests to GitHub's GraphQL endpoint with a 403 whose message starts with `GitHub GraphQL is not available from Claude Code sessions` and names the REST fallback, `gh api repos/{owner}/{repo}/...`. `gh` subcommands that use GraphQL, such as `gh pr` and `gh issue`, get the same 403. The restriction applies to every request through the proxy regardless of the credentials you supply, so a `GH_TOKEN` you set gets the same 403. Claude can't reach GitHub APIs that exist only in GraphQL, such as Projects v2, through the proxy.

257 261

258Committed files from public repositories arrive through `raw.githubusercontent.com`, which the [security proxy](#security-proxy) handles instead. That domain is in the default [Trusted list](#default-allowed-domains), so those files stay reachable unless the environment's [access level](#access-levels) excludes it.262Committed files from public repositories arrive through `raw.githubusercontent.com`, which the [security proxy](#security-proxy) handles instead. That domain is on the [default allowlist](#default-allowed-domains), so those files stay reachable as long as the environment's [network access](#access-levels) allows that list.

259 263

260### Security proxy264### Security proxy

261 265

391service redis-server start395service redis-server start

392```396```

393 397

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

395 399

396If your images are large or slow to pull, add `docker compose pull` or `docker compose build` to your [setup script](#setup-scripts). The [environment cache](#environment-caching) keeps the pulled images, so each new session has them on disk. The cache stores files only, not running processes, so Claude still starts the containers each session.400If your images are large or slow to pull, add `docker compose pull` or `docker compose build` to your [setup script](#setup-scripts). The [environment cache](#environment-caching) keeps the pulled images, so each new session has them on disk. The cache stores files only, not running processes, so Claude still starts the containers each session.

397 401

445 449

446* **Exit zero**: if the script exits non-zero, the session [fails to start](https://code.claude.com/docs/en/web-quickstart.md#setup-script-failed) or starts without whatever the script failed to install. Append `|| true` to non-critical commands so an intermittent install failure doesn't fail the script.450* **Exit zero**: if the script exits non-zero, the session [fails to start](https://code.claude.com/docs/en/web-quickstart.md#setup-script-failed) or starts without whatever the script failed to install. Append `|| true` to non-critical commands so an intermittent install failure doesn't fail the script.

447* **Finish within five minutes**: keep the script's total runtime under roughly five minutes so the [environment cache](#environment-caching) can build. When setup takes longer than that, the environment isn't cached. Run independent installs in parallel with `&` and `wait`, and move any single download that won't fit into a [SessionStart hook](#setup-scripts-vs-sessionstart-hooks) that launches it in the background. If new sessions stall or fail during setup, see [New sessions hang or time out during setup](https://code.claude.com/docs/en/web-quickstart.md#new-sessions-hang-or-time-out-during-setup).451* **Finish within five minutes**: keep the script's total runtime under roughly five minutes so the [environment cache](#environment-caching) can build. When setup takes longer than that, the environment isn't cached. Run independent installs in parallel with `&` and `wait`, and move any single download that won't fit into a [SessionStart hook](#setup-scripts-vs-sessionstart-hooks) that launches it in the background. If new sessions stall or fail during setup, see [New sessions hang or time out during setup](https://code.claude.com/docs/en/web-quickstart.md#new-sessions-hang-or-time-out-during-setup).

448* **Network access for installs**: package installs need to reach registries. The default **Trusted** level covers [common package registries](#default-allowed-domains) including npm, PyPI, RubyGems, and crates.io; with **None** network access, installs fail.452* **Network access for installs**: package installs need to reach registries. The default **Limited** level with **Allow package managers** checked covers [common package registries](#default-allowed-domains) including npm, PyPI, RubyGems, and crates.io. With **None** network access, installs fail.

449* **The environment's variables aren't set yet**: the script runs before the session sets the environment's [environment variables](#set-environment-variables). Set any value the script needs in the script itself.453* **The environment's variables aren't set yet**: the script runs before the session sets the environment's [environment variables](#set-environment-variables). Set any value the script needs in the script itself.

450 454

451### Environment caching455### Environment caching

541* **One repository per session**: in an Anthropic-hosted environment, a session with several repositories doesn't load hooks from any repository's `.claude/settings.json`, so a SessionStart hook you define there doesn't run. Install dependencies for those sessions with a [setup script](#setup-scripts) instead. For a self-hosted environment, see [which repository's settings apply](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#repository-settings-in-sessions-with-several-repositories).545* **One repository per session**: in an Anthropic-hosted environment, a session with several repositories doesn't load hooks from any repository's `.claude/settings.json`, so a SessionStart hook you define there doesn't run. Install dependencies for those sessions with a [setup script](#setup-scripts) instead. For a self-hosted environment, see [which repository's settings apply](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#repository-settings-in-sessions-with-several-repositories).

542* **Not in a project's cloud threads**: a cloud thread in a [project](https://code.claude.com/docs/en/claude-projects.md#what-threads-pick-up-from-your-repositories) doesn't run hooks from a repository's `.claude/settings.json`, whatever the number of repositories. In an Anthropic-hosted environment, install dependencies for threads with a [setup script](#setup-scripts). In a self-hosted environment, use a hook in the [runner host's settings](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#repository-settings-in-sessions-with-several-repositories) instead.546* **Not in a project's cloud threads**: a cloud thread in a [project](https://code.claude.com/docs/en/claude-projects.md#what-threads-pick-up-from-your-repositories) doesn't run hooks from a repository's `.claude/settings.json`, whatever the number of repositories. In an Anthropic-hosted environment, install dependencies for threads with a [setup script](#setup-scripts). In a self-hosted environment, use a hook in the [runner host's settings](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#repository-settings-in-sessions-with-several-repositories) instead.

543* **No cloud-only scoping**: hooks run in both local and cloud sessions. To skip local execution, exit early unless the `CLAUDE_CODE_REMOTE` environment variable is `true`, the way the [dependency install script](#install-dependencies-with-a-sessionstart-hook) does.547* **No cloud-only scoping**: hooks run in both local and cloud sessions. To skip local execution, exit early unless the `CLAUDE_CODE_REMOTE` environment variable is `true`, the way the [dependency install script](#install-dependencies-with-a-sessionstart-hook) does.

544* **Requires network access**: install commands need to reach package registries. If your environment uses **None** network access, these hooks fail. The [default allowlist](#default-allowed-domains) under **Trusted** covers npm, PyPI, RubyGems, and crates.io.548* **Requires network access**: install commands need to reach package registries. If your environment uses **None** network access, these hooks fail. Under the default **Limited** level with **Allow package managers** checked, the [default allowlist](#default-allowed-domains) covers npm, PyPI, RubyGems, and crates.io.

545* **Proxy compatibility**: in Anthropic-hosted environments, all outbound traffic passes through a [security proxy](#security-proxy), and some package managers don't work correctly with it; Bun is a known example. In a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#default-deny-egress), outbound traffic goes through your own network boundary instead.549* **Proxy compatibility**: in Anthropic-hosted environments, all outbound traffic passes through a [security proxy](#security-proxy), and some package managers don't work correctly with it; Bun is a known example. In a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#default-deny-egress), outbound traffic goes through your own network boundary instead.

546* **Adds startup latency**: hooks run each time a session starts or resumes, unlike setup scripts which benefit from [environment caching](#environment-caching). Keep install scripts fast by skipping work that's already done, the way the [dependency install script](#install-dependencies-with-a-sessionstart-hook) does.550* **Adds startup latency**: hooks run each time a session starts or resumes, unlike setup scripts which benefit from [environment caching](#environment-caching). Keep install scripts fast by skipping work that's already done, the way the [dependency install script](#install-dependencies-with-a-sessionstart-hook) does.

547 551

549 553

550## Default allowed domains554## Default allowed domains

551 555

552With **Trusted** network access, sessions can reach the following domains by default. Domains marked with `*` indicate wildcard subdomain matching, so `*.gcr.io` allows any subdomain of `gcr.io`.556When **Allow package managers** is checked under **Limited** network access, as it is in a new environment, sessions can reach the following domains. Domains marked with `*` indicate wildcard subdomain matching, so `*.gcr.io` allows any subdomain of `gcr.io`.

553 557

554> [accordion] Anthropic services558> [accordion] Anthropic services

555>559>

code-review-local.md +1 −3

Details

14>14>

15> To have every pull request in a repository reviewed automatically on GitHub, see [Code Review](https://code.claude.com/docs/en/code-review.md), a managed service that an Owner turns on for your organization.15> To have every pull request in a repository reviewed automatically on GitHub, see [Code Review](https://code.claude.com/docs/en/code-review.md), a managed service that an Owner turns on for your organization.

16 16

~~17`/review` is an alias of `/code-review`. Before v2.1.223, `/review` was a separate command that ran a single-pass, read-only review of a GitHub pull request.~~17`/review` is an alias of `/code-review`.

18 18

19**1. Run /code-review**19**1. Run /code-review**

20 20

91* **`ultra`**: the review neither uses nor updates the remembered level91* **`ultra`**: the review neither uses nor updates the remembered level

92* **No level ever typed**: the review uses the session's current effort92* **No level ever typed**: the review uses the session's current effort

93 93

~~94Before v2.1.223, a `/code-review` without a level always used the session's current effort.~~

96### Post findings to a GitLab merge request94### Post findings to a GitLab merge request

97 95

98When you pass `--comment` for a GitLab merge request, Claude Code posts the findings through GitLab's `glab` CLI. Requires Claude Code v2.1.257 or later. When `glab` isn't installed, Claude prints the findings in the terminal instead.96When you pass `--comment` for a GitLab merge request, Claude Code posts the findings through GitLab's `glab` CLI. Requires Claude Code v2.1.257 or later. When `glab` isn't installed, Claude prints the findings in the terminal instead.

commands.md +2 −2

Details

104| `/install-github-app` | Install the Claude GitHub App for a repository, with an optional step to set up [GitHub Actions](https://code.claude.com/docs/en/github-actions.md) workflows and secrets. Walks you through selecting a repo and configuring the integration. Works only with github.com repositories. When your repository's git remote is on gitlab.com or bitbucket.org, the command prints a notice and exits instead of starting setup. To run Claude Code from GitLab pipelines, see [GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md) |104| `/install-github-app` | Install the Claude GitHub App for a repository, with an optional step to set up [GitHub Actions](https://code.claude.com/docs/en/github-actions.md) workflows and secrets. Walks you through selecting a repo and configuring the integration. Works only with github.com repositories. When your repository's git remote is on gitlab.com or bitbucket.org, the command prints a notice and exits instead of starting setup. To run Claude Code from GitLab pipelines, see [GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md) |

107| `/list-agents` | List the subagents, [agent team](https://code.claude.com/docs/en/agent-teams.md) teammates, and other Claude Code sessions Claude can message, with the name to use for each. See [cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md). Also available as `/peers`. Requires Claude Code v2.1.224 or later; earlier versions report `Unknown command: /list-agents`. Teammate rows and the first line showing this session's own name require v2.1.239 or later. Available only in sessions where [cross-session messaging is enabled](https://code.claude.com/docs/en/cross-session-messaging.md#availability) |107| `/list-agents` | List the subagents, [agent team](https://code.claude.com/docs/en/agent-teams.md) teammates, and other Claude Code sessions Claude can message, with the name to use for each. See [cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md). Also available as `/peers`. Teammate rows and the first line showing this session's own name require v2.1.239 or later. Available only in sessions where [cross-session messaging is enabled](https://code.claude.com/docs/en/cross-session-messaging.md#availability) |

110| `/loop [interval] [prompt]` | **[Skill](https://code.claude.com/docs/en/skills.md#bundled-skills).** Run a prompt repeatedly while the session stays open. Omit the interval and Claude [self-paces between iterations](https://code.claude.com/docs/en/scheduled-tasks.md#let-claude-choose-the-interval). Omit the prompt and Claude runs the [built-in maintenance prompt](https://code.claude.com/docs/en/scheduled-tasks.md#run-the-built-in-maintenance-prompt) or your [`loop.md`](https://code.claude.com/docs/en/scheduled-tasks#customize-the-default-prompt-with-loop-md). Example: `/loop 5m check if the deploy finished`. See [Run prompts on a schedule](https://code.claude.com/docs/en/scheduled-tasks.md). Alias: `/proactive` |110| `/loop [interval] [prompt]` | **[Skill](https://code.claude.com/docs/en/skills.md#bundled-skills).** Run a prompt repeatedly while the session stays open. Omit the interval and Claude [self-paces between iterations](https://code.claude.com/docs/en/scheduled-tasks.md#let-claude-choose-the-interval). Omit the prompt and Claude runs the [built-in maintenance prompt](https://code.claude.com/docs/en/scheduled-tasks.md#run-the-built-in-maintenance-prompt) or your [`loop.md`](https://code.claude.com/docs/en/scheduled-tasks#customize-the-default-prompt-with-loop-md). Example: `/loop 5m check if the deploy finished`. See [Run prompts on a schedule](https://code.claude.com/docs/en/scheduled-tasks.md). Alias: `/proactive` |

132| `/rename [name]` | Rename the current session and show the name on the prompt bar. Without a name, auto-generates one from conversation history. Also available in non-interactive mode (`-p`). From every rename surface, including claude.ai and the desktop app, Claude Code replaces control and invisible characters in the new name with spaces and caps the name at 200 characters. If the name is empty once invisible characters are removed, Claude Code rejects it and shows `That name is empty once invisible characters are removed. Usage: /rename <name>`. The character replacement and length cap require Claude Code v2.1.221 or later |132| `/rename [name]` | Rename the current session and show the name on the prompt bar. Without a name, auto-generates one from conversation history. Also available in non-interactive mode (`-p`). From every rename surface, including claude.ai and the desktop app, Claude Code replaces control and invisible characters in the new name with spaces and caps the name at 200 characters. If the name is empty once invisible characters are removed, Claude Code rejects it and shows `That name is empty once invisible characters are removed. Usage: /rename <name>`. The character replacement and length cap require Claude Code v2.1.221 or later |

133| `/restart` | Restart Claude Code and resume this session, which applies an installed update. Run it when the footer offers it after an update installs. Requires a Pro, Max, or Ultra plan and a native install on macOS or Linux, not WSL. Requires Claude Code v2.1.288 or later. Alias: `/update` |133| `/restart` | Restart Claude Code and resume this session, which applies an installed update. Run it when the footer offers it after an update installs. Requires a Pro, Max, or Ultra plan and a native install on macOS or Linux, not WSL. Requires Claude Code v2.1.288 or later. Alias: `/update` |

134| `/resume [session]` | Resume a conversation by ID or name, or open the session picker. [Background sessions](https://code.claude.com/docs/en/agent-view.md) appear in the picker marked with `bg`. Resuming one that is still running, from the picker or by ID or name, [opens that session](https://code.claude.com/docs/en/sessions.md#resume-a-running-background-session): your current conversation moves to the background and this terminal attaches to the running one. Press `←` on an empty prompt to return to agent view, which also lists the conversation you left. Before v2.1.285, Claude Code refused and told you to open the session with `claude attach` or stop it first. Alias: `/continue` |134| `/resume [session]` | Resume a conversation by ID or name, or open the session picker. [Background sessions](https://code.claude.com/docs/en/agent-view.md) appear in the picker marked with `bg`. Resuming one that is still running, from the picker or by ID or name, [opens that session](https://code.claude.com/docs/en/sessions.md#resume-a-running-background-session): your current conversation moves to the background and this terminal attaches to the running one. Press `←` on an empty prompt to return to agent view, which also lists the conversation you left. Before v2.1.285, Claude Code refused and told you to open the session with `claude attach` or stop it first. Alias: `/continue` |

135| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [--max-findings n\|all\|default] [pr#\|branch\|path]` | Alias of [`/code-review`](https://code.claude.com/docs/en/code-review-local): reviews the current diff, or a PR number, branch, or path you pass, such as `/review 1234`, and takes the same effort levels and flags. With no level given, the review reuses the last `low` through `max` level you typed; see [Review locally with `/code-review`](https://code.claude.com/docs/en/code-review-local) for the exact rules. For a deep cloud review, use [`/code-review ultra`](https://code.claude.com/docs/en/ultrareview). Before v2.1.223, `/review` was a separate command that ran a single-pass, read-only review of a GitHub pull request by number, listing open PRs to pick from when run with no argument; from v2.1.186 through v2.1.201, it ran the same multi-agent engine as `/code-review medium` |135| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [--max-findings n\|all\|default] [pr#\|branch\|path]` | Alias of [`/code-review`](https://code.claude.com/docs/en/code-review-local): reviews the current diff, or a PR number, branch, or path you pass, such as `/review 1234`, and takes the same effort levels and flags. With no level given, the review reuses the last `low` through `max` level you typed; see [Review locally with `/code-review`](https://code.claude.com/docs/en/code-review-local) for the exact rules. For a deep cloud review, use [`/code-review ultra`](https://code.claude.com/docs/en/ultrareview) |

136| `/rewind` | Rewind the conversation and/or code to a previous point, or summarize from a selected message. See [checkpointing](https://code.claude.com/docs/en/checkpointing.md). Aliases: `/checkpoint`, `/undo` |136| `/rewind` | Rewind the conversation and/or code to a previous point, or summarize from a selected message. See [checkpointing](https://code.claude.com/docs/en/checkpointing.md). Aliases: `/checkpoint`, `/undo` |

137| `/run` | **[Skill](https://code.claude.com/docs/en/skills.md#bundled-skills).** Launch and drive your project's app to see a change working, not only passing tests. See [Run and verify your app](https://code.claude.com/docs/en/skills.md#run-and-verify-your-app) |137| `/run` | **[Skill](https://code.claude.com/docs/en/skills.md#bundled-skills).** Launch and drive your project's app to see a change working, not only passing tests. See [Run and verify your app](https://code.claude.com/docs/en/skills.md#run-and-verify-your-app) |

138| `/run-skill-generator` | **[Skill](https://code.claude.com/docs/en/skills.md#bundled-skills).** Teach `/run` and `/verify` how to build, launch, and drive your project's app from a clean environment by writing a per-project [skill](https://code.claude.com/docs/en/skills.md#run-and-verify-your-app) |138| `/run-skill-generator` | **[Skill](https://code.claude.com/docs/en/skills.md#bundled-skills).** Teach `/run` and `/verify` how to build, launch, and drive your project's app from a clean environment by writing a per-project [skill](https://code.claude.com/docs/en/skills.md#run-and-verify-your-app) |

costs.md +6 −6

Details

292 292

293Custom [hooks](https://code.claude.com/docs/en/hooks.md) can preprocess data before Claude sees it. Instead of Claude reading a 10,000-line log file to find errors, a hook can grep for `ERROR` and return only matching lines, reducing context from tens of thousands of tokens to hundreds.293Custom [hooks](https://code.claude.com/docs/en/hooks.md) can preprocess data before Claude sees it. Instead of Claude reading a 10,000-line log file to find errors, a hook can grep for `ERROR` and return only matching lines, reducing context from tens of thousands of tokens to hundreds.

294 294

295A [skill](https://code.claude.com/docs/en/skills.md) can give Claude domain knowledge so it doesn't have to explore. For example, a "codebase-overview" skill could describe your project's architecture, key directories, and naming conventions. When Claude invokes the skill, it gets this context immediately instead of spending tokens reading multiple files to understand the structure.295This PreToolUse hook trims test output to its last 100 lines:

~~296~~

297For example, this PreToolUse hook filters test output to show only failures:

298 296

299> [tab] settings.json297> [tab] settings.json

300>298>

320 318

321> [tab] filter-test-output.sh319> [tab] filter-test-output.sh

322>320>

323> The hook calls this script. Create the folder with `mkdir -p ~/.claude/hooks`, save the script below as `~/.claude/hooks/filter-test-output.sh`, and make it executable with `chmod +x ~/.claude/hooks/filter-test-output.sh`. It checks if the command is a test runner and modifies it to show only failures:321> The hook calls this script. Create the folder with `mkdir -p ~/.claude/hooks`, save the script below as `~/.claude/hooks/filter-test-output.sh`, and make it executable with `chmod +x ~/.claude/hooks/filter-test-output.sh`. It checks if the command is a test runner and, if so, keeps only the last 100 lines of its output:

324>322>

325> ```bash theme={null}323> ```bash theme={null}

326> #!/bin/bash324> #!/bin/bash

327> input=$(cat)325> input=$(cat)

328> cmd=$(echo "$input" | jq -r '.tool_input.command')326> cmd=$(echo "$input" | jq -r '.tool_input.command')

329>327>

330> # If running tests, filter to show only failures328> # If running tests, keep only the last 100 lines

332> if [[ "$cmd" =~ $pattern ]]; then330> if [[ "$cmd" =~ $pattern ]]; then

334> echo "$input" | jq --arg filtered "$filtered_cmd" \332> echo "$input" | jq --arg filtered "$filtered_cmd" \

335> '{hookSpecificOutput: {hookEventName: "PreToolUse", updatedInput: (.tool_input + {command: $filtered})}}'333> '{hookSpecificOutput: {hookEventName: "PreToolUse", updatedInput: (.tool_input + {command: $filtered})}}'

336> else334> else

340 338

341To verify the setup, run `/hooks` and check that the hook appears under PreToolUse. You can also start Claude Code with `claude --debug-file ./claude-debug.txt` and ask Claude to run `npm test`. When the hook rewrites the command, that log file contains a `modified tool input keys` line listing `command` and the other Bash input fields.339To verify the setup, run `/hooks` and check that the hook appears under PreToolUse. You can also start Claude Code with `claude --debug-file ./claude-debug.txt` and ask Claude to run `npm test`. When the hook rewrites the command, that log file contains a `modified tool input keys` line listing `command` and the other Bash input fields.

342 340

341A [skill](https://code.claude.com/docs/en/skills.md) can give Claude domain knowledge so it doesn't have to explore. For example, a "codebase-overview" skill could describe your project's architecture, key directories, and naming conventions. When Claude invokes the skill, it gets this context immediately instead of spending tokens reading multiple files to understand the structure.

342

343### Move instructions from CLAUDE.md to skills343### Move instructions from CLAUDE.md to skills

344 344

345Your [CLAUDE.md](https://code.claude.com/docs/en/memory.md) file is loaded into context at session start. If it contains detailed instructions for specific workflows (like PR reviews or database migrations), those tokens are present even when you're doing unrelated work. [Skills](https://code.claude.com/docs/en/skills.md) load on-demand only when invoked, so moving specialized instructions into skills keeps your base context smaller. Aim to keep CLAUDE.md under 200 lines by including only essentials.345Your [CLAUDE.md](https://code.claude.com/docs/en/memory.md) file is loaded into context at session start. If it contains detailed instructions for specific workflows (like PR reviews or database migrations), those tokens are present even when you're doing unrelated work. [Skills](https://code.claude.com/docs/en/skills.md) load on-demand only when invoked, so moving specialized instructions into skills keeps your base context smaller. Aim to keep CLAUDE.md under 200 lines by including only essentials.

cross-session-messaging.md +1 −1

Details

56 56

57### Message delivery57### Message delivery

58 58

59The receiving Claude reads the message between tool calls during an active turn, so a running tool is never interrupted. When the receiving session is idle, Claude Code starts a new turn with the message.59The receiving Claude reads the message between tool calls during an active turn. When the receiving session is idle, Claude Code starts a new turn with the message.

60 60

61A message from another session arrives as plain text. If it mentions a file or an [MCP resource](https://code.claude.com/docs/en/mcp.md#use-mcp-resources) with `@`, Claude sees the mention as written and Claude Code attaches nothing, whether the message starts a new turn or arrives during one. Claude can still open a mentioned path on the receiving machine with its own tools, subject to that session's permissions.61A message from another session arrives as plain text. If it mentions a file or an [MCP resource](https://code.claude.com/docs/en/mcp.md#use-mcp-resources) with `@`, Claude sees the mention as written and Claude Code attaches nothing, whether the message starts a new turn or arrives during one. Claude can still open a mentioned path on the receiving machine with its own tools, subject to that session's permissions.

62 62

desktop.md +2 −2

Details

256 256

257### Minimize a pane257### Minimize a pane

258 258

259To keep the Terminal, Browser, or [iOS Simulator](https://code.claude.com/docs/en/desktop-ios-simulator.md) in view at a small size, click **Minimize** in the pane's header. The button requires Claude Desktop v4.0.0 or later and a Claude account rather than a [third-party provider](https://code.claude.com/docs/en/third-party-integrations.md). The Browser pane has it only in local sessions.259To keep the Terminal, Browser, [iOS Simulator](https://code.claude.com/docs/en/desktop-ios-simulator.md), or a [side chat](#ask-a-side-question-without-derailing-the-session) in view at a small size, click **Minimize** in the pane's header. The button requires Claude Desktop v4.0.0 or later and a Claude account rather than a [third-party provider](https://code.claude.com/docs/en/third-party-integrations.md). The Browser pane has it only in local sessions.

260 260

261The minimized pane sits in the [session details panel](#see-session-details) while that panel is on screen, and floats in a corner of the chat otherwise:261The minimized pane sits in the [session details panel](#see-session-details) while that panel is on screen, and floats in a corner of the chat otherwise:

262 262

2050 2050

2051* **Local sessions on this machine**: a managed settings file deployed to disk applies. Managed settings pushed remotely through the admin console also reach these sessions on Anthropic's API when the session authenticates with an [eligible login](https://code.claude.com/docs/en/server-managed-settings.md#platform-availability), following the same [settings precedence](https://code.claude.com/docs/en/settings.md#settings-precedence) as the terminal CLI.2051* **Local sessions on this machine**: a managed settings file deployed to disk applies. Managed settings pushed remotely through the admin console also reach these sessions on Anthropic's API when the session authenticates with an [eligible login](https://code.claude.com/docs/en/server-managed-settings.md#platform-availability), following the same [settings precedence](https://code.claude.com/docs/en/settings.md#settings-precedence) as the terminal CLI.

2052* **[Cloud sessions](#cloud-sessions)**: receive [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md); device-deployed files don't reach them, because they run on Anthropic-managed VMs. Sessions routed to a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments) also read the managed settings file in the runner image. [How Claude Code combines managed sources](https://code.claude.com/docs/en/managed-settings.md#how-claude-code-combines-managed-sources) says when that file applies.2052* **[Cloud sessions](#cloud-sessions)**: receive [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md); device-deployed files don't reach them, because they run on Anthropic-managed VMs. Sessions routed to a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments) also read the managed settings file in the runner image. [How Claude Code combines managed sources](https://code.claude.com/docs/en/managed-settings.md#how-claude-code-combines-managed-sources) says when that file applies.

2053* **[SSH sessions](#ssh-sessions)**: the session reads the managed settings file from the remote host. Desktop itself reads `sshConfigs`, `sshHostAllowlist`, `disableSshSavedPasswords`, and `disableDesktopLocalSessions` on the local machine. If you deliver more than one managed source, it reads them from [one by default](https://code.claude.com/docs/en/managed-settings.md#how-claude-code-combines-managed-sources).2053* **[SSH sessions](#ssh-sessions)**: the session reads the managed settings file from the remote host. Desktop itself reads `sshConfigs`, `sshHostAllowlist`, `disableSshSavedPasswords`, and `disableDesktopLocalSessions` on the local machine. If you deliver more than one managed source, it reads them from [one by default](https://code.claude.com/docs/en/managed-settings.md#how-claude-code-combines-managed-sources). If you set `permissions.disableBypassPermissionsMode` or `disableAutoMode` in the managed settings in force on the local machine, an SSH session's mode selector doesn't offer that mode, whatever the remote host sets.

2054* **[Cowork](https://claude.com/docs/cowork/overview) sessions**: in a Cowork session on this machine, Claude Code never fetches admin-console settings, even when the user signs in with a Team or Enterprise account, and reads policy deployed to the machine unless your Claude Desktop configuration sets `requireCoworkFullVmSandbox`. Remote Cowork sessions receive neither. See [where and when a policy applies](https://code.claude.com/docs/en/managed-settings.md#where-and-when-a-policy-applies) for which device files reach Cowork, and [MCP permission rules](https://code.claude.com/docs/en/permissions.md#mcp) for how `Bash` and `WebFetch` rules apply to Cowork's tools.2054* **[Cowork](https://claude.com/docs/cowork/overview) sessions**: in a Cowork session on this machine, Claude Code never fetches admin-console settings, even when the user signs in with a Team or Enterprise account, and reads policy deployed to the machine unless your Claude Desktop configuration sets `requireCoworkFullVmSandbox`. Remote Cowork sessions receive neither. See [where and when a policy applies](https://code.claude.com/docs/en/managed-settings.md#where-and-when-a-policy-applies) for which device files reach Cowork, and [MCP permission rules](https://code.claude.com/docs/en/permissions.md#mcp) for how `Bash` and `WebFetch` rules apply to Cowork's tools.

2055 2055

2056In local and SSH sessions, the desktop app delivers each user's connected claude.ai connectors to Claude Code directly. No MCP setting or `managed-mcp.json` reaches those connectors, whichever settings source or file location you use. To block a connector's tools in these sessions, use your organization's [connector tool controls](https://code.claude.com/docs/en/mcp.md#organization-controls-on-connector-tools). [How connectors reach Claude Code](https://code.claude.com/docs/en/mcp.md#how-connectors-reach-claude-code) shows which settings govern connectors in each kind of session.2056In local and SSH sessions, the desktop app delivers each user's connected claude.ai connectors to Claude Code directly. No MCP setting or `managed-mcp.json` reaches those connectors, whichever settings source or file location you use. To block a connector's tools in these sessions, use your organization's [connector tool controls](https://code.claude.com/docs/en/mcp.md#organization-controls-on-connector-tools). [How connectors reach Claude Code](https://code.claude.com/docs/en/mcp.md#how-connectors-reach-claude-code) shows which settings govern connectors in each kind of session.

desktop-ios-simulator.md +2 −2

Details

8 8

9> [!NOTE]9> [!NOTE]

10>10>

11> The iOS Simulator pane is in public beta in Claude Code Desktop on macOS. It's available on Pro, Max, Ultra, Team, and Enterprise plans, except in Enterprise organizations that have a HIPAA configuration enabled.11> The iOS Simulator pane is in public beta in Claude Code Desktop on macOS. It's available on Pro, Max, Ultra, Team, and Enterprise plans, except in Enterprise organizations that have a HIPAA configuration enabled. It isn't available if you use a [third-party provider](https://code.claude.com/docs/en/third-party-integrations.md).

12 12

13The iOS Simulator pane shows your app running in Apple's iOS Simulator next to your conversation in Claude Code Desktop. When Claude builds, installs, launches, or checks your app in a simulator, the pane opens automatically and streams the device screen live. Use it to watch Claude run and test your app, or to tap through the app yourself while Claude keeps working.13The iOS Simulator pane shows your app running in Apple's iOS Simulator next to your conversation in Claude Code Desktop. When Claude builds, installs, launches, or checks your app in a simulator, the pane opens automatically and streams the device screen live. Use it to watch Claude run and test your app, or to tap through the app yourself while Claude keeps working.

14 14

147* State the goal explicitly, for example "run the app in the iOS Simulator and tap through the signup flow".147* State the goal explicitly, for example "run the app in the iOS Simulator and tap through the signup flow".

148* Confirm Xcode and the iOS simulators are installed and that you're using a [recommended Xcode version](#requirements).148* Confirm Xcode and the iOS simulators are installed and that you're using a [recommended Xcode version](#requirements).

149* If your organization manages Claude Code, the [simulator tools may be disabled by policy](#turn-off-simulator-access).149* If your organization manages Claude Code, the [simulator tools may be disabled by policy](#turn-off-simulator-access).

150* If you're in an Enterprise organization that has a HIPAA configuration enabled, the simulator pane isn't available to you.150* If you're in an Enterprise organization that has a HIPAA configuration enabled, or you use a [third-party provider](https://code.claude.com/docs/en/third-party-integrations.md), the simulator pane isn't available to you.

151* The simulator pane requires Claude Desktop v1.24012.0 or later. Open **Claude > Check for Updates…**, then restart the app.151* The simulator pane requires Claude Desktop v1.24012.0 or later. Open **Claude > Check for Updates…**, then restart the app.

152 152

153### The simulator pane says no simulators were found153### The simulator pane says no simulators were found

env-vars.md +10 −9

Details

204| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | Set to `0` to stop Claude Code from opening the browser automatically when a new [artifact](https://code.claude.com/docs/en/artifacts.md#create-an-artifact) is published |204| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | Set to `0` to stop Claude Code from opening the browser automatically when a new [artifact](https://code.claude.com/docs/en/artifacts.md#create-an-artifact) is published |

205| `CLAUDE_CODE_ARTIFACT_COMMENTS` | Set to `0` to stop Claude reading and replying to [comments on an artifact](https://code.claude.com/docs/en/artifacts.md#collect-comments-on-an-artifact). Has no effect when `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` has [turned artifacts off](https://code.claude.com/docs/en/artifacts.md#availability). Requires Claude Code v2.1.221 or later |205| `CLAUDE_CODE_ARTIFACT_COMMENTS` | Set to `0` to stop Claude reading and replying to [comments on an artifact](https://code.claude.com/docs/en/artifacts.md#collect-comments-on-an-artifact). Has no effect when `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` has [turned artifacts off](https://code.claude.com/docs/en/artifacts.md#availability). Requires Claude Code v2.1.221 or later |

206| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | Set to `0` to stop Claude [replying on its own to comments sent to it](https://code.claude.com/docs/en/artifacts.md#let-claude-reply-to-comments-on-its-own). Requires Claude Code v2.1.228 or later |206| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | Set to `0` to stop Claude [replying on its own to comments sent to it](https://code.claude.com/docs/en/artifacts.md#let-claude-reply-to-comments-on-its-own). Requires Claude Code v2.1.228 or later |

207| `CLAUDE_CODE_ARTIFACT_PUBLISH_EDITS` | Set to `0` to stop Claude from applying small changes to an [artifact's](https://code.claude.com/docs/en/artifacts.md#update-an-artifact) file as part of publishing it. Claude then edits the file with its file-editing tools and publishes it as a separate step. Requires Claude Code v2.1.300 or later |207| `CLAUDE_CODE_ARTIFACT_PUBLISH_EDITS` | Set to `0` to stop Claude from [applying small changes](https://code.claude.com/docs/en/artifacts.md#turn-off-one-step-artifact-updates) to an artifact's file as part of publishing it. Claude then edits the file with its file-editing tools and publishes it as a separate step. Requires Claude Code v2.1.300 or later |

208| `CLAUDE_CODE_ATTRIBUTION_HEADER` | Set to `0` to omit the [attribution block](https://code.claude.com/docs/en/llm-gateway-protocol.md#system-prompt-attribution-block), which carries the client version and a prompt fingerprint, from the start of the system prompt. Caching on a direct connection to the Anthropic API is unaffected either way. In some direct-connection setups, Claude Code keeps the block on [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) classifier requests even when you set `0`. In [System prompt attribution block](https://code.claude.com/docs/en/llm-gateway-protocol.md#system-prompt-attribution-block), check which connections and credentials this covers. Before v2.1.181 the block included a per-request token on custom base URLs and Microsoft Foundry connections, so on those versions set it to `0` when your LLM gateway caches on the request body or forwards requests to a third-party provider, or when you connect to Microsoft Foundry directly |208| `CLAUDE_CODE_ATTRIBUTION_HEADER` | Set to `0` to omit the [attribution block](https://code.claude.com/docs/en/llm-gateway-protocol.md#system-prompt-attribution-block), which carries the client version and a prompt fingerprint, from the start of the system prompt. Caching on a direct connection to the Anthropic API is unaffected either way. In some direct-connection setups, Claude Code keeps the block on [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) classifier requests even when you set `0`. In [System prompt attribution block](https://code.claude.com/docs/en/llm-gateway-protocol.md#system-prompt-attribution-block), check which connections and credentials this covers. Before v2.1.181 the block included a per-request token on custom base URLs and Microsoft Foundry connections, so on those versions set it to `0` when your LLM gateway caches on the request body or forwards requests to a third-party provider, or when you connect to Microsoft Foundry directly |

209| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | Removed in v2.1.283. Use `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE` instead |209| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | Removed in v2.1.283. Use `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE` instead |

210| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Set the auto-compact window, how full the context gets before compaction, from `100000` to `1000000` tokens. Suffixed values such as `200k` require v2.1.304 or later. For precedence over the other ways to set the window and the effect on the status line's `used_percentage`, see [Set the auto-compact window](https://code.claude.com/docs/en/model-config.md#set-the-auto-compact-window) |210| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Set the auto-compact window, how full the context gets before compaction, from `100000` to `1000000` tokens. Suffixed values such as `200k` require v2.1.304 or later. For precedence over the other ways to set the window and the effect on the status line's `used_percentage`, see [Set the auto-compact window](https://code.claude.com/docs/en/model-config.md#set-the-auto-compact-window) |

248| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Set to `1` to strip pre-release `anthropic-beta` request headers, the body fields that pair with them, and beta tool-schema fields such as `defer_loading` and `eager_input_streaming` from API requests. Use this when a proxy gateway rejects requests with an `Unexpected value(s)` error for the `anthropic-beta` header or an `Extra inputs are not permitted` error. [Disable pre-release capabilities](https://code.claude.com/docs/en/llm-gateway-protocol.md#disable-pre-release-capabilities) lists what the variable removes, including [MCP tool search](https://code.claude.com/docs/en/mcp.md#scale-with-mcp-tool-search), and what Claude Code keeps sending |248| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Set to `1` to strip pre-release `anthropic-beta` request headers, the body fields that pair with them, and beta tool-schema fields such as `defer_loading` and `eager_input_streaming` from API requests. Use this when a proxy gateway rejects requests with an `Unexpected value(s)` error for the `anthropic-beta` header or an `Extra inputs are not permitted` error. [Disable pre-release capabilities](https://code.claude.com/docs/en/llm-gateway-protocol.md#disable-pre-release-capabilities) lists what the variable removes, including [MCP tool search](https://code.claude.com/docs/en/mcp.md#scale-with-mcp-tool-search), and what Claude Code keeps sending |

249| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | Set to `1` to disable the built-in [Explore and Plan subagents](https://code.claude.com/docs/en/sub-agents.md#built-in-subagents). Claude explores with its search tools or the general-purpose subagent instead, and [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) reads files directly rather than launching Explore and Plan agents. Custom subagents named `Explore` or `Plan` are unaffected. To remove every built-in subagent type in the Agent SDK or non-interactive mode, use `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` instead. Requires Claude Code v2.1.198 or later |249| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | Set to `1` to disable the built-in [Explore and Plan subagents](https://code.claude.com/docs/en/sub-agents.md#built-in-subagents). Claude explores with its search tools or the general-purpose subagent instead, and [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) reads files directly rather than launching Explore and Plan agents. Custom subagents named `Explore` or `Plan` are unaffected. To remove every built-in subagent type in the Agent SDK or non-interactive mode, use `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` instead. Requires Claude Code v2.1.198 or later |

251| `CLAUDE_CODE_DISABLE_FEATURE_FLAGS` | Set to `1` to turn off feature-flag fetching. Requires Claude Code v2.1.319 or later. With this variable set, [Remote Control](https://code.claude.com/docs/en/remote-control.md#requirements) and the other [features that need feature-flag fetching](#features-that-need-feature-flag-fetching) are unavailable. Telemetry event logging stays on unless `DISABLE_TELEMETRY` is also set. The older name, `DISABLE_GROWTHBOOK`, still works, and it is the only one that v2.1.124 through v2.1.318 read |

251| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | Set to `1` to disable the "How is Claude doing?" session quality surveys. Surveys are also disabled when `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` is set, unless `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` opts back in. To set a sample rate instead of disabling outright, use the [`feedbackSurveyRate`](https://code.claude.com/docs/en/settings-reference#feedbacksurveyrate) setting. See [Session quality surveys](https://code.claude.com/docs/en/data-usage.md#session-quality-surveys) |252| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | Set to `1` to disable the "How is Claude doing?" session quality surveys. Surveys are also disabled when `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` is set, unless `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` opts back in. To set a sample rate instead of disabling outright, use the [`feedbackSurveyRate`](https://code.claude.com/docs/en/settings-reference#feedbacksurveyrate) setting. See [Session quality surveys](https://code.claude.com/docs/en/data-usage.md#session-quality-surveys) |

252| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | Set to `1` to disable file [checkpointing](https://code.claude.com/docs/en/checkpointing.md). The `/rewind` command will not be able to restore code changes. Overrides the [`fileCheckpointingEnabled`](https://code.claude.com/docs/en/settings-reference#filecheckpointingenabled) setting |253| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | Set to `1` to disable file [checkpointing](https://code.claude.com/docs/en/checkpointing.md). The `/rewind` command will not be able to restore code changes. Overrides the [`fileCheckpointingEnabled`](https://code.claude.com/docs/en/settings-reference#filecheckpointingenabled) setting |

253| `CLAUDE_CODE_DISABLE_FILE_MENTIONS` | Set to `1` to stop Claude Code from expanding [`@` mentions](https://code.claude.com/docs/en/common-workflows#reference-files-and-directories) of files and directories. Claude instead gets the mentioned paths with a note to read them using its file tools. Ignored in [project and local settings](https://code.claude.com/docs/en/settings-reference.md#variables-claude-code-ignores-in-env). Requires Claude Code v2.1.299 or later |254| `CLAUDE_CODE_DISABLE_FILE_MENTIONS` | Set to `1` to stop Claude Code from expanding [`@` mentions](https://code.claude.com/docs/en/common-workflows#reference-files-and-directories) of files and directories. Claude instead gets the mentioned paths with a note to read them using its file tools. Ignored in [project and local settings](https://code.claude.com/docs/en/settings-reference.md#variables-claude-code-ignores-in-env). Requires Claude Code v2.1.299 or later |

451| `DISABLE_ERROR_REPORTING` | Set to any non-empty value, such as `1`, to opt out of error reporting. **Setting it to `0` or `false` still opts out**, unlike most on/off variables; unset the variable to turn error reporting back on |452| `DISABLE_ERROR_REPORTING` | Set to any non-empty value, such as `1`, to opt out of error reporting. **Setting it to `0` or `false` still opts out**, unlike most on/off variables; unset the variable to turn error reporting back on |

452| `DISABLE_EXTRA_USAGE_COMMAND` | Set to `1` to hide the `/usage-credits` command that lets users purchase additional usage beyond rate limits |453| `DISABLE_EXTRA_USAGE_COMMAND` | Set to `1` to hide the `/usage-credits` command that lets users purchase additional usage beyond rate limits |

453| `DISABLE_FEEDBACK_COMMAND` | Set to `1` to disable the `/feedback` command and [Claude-drafted feedback](https://code.claude.com/docs/en/tools-reference.md#sendfeedback-tool-behavior). Also disables `/bug` and `/share`, which report through the same path; before v2.1.212 they were aliases of `/feedback`, so the command was disabled under every name. The older name `DISABLE_BUG_COMMAND` is also accepted |454| `DISABLE_FEEDBACK_COMMAND` | Set to `1` to disable the `/feedback` command and [Claude-drafted feedback](https://code.claude.com/docs/en/tools-reference.md#sendfeedback-tool-behavior). Also disables `/bug` and `/share`, which report through the same path; before v2.1.212 they were aliases of `/feedback`, so the command was disabled under every name. The older name `DISABLE_BUG_COMMAND` is also accepted |

454| `DISABLE_GROWTHBOOK` | Set to `1` or `true` to disable feature-flag fetching and use code defaults for every flag. This makes [Remote Control](https://code.claude.com/docs/en/remote-control.md#requirements) and the other [features that need feature-flag fetching](#features-that-need-feature-flag-fetching) unavailable. Setting it to `0` or `false` leaves fetching on. Telemetry event logging stays on unless `DISABLE_TELEMETRY` is also set |455| `DISABLE_GROWTHBOOK` | Set to `1` to turn off [feature-flag fetching](#features-that-need-feature-flag-fetching). Requires Claude Code v2.1.124 or later. Superseded by `CLAUDE_CODE_DISABLE_FEATURE_FLAGS`, which requires v2.1.319 or later: use that name unless a machine on v2.1.318 or earlier reads the configuration. This name still works |

455| `DISABLE_INSTALLATION_CHECKS` | Set to `1` to disable installation warnings. Use only when manually managing the installation location, as this can mask issues with standard installations |456| `DISABLE_INSTALLATION_CHECKS` | Set to `1` to disable installation warnings. Use only when manually managing the installation location, as this can mask issues with standard installations |

456| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | Set to `1` to hide the `/install-github-app` command. Already hidden when using third-party providers (Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry) |457| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | Set to `1` to hide the `/install-github-app` command. Already hidden when using third-party providers (Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry) |

457| `DISABLE_INTERLEAVED_THINKING` | Set to `1` to prevent sending the interleaved-thinking beta header. Useful when your LLM gateway or provider does not support [interleaved thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) |458| `DISABLE_INTERLEAVED_THINKING` | Set to `1` to prevent sending the interleaved-thinking beta header. Useful when your LLM gateway or provider does not support [interleaved thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) |

502| `OTEL_LOG_TOOL_CONTENT` | Set to `1` to include tool content in the `tool.output` OpenTelemetry span event. Span attributes carry tool content under [their own gates](https://code.claude.com/docs/en/monitoring-usage.md#new-context-gates). Requires [tracing](https://code.claude.com/docs/en/monitoring-usage.md#traces-beta). Disabled by default to protect sensitive data. Set it in your shell, user settings, or managed settings. Ignored in [project and local settings](https://code.claude.com/docs/en/settings-reference.md#variables-claude-code-ignores-in-env), apart from the off values that section describes. See [Monitoring](https://code.claude.com/docs/en/monitoring-usage.md#tool-output-span-event) |503| `OTEL_LOG_TOOL_CONTENT` | Set to `1` to include tool content in the `tool.output` OpenTelemetry span event. Span attributes carry tool content under [their own gates](https://code.claude.com/docs/en/monitoring-usage.md#new-context-gates). Requires [tracing](https://code.claude.com/docs/en/monitoring-usage.md#traces-beta). Disabled by default to protect sensitive data. Set it in your shell, user settings, or managed settings. Ignored in [project and local settings](https://code.claude.com/docs/en/settings-reference.md#variables-claude-code-ignores-in-env), apart from the off values that section describes. See [Monitoring](https://code.claude.com/docs/en/monitoring-usage.md#tool-output-span-event) |

503| `OTEL_LOG_TOOL_DETAILS` | Set to `1` to include tool input arguments; MCP server names; user-authored workflow names; raw error strings on tool failures; the refusal `category` on `api_refusal` events; real agent, skill, plugin, and MCP server names on [cost and token metrics](https://code.claude.com/docs/en/monitoring-usage.md#cost-counter); and other tool details in OpenTelemetry metrics, traces, and logs. Disabled by default to protect PII. Set it in your shell, user settings, or managed settings. Ignored in [project and local settings](https://code.claude.com/docs/en/settings-reference.md#variables-claude-code-ignores-in-env), apart from the off values that section describes. See [Monitoring](https://code.claude.com/docs/en/monitoring-usage.md) |504| `OTEL_LOG_TOOL_DETAILS` | Set to `1` to include tool input arguments; MCP server names; user-authored workflow names; raw error strings on tool failures; the refusal `category` on `api_refusal` events; real agent, skill, plugin, and MCP server names on [cost and token metrics](https://code.claude.com/docs/en/monitoring-usage.md#cost-counter); and other tool details in OpenTelemetry metrics, traces, and logs. Disabled by default to protect PII. Set it in your shell, user settings, or managed settings. Ignored in [project and local settings](https://code.claude.com/docs/en/settings-reference.md#variables-claude-code-ignores-in-env), apart from the off values that section describes. See [Monitoring](https://code.claude.com/docs/en/monitoring-usage.md) |

504| `OTEL_LOG_USER_PROMPTS` | Set to `1` to include user prompt text in OpenTelemetry traces and logs. Disabled by default (prompts are redacted). Set it in your shell, user settings, or managed settings. Ignored in [project and local settings](https://code.claude.com/docs/en/settings-reference.md#variables-claude-code-ignores-in-env), apart from the off values that section describes. See [Monitoring](https://code.claude.com/docs/en/monitoring-usage.md) |505| `OTEL_LOG_USER_PROMPTS` | Set to `1` to include user prompt text in OpenTelemetry traces and logs. Disabled by default (prompts are redacted). Set it in your shell, user settings, or managed settings. Ignored in [project and local settings](https://code.claude.com/docs/en/settings-reference.md#variables-claude-code-ignores-in-env), apart from the off values that section describes. See [Monitoring](https://code.claude.com/docs/en/monitoring-usage.md) |

505| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | Set to `false` to exclude account UUID from metrics attributes (default: included). See [Monitoring](https://code.claude.com/docs/en/monitoring-usage.md) |506| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | Set to `false` to exclude account UUID from metric and event attributes (default: included). See [Monitoring](https://code.claude.com/docs/en/monitoring-usage.md) |

506| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | Set to `true` to include the session entrypoint in metrics attributes (default: excluded). Added in v2.1.152. See [Monitoring](https://code.claude.com/docs/en/monitoring-usage.md) |507| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | Set to `true` to include the session entrypoint in metric and event attributes (default: excluded). Added in v2.1.152. See [Monitoring](https://code.claude.com/docs/en/monitoring-usage.md) |

507| `OTEL_METRICS_INCLUDE_REPOSITORY` | Set to `true` to tag OpenTelemetry metrics and events with `vcs.*` attributes identifying the session's repository (default: excluded). Requires Claude Code v2.1.269 or later. See [Repository attributes](https://code.claude.com/docs/en/monitoring-usage.md#repository-attributes) |508| `OTEL_METRICS_INCLUDE_REPOSITORY` | Set to `true` to tag OpenTelemetry metrics and events with `vcs.*` attributes identifying the session's repository (default: excluded). Requires Claude Code v2.1.269 or later. See [Repository attributes](https://code.claude.com/docs/en/monitoring-usage.md#repository-attributes) |

508| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | As of v2.1.161, Claude Code attaches `OTEL_RESOURCE_ATTRIBUTES` keys to metric datapoint labels. Set to `false` to exclude them (default: included). See [Monitoring](https://code.claude.com/docs/en/monitoring-usage.md#multi-team-organization-support) |509| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | As of v2.1.161, Claude Code attaches `OTEL_RESOURCE_ATTRIBUTES` keys to metric datapoint labels. Set to `false` to exclude them (default: included). See [Monitoring](https://code.claude.com/docs/en/monitoring-usage.md#multi-team-organization-support) |

509| `OTEL_METRICS_INCLUDE_SESSION_ID` | Set to `false` to exclude session ID from metrics attributes (default: included). See [Monitoring](https://code.claude.com/docs/en/monitoring-usage.md) |510| `OTEL_METRICS_INCLUDE_SESSION_ID` | Set to `false` to exclude session ID from metric and event attributes (default: included). See [Monitoring](https://code.claude.com/docs/en/monitoring-usage.md) |

510| `OTEL_METRICS_INCLUDE_VERSION` | Set to `true` to include Claude Code version in metrics attributes (default: excluded). See [Monitoring](https://code.claude.com/docs/en/monitoring-usage.md) |511| `OTEL_METRICS_INCLUDE_VERSION` | Set to `true` to include Claude Code version in metric and event attributes (default: excluded). See [Monitoring](https://code.claude.com/docs/en/monitoring-usage.md) |

511| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Override the character budget for skill metadata shown to the [Skill tool](https://code.claude.com/docs/en/skills.md#control-who-invokes-a-skill). The budget scales dynamically at 1% of the context window, with a fallback of 8,000 characters. Legacy name kept for backwards compatibility |512| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Override the character budget for skill metadata shown to the [Skill tool](https://code.claude.com/docs/en/skills.md#control-who-invokes-a-skill). The budget scales dynamically at 1% of the context window, with a fallback of 8,000 characters. Legacy name kept for backwards compatibility |

512| `TASK_MAX_OUTPUT_LENGTH` | Removed in v2.1.277 and now a no-op, together with the `TaskOutput` tool it sized. Previously set the maximum number of characters of a [background task's](https://code.claude.com/docs/en/tools-reference.md#background-commands) output that the `TaskOutput` tool kept. Claude reads a background task's output file with `Read` instead |513| `TASK_MAX_OUTPUT_LENGTH` | Removed in v2.1.277 and now a no-op, together with the `TaskOutput` tool it sized. Previously set the maximum number of characters of a [background task's](https://code.claude.com/docs/en/tools-reference.md#background-commands) output that the `TaskOutput` tool kept. Claude reads a background task's output file with `Read` instead |

569 570

570Claude Code turns some features on through feature flags it fetches from Anthropic. Claude Code skips that fetch in these sessions:571Claude Code turns some features on through feature flags it fetches from Anthropic. Claude Code skips that fetch in these sessions:

571 572

572* A session where you set `DISABLE_GROWTHBOOK`, `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`; each variable's row in the [variables table](#variables) says which values turn fetching off573* A session where you set `CLAUDE_CODE_DISABLE_FEATURE_FLAGS`, `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`; each variable's row in the [variables table](#variables) says which values turn fetching off

573* A session on a [third-party provider](https://code.claude.com/docs/en/third-party-integrations.md), such as Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, or Microsoft Foundry, unless a host platform that embeds Claude Code sets `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`574* A session on a [third-party provider](https://code.claude.com/docs/en/third-party-integrations.md), such as Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, or Microsoft Foundry, unless a host platform that embeds Claude Code sets `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`

574* A [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway) session575* A [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway) session

575 576

576With fetching off, you can't:577With fetching off, you can't:

577 578

578* Use [Remote Control](https://code.claude.com/docs/en/remote-control.md) with `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` or `DISABLE_GROWTHBOOK` set. For `DISABLE_TELEMETRY` and `DO_NOT_TRACK`, see the [Remote Control requirements](https://code.claude.com/docs/en/remote-control.md#requirements)579* Use [Remote Control](https://code.claude.com/docs/en/remote-control.md) with `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` or [`CLAUDE_CODE_DISABLE_FEATURE_FLAGS`](#variables) set. For `DISABLE_TELEMETRY` and `DO_NOT_TRACK`, see the [Remote Control requirements](https://code.claude.com/docs/en/remote-control.md#requirements)

579* [Message sessions beyond this machine](https://code.claude.com/docs/en/cross-session-messaging.md#message-sessions-on-other-machines) when [Remote Control](https://code.claude.com/docs/en/remote-control.md#requirements) is unavailable. Messaging between sessions on this machine works with fetching off580* [Message sessions beyond this machine](https://code.claude.com/docs/en/cross-session-messaging.md#message-sessions-on-other-machines) when [Remote Control](https://code.claude.com/docs/en/remote-control.md#requirements) is unavailable. Messaging between sessions on this machine works with fetching off

580* Run [`claude import` or the `/import` command](https://code.claude.com/docs/en/cli-reference#cli-commands)581* Run [`claude import` or the `/import` command](https://code.claude.com/docs/en/cli-reference#cli-commands)

581* Run [`/skill-doctor`](https://code.claude.com/docs/en/skills#find-unused-skills) or open its report in the `/plugin` **Stats** tab582* Run [`/skill-doctor`](https://code.claude.com/docs/en/skills#find-unused-skills) or open its report in the `/plugin` **Stats** tab

582* Run [`/restart`](https://code.claude.com/docs/en/commands) on Pro, Max, and Ultra plans583* Run [`/restart`](https://code.claude.com/docs/en/commands) on Pro, Max, and Ultra plans

583* Sync the [skills](https://code.claude.com/docs/en/skills.md#where-synced-skills-load) and [plugins](https://code.claude.com/docs/en/plugins/loading.md#synced-plugins) enabled for your claude.ai account into your terminal sessions584* Sync the [skills](https://code.claude.com/docs/en/skills.md#where-synced-skills-load) and [plugins](https://code.claude.com/docs/en/plugins/loading.md#synced-plugins) enabled for your claude.ai account into your terminal sessions

584* Turn on the [You should know mod](https://code.claude.com/docs/en/interactive-mode.md#you-should-know-suggestions)585* Turn on the [You should know mod](https://code.claude.com/docs/en/interactive-mode.md#you-should-know-suggestions)

585* Use [the advisor tool](https://code.claude.com/docs/en/advisor.md#requirements)586* Use [the advisor tool](https://code.claude.com/docs/en/advisor.md#requirements), except on Claude Platform on AWS with Claude Code v2.1.300 or later

586* Use [MCP tasks](https://code.claude.com/docs/en/mcp.md#mcp-tasks-that-run-on-the-server)587* Use [MCP tasks](https://code.claude.com/docs/en/mcp.md#mcp-tasks-that-run-on-the-server)

587* Read or reply to [comments on an artifact](https://code.claude.com/docs/en/artifacts.md#collect-comments-on-an-artifact)588* Read or reply to [comments on an artifact](https://code.claude.com/docs/en/artifacts.md#collect-comments-on-an-artifact)

588* Have Claude read [another organization's public artifact](https://code.claude.com/docs/en/artifacts.md#read-an-artifact-shared-with-you)589* Have Claude read [another organization's public artifact](https://code.claude.com/docs/en/artifacts.md#read-an-artifact-shared-with-you)

errors.md +144 −15

Details

105| `Could not refresh your login because another Claude Code process is refreshing it` | [Authentication](#could-not-refresh-your-login) |105| `Could not refresh your login because another Claude Code process is refreshing it` | [Authentication](#could-not-refresh-your-login) |

106| `Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh` | [Authentication](#could-not-refresh-your-login) |106| `Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh` | [Authentication](#could-not-refresh-your-login) |

107| `Could not refresh your login: the disk that holds the Claude Code config directory (~/.claude by default), or your disk quota on it, is full` | [Authentication](#could-not-refresh-your-login-disk-full) |

108| `Failed to refresh OAuth token: the disk that holds the Claude Code config directory (~/.claude by default), or your disk quota on it, is full` | [Authentication](#could-not-refresh-your-login-disk-full) |

107| `Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted` | [Authentication](#your-account-is-on-hold) |109| `Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted` | [Authentication](#your-account-is-on-hold) |

108| `Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted` | [Authentication](#your-account-is-on-hold) |110| `Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted` | [Authentication](#your-account-is-on-hold) |

109| `Anthropic profile login expired · Re-authenticate your Anthropic profile` | [Authentication](#anthropic-profile-login-expired) |111| `Anthropic profile login expired · Re-authenticate your Anthropic profile` | [Authentication](#anthropic-profile-login-expired) |

242| `The current directory no longer exists (it was deleted or moved)` / `Can't read the current directory` | [Command-line errors](#the-current-directory-no-longer-exists) |244| `The current directory no longer exists (it was deleted or moved)` / `Can't read the current directory` | [Command-line errors](#the-current-directory-no-longer-exists) |

243| `Temp directory <dir> ... Refusing to use it` / `Claude Code's temporary directory <dir> could not be created` | [Command-line errors](#temp-directory-refused-or-cannot-be-created) |245| `Temp directory <dir> ... Refusing to use it` / `Claude Code's temporary directory <dir> could not be created` | [Command-line errors](#temp-directory-refused-or-cannot-be-created) |

247| `Error: Claude Code could not save ... because the disk is full (ENOSPC)` / `because your disk quota is used up (EDQUOT)` | [Command-line errors](#could-not-save-because-the-disk-is-full) |

245| `couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded` | [Command-line errors](#directory-couldnt-be-resolved-to-a-real-location) |248| `couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded` | [Command-line errors](#directory-couldnt-be-resolved-to-a-real-location) |

246| `Error: Workspace not trusted` when starting Remote Control | [Command-line errors](#workspace-not-trusted-when-starting-remote-control) |249| `Error: Workspace not trusted` when starting Remote Control | [Command-line errors](#workspace-not-trusted-when-starting-remote-control) |

247| `Error: Workspace not trusted` when running `claude ultrareview` | [Command-line errors](#workspace-not-trusted-when-running-claude-ultrareview) |250| `Error: Workspace not trusted` when running `claude ultrareview` | [Command-line errors](#workspace-not-trusted-when-running-claude-ultrareview) |

252| `Remote Control did not start: "<question>" got no answer` | [Command-line errors](#remote-control-did-not-start-got-no-answer) |

249| `` `<flag>` before `remote-control` is not carried over to the sessions Remote Control starts `` | [Command-line errors](#not-carried-over-to-the-sessions-remote-control-starts) |253| `` `<flag>` before `remote-control` is not carried over to the sessions Remote Control starts `` | [Command-line errors](#not-carried-over-to-the-sessions-remote-control-starts) |

250| `--sandbox is not supported by claude remote-control` / `--no-sandbox is not supported by claude remote-control` | [Command-line errors](#sandbox-is-not-supported-by-claude-remote-control) |254| `--sandbox is not supported by claude remote-control` / `--no-sandbox is not supported by claude remote-control` | [Command-line errors](#sandbox-is-not-supported-by-claude-remote-control) |

251| `` `claude import` is not yet available in this build `` | [Command-line errors](#claude-import-is-not-yet-available-in-this-build) |255| `` `claude import` is not yet available in this build `` | [Command-line errors](#claude-import-is-not-yet-available-in-this-build) |

320| `The packages it lists are not installed` / `The packages it lists were not installed, because` | [Plugin troubleshooting](https://code.claude.com/docs/en/plugins/troubleshooting.md#the-packages-it-lists-are-not-installed) |324| `The packages it lists are not installed` / `The packages it lists were not installed, because` | [Plugin troubleshooting](https://code.claude.com/docs/en/plugins/troubleshooting.md#the-packages-it-lists-are-not-installed) |

321| `does not load (...), so Claude Code ignores the whole file` | [Plugin troubleshooting](https://code.claude.com/docs/en/plugins/troubleshooting.md#does-not-load-so-claude-code-ignores-the-whole-file) |325| `does not load (...), so Claude Code ignores the whole file` | [Plugin troubleshooting](https://code.claude.com/docs/en/plugins/troubleshooting.md#does-not-load-so-claude-code-ignores-the-whole-file) |

327| `path not read: <path> is absolute or has a ".." part` | [Plugin errors](#server-file-path-not-read) |

325| `its marketplace entry path does not stay inside the marketplace directory` | [Plugin errors](#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory) |330| `its marketplace entry path does not stay inside the marketplace directory` | [Plugin errors](#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory) |

368| `Refusing to write <path>: where it leads on disk could not be determined` / `Refusing to read <path>: where it leads on disk could not be determined` | [Tool errors](#refusing-after-a-symlink-changed) |373| `Refusing to write <path>: where it leads on disk could not be determined` / `Refusing to read <path>: where it leads on disk could not be determined` | [Tool errors](#refusing-after-a-symlink-changed) |

369| `Refusing to search <path>: a path one of its Read deny rules is written through changed while the search was being prepared` / `Refusing to search <path>: it could not be opened` | [Tool errors](#refusing-after-a-symlink-changed) |374| `Refusing to search <path>: a path one of its Read deny rules is written through changed while the search was being prepared` / `Refusing to search <path>: it could not be opened` | [Tool errors](#refusing-after-a-symlink-changed) |

370| `its permission check expired before it ran (too many concurrent file operations)` / `ripgrep was found only by name on PATH` | [Tool errors](#refusing-after-a-symlink-changed) |375| `its permission check expired before it ran (too many concurrent file operations)` / `ripgrep was found only by name on PATH` | [Tool errors](#refusing-after-a-symlink-changed) |

376| `The search failed, so this is not a "no matches" result: matches may exist` | [Tool errors](#the-search-failed) |

372| `Command killed: its output file was replaced or could no longer be verified` | [Tool errors](#task-output-swap-refused) |378| `Command killed: its output file was replaced or could no longer be verified` | [Tool errors](#task-output-swap-refused) |

373| `Disk full: this computer's volume holding <dir> (Claude Code's temporary directory) has <n> MB free` / `Nearly out of inodes: this computer's volume holding <dir>` | [Tool errors](#disk-quota-or-temp-filesystem-is-full) |379| `Disk full: this computer's volume holding <dir> (Claude Code's temporary directory) has <n> MB free` / `Nearly out of inodes: this computer's volume holding <dir>` | [Tool errors](#disk-quota-or-temp-filesystem-is-full) |

377| `Command output was lost: the temp filesystem at <dir> is full` / `is out of inodes` | [Tool errors](#disk-quota-or-temp-filesystem-is-full) |383| `Command output was lost: the temp filesystem at <dir> is full` / `is out of inodes` | [Tool errors](#disk-quota-or-temp-filesystem-is-full) |

378| `File is not valid UTF-8. It may use a legacy encoding such as Windows-1252, Shift-JIS or GBK, or be binary` | [Tool errors](#file-is-not-valid-utf-8) |384| `File is not valid UTF-8. It may use a legacy encoding such as Windows-1252, Shift-JIS or GBK, or be binary` | [Tool errors](#file-is-not-valid-utf-8) |

379| `git is not installed on this Mac. To install it, run xcode-select --install, then try again.` | [Tool errors](#git-is-not-installed-on-this-mac) |385| `git is not installed on this Mac. To install it, run xcode-select --install, then try again.` | [Tool errors](#git-is-not-installed-on-this-mac) |

386| `Refusing to apply edits to <path>: a hook is configured for file edits in this session` | [Tool errors](#a-hook-is-configured-for-file-edits) |

380| `the source file is not valid UTF-8 text` / `the source file is not valid UTF-16 text` | [Tool errors](#the-source-file-is-not-valid-utf-8-text) |387| `the source file is not valid UTF-8 text` / `the source file is not valid UTF-16 text` | [Tool errors](#the-source-file-is-not-valid-utf-8-text) |

397| `MCP tool "<tool>" on server "<server>" gave no answer that could be read` / `answered without its text` | [How an MCP tool hook's result is read](https://code.claude.com/docs/en/hooks.md#how-the-tools-result-is-read) |

390| `Can't open MCP settings while no terminal is attached to this background session` | [Background session errors](#commands-refused-in-a-background-session) |398| `Can't open MCP settings while no terminal is attached to this background session` | [Background session errors](#commands-refused-in-a-background-session) |

391| `Can't open MCP settings in a background session` | [Background session errors](#commands-refused-in-a-background-session) |399| `Can't open MCP settings in a background session` | [Background session errors](#commands-refused-in-a-background-session) |

392| `blocked because the path is spelled in a form that cannot be safely resolved` | [Background session errors](#write-or-command-blocked-because-the-path-cannot-be-safely-resolved) |400| `blocked because the path is spelled in a form that cannot be safely resolved` | [Background session errors](#write-or-command-blocked-because-the-path-cannot-be-safely-resolved) |

397| `Can't open — this session is running in another terminal` | [Background session errors](#this-session-is-running-in-another-terminal) |405| `Can't open — this session is running in another terminal` | [Background session errors](#this-session-is-running-in-another-terminal) |

398| `This conversation is already open in another running Claude session` | [Background session errors](#this-session-is-running-in-another-terminal) |406| `This conversation is already open in another running Claude session` | [Background session errors](#this-session-is-running-in-another-terminal) |

399| `This session's saved conversation is no longer on disk` | [Background session errors](#this-sessions-saved-conversation-is-no-longer-on-disk) |407| `This session's saved conversation is no longer on disk` | [Background session errors](#this-sessions-saved-conversation-is-no-longer-on-disk) |

408| `This forked session could not be started. Fork the conversation again to retry.` | [Background session errors](#this-forked-session-could-not-be-started) |

400| `Bypass permissions was requested at launch and ignored` | [Bypass permissions ignored in a background session](https://code.claude.com/docs/en/permission-modes.md#bypass-permissions-ignored-in-a-background-session) |409| `Bypass permissions was requested at launch and ignored` | [Bypass permissions ignored in a background session](https://code.claude.com/docs/en/permission-modes.md#bypass-permissions-ignored-in-a-background-session) |

401| `kept <id> — its worktree is still at <path>` | [Background session errors](#worktree-has-commits-that-are-not-pushed-anywhere) if the message's next line mentions unpushed commits, otherwise [What deleting a session removes](https://code.claude.com/docs/en/agent-view.md#what-deleting-a-session-removes) |410| `kept <id> — its worktree is still at <path>` | [Background session errors](#worktree-has-commits-that-are-not-pushed-anywhere) if the message's next line mentions unpushed commits, otherwise [What deleting a session removes](https://code.claude.com/docs/en/agent-view.md#what-deleting-a-session-removes) |

402| `kept <id> — <n> unpushed commits on <branch>` | [Background session errors](#worktree-has-commits-that-are-not-pushed-anywhere) |411| `kept <id> — <n> unpushed commits on <branch>` | [Background session errors](#worktree-has-commits-that-are-not-pushed-anywhere) |

548| [`CLAUDE_CODE_MAX_RETRIES`](https://code.claude.com/docs/en/env-vars) | 10 | Number of retry attempts. Capped at 15 as of v2.1.186; as of v2.1.199 `CLAUDE_CODE_RETRY_WATCHDOG` raises the default and removes the cap. Lower it to surface failures faster in scripts. |557| [`CLAUDE_CODE_MAX_RETRIES`](https://code.claude.com/docs/en/env-vars) | 10 | Number of retry attempts. Capped at 15 as of v2.1.186; as of v2.1.199 `CLAUDE_CODE_RETRY_WATCHDOG` raises the default and removes the cap. Lower it to surface failures faster in scripts. |

549| [`CLAUDE_CODE_RETRY_WATCHDOG`](https://code.claude.com/docs/en/env-vars) | unset | Set to `1` in unattended sessions such as CI jobs to retry `429` and `529` capacity errors indefinitely instead of failing after `CLAUDE_CODE_MAX_RETRIES` attempts. Claude Code fails at once when a standard-speed request gets a `429` that reports a spend limit or exhausted usage credits, even one from a [gateway spend cap](#spend-limit-reached) that resets on a schedule. Before v2.1.239, the watchdog retried these indefinitely. For fast mode requests, see [Handle rate limits](https://code.claude.com/docs/en/fast-mode.md#handle-rate-limits). On v2.1.199 or later it also raises the default retry count for other transient errors, such as server errors, timeouts, and dropped connections, to 300, roughly three hours of backoff, and removes the cap of 15 on `CLAUDE_CODE_MAX_RETRIES` if you set that variable explicitly. |558| [`CLAUDE_CODE_RETRY_WATCHDOG`](https://code.claude.com/docs/en/env-vars) | unset | Set to `1` in unattended sessions such as CI jobs to retry `429` and `529` capacity errors indefinitely instead of failing after `CLAUDE_CODE_MAX_RETRIES` attempts. Claude Code fails at once when a standard-speed request gets a `429` that reports a spend limit or exhausted usage credits, even one from a [gateway spend cap](#spend-limit-reached) that resets on a schedule. Before v2.1.239, the watchdog retried these indefinitely. For fast mode requests, see [Handle rate limits](https://code.claude.com/docs/en/fast-mode.md#handle-rate-limits). On v2.1.199 or later it also raises the default retry count for other transient errors, such as server errors, timeouts, and dropped connections, to 300, roughly three hours of backoff, and removes the cap of 15 on `CLAUDE_CODE_MAX_RETRIES` if you set that variable explicitly. |

550| [`CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS`](https://code.claude.com/docs/en/env-vars) | unset | Maximum time in milliseconds that each API request spends waiting out `429` and `529` errors when `CLAUDE_CODE_RETRY_WATCHDOG` is set. When unset, the wait has no limit. Requires Claude Code v2.1.295 or later. |559| [`CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS`](https://code.claude.com/docs/en/env-vars) | unset | Maximum time in milliseconds that each API request spends waiting out `429` and `529` errors when `CLAUDE_CODE_RETRY_WATCHDOG` is set. When unset, the wait has no limit. Requires Claude Code v2.1.295 or later. |

560| `CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS` | no cap | With `CLAUDE_CODE_RETRY_WATCHDOG` set, the longest time in milliseconds one request waits for your plan's [usage limit](#youve-hit-your-session-limit), such as the session or weekly limit, to reset. When the reset is further away than this cap, the request fails at once, unless usage credits have room or the API couldn't check them. In those cases it's retried, and fails if the cap passes before it succeeds. Requires Claude Code v2.1.301 or later. |

551| [`CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS`](https://code.claude.com/docs/en/env-vars) | unset | Minimum interval in milliseconds between checks of whether a [usage limit](#youve-hit-your-session-limit) was already lifted, while a request waits for that limit to reset with `CLAUDE_CODE_RETRY_WATCHDOG` set. When a check finds the limit lifted, the request goes out at once. Give plain digits from `60000` to `10800000`. When unset or outside that range, no checks are made. For when Claude Code skips these checks, see the [environment variables reference](https://code.claude.com/docs/en/env-vars.md). Requires Claude Code v2.1.305 or later. |561| [`CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS`](https://code.claude.com/docs/en/env-vars) | unset | Minimum interval in milliseconds between checks of whether a [usage limit](#youve-hit-your-session-limit) was already lifted, while a request waits for that limit to reset with `CLAUDE_CODE_RETRY_WATCHDOG` set. When a check finds the limit lifted, the request goes out at once. Give plain digits from `60000` to `10800000`. When unset or outside that range, no checks are made. For when Claude Code skips these checks, see the [environment variables reference](https://code.claude.com/docs/en/env-vars.md). Requires Claude Code v2.1.305 or later. |

552| [`CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS`](https://code.claude.com/docs/en/env-vars) | 500 | Starting delay in milliseconds of the backoff between retries of a request that the API rejects with a `529` overloaded error. Raise it, up to 32000, to spread the retries over a longer window when the API is at capacity. Has no effect when `CLAUDE_CODE_RETRY_WATCHDOG` is set to `1`, or when the rejected request was sent in [fast mode](https://code.claude.com/docs/en/fast-mode.md#handle-rate-limits). Requires Claude Code v2.1.292 or later. |562| [`CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS`](https://code.claude.com/docs/en/env-vars) | 500 | Starting delay in milliseconds of the backoff between retries of a request that the API rejects with a `529` overloaded error. Raise it, up to 32000, to spread the retries over a longer window when the API is at capacity. Has no effect when `CLAUDE_CODE_RETRY_WATCHDOG` is set to `1`, or when the rejected request was sent in [fast mode](https://code.claude.com/docs/en/fast-mode.md#handle-rate-limits). Requires Claude Code v2.1.292 or later. |

553| [`CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS`](https://code.claude.com/docs/en/env-vars) | 32000 | Ceiling in milliseconds on the backoff between retries of a request that the API rejects with a `529` overloaded error. Raise it, up to 64000, so that later retries keep spreading apart when the API is at capacity. Has no effect when `CLAUDE_CODE_RETRY_WATCHDOG` is set to `1`, or when the rejected request was sent in [fast mode](https://code.claude.com/docs/en/fast-mode.md#handle-rate-limits). Requires Claude Code v2.1.296 or later. |563| [`CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS`](https://code.claude.com/docs/en/env-vars) | 32000 | Ceiling in milliseconds on the backoff between retries of a request that the API rejects with a `529` overloaded error. Raise it, up to 64000, so that later retries keep spreading apart when the API is at capacity. Has no effect when `CLAUDE_CODE_RETRY_WATCHDOG` is set to `1`, or when the rejected request was sent in [fast mode](https://code.claude.com/docs/en/fast-mode.md#handle-rate-limits). Requires Claude Code v2.1.296 or later. |

554| [`API_TIMEOUT_MS`](https://code.claude.com/docs/en/env-vars) | 600000 | Time in milliseconds that each request attempt has to receive its response headers. It doesn't limit how long a streaming response runs after that. Raise it for slow networks or proxies. For how it caps the first-byte deadline, see [No response from API](#no-response-from-api). |564| [`API_TIMEOUT_MS`](https://code.claude.com/docs/en/env-vars) | 600000 | Time in milliseconds that each request attempt has to receive its response headers. It doesn't limit how long a streaming response runs after that. Raise it for slow networks or proxies. For how it caps the first-byte deadline, see [No response from API](#no-response-from-api). |

555| [`CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES`](https://code.claude.com/docs/en/env-vars) | unset | Limit on re-sends of a [non-streaming request](#streaming-response-ended-before-any-complete-data-was-received) that times out. At the limit, the request fails. A response from Claude that takes longer than the timeout to generate times out again on every re-send, so set a low number such as `0` to fail sooner. Each non-streaming attempt times out after 300 seconds in a local session, or after `API_TIMEOUT_MS` when you set a positive value. Requires Claude Code v2.1.285 or later. |565| [`CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES`](https://code.claude.com/docs/en/env-vars) | unset | Limit on re-sends of a [non-streaming request](#streaming-response-ended-before-any-complete-data-was-received) that times out. At the limit, the request fails. A response from Claude that takes longer than the timeout to generate times out again on every re-send, so set a low number such as `0` to fail sooner. For each attempt's timeout, see [How long a non-streaming attempt waits](#how-long-a-non-streaming-attempt-waits). Requires Claude Code v2.1.285 or later. |

556| [`CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`](https://code.claude.com/docs/en/env-vars) | unset | Deadline in milliseconds for the first response byte of a streaming request. Requires Claude Code v2.1.242 or later. For how Claude Code picks the deadline when this is unset, see [No response from API](#no-response-from-api). |566| [`CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`](https://code.claude.com/docs/en/env-vars) | unset | Deadline in milliseconds for the first response byte of a streaming request. Requires Claude Code v2.1.242 or later. For how Claude Code picks the deadline when this is unset, see [No response from API](#no-response-from-api). |

557 567

568#### How long a non-streaming attempt waits

569

570A non-streaming attempt ends at its request timeout or at the body idle timeout, whichever comes first:

571

572* **Request timeout**: `API_TIMEOUT_MS` when you set a positive value, otherwise 300 seconds in a local session.

573* **[Body idle timeout](https://code.claude.com/docs/en/network-config.md#streaming-idle-watchdogs)**: 5 to 6 minutes without a response, however high you set `API_TIMEOUT_MS`, where it runs and you haven't turned it off.

574

558## Server errors575## Server errors

559 576

560Most of these errors come from the inference provider: Anthropic's service on the Anthropic API, and the service behind that provider's endpoint on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or a custom gateway. [Auto mode cannot determine the safety of an action](#auto-mode-cannot-determine-the-safety-of-an-action) and [Agent terminated early due to an API error](#agent-terminated-early-due-to-an-api-error) also cover causes on your side, such as an Amazon Bedrock account that can't invoke the classifier model or a subagent that hit a usage limit.577Most of these errors come from the inference provider: Anthropic's service on the Anthropic API, and the service behind that provider's endpoint on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or a custom gateway. [Auto mode cannot determine the safety of an action](#auto-mode-cannot-determine-the-safety-of-an-action) and [Agent terminated early due to an API error](#agent-terminated-early-due-to-an-api-error) also cover causes on your side, such as an Amazon Bedrock account that can't invoke the classifier model or a subagent that hit a usage limit.

1436 1453

1437This is not the same state as [OAuth token revoked or expired](#oauth-token-revoked-or-expired). Those messages report a rejection the API returned. Claude Code itself produces `Login expired` for a login it already failed to renew, so it sends no request. When the renewal fails because the account itself is suspended rather than the login being stale, Claude Code shows [Your account is on hold](#your-account-is-on-hold) instead.1454This is not the same state as [OAuth token revoked or expired](#oauth-token-revoked-or-expired). Those messages report a rejection the API returned. Claude Code itself produces `Login expired` for a login it already failed to renew, so it sends no request. When the renewal fails because the account itself is suspended rather than the login being stale, Claude Code shows [Your account is on hold](#your-account-is-on-hold) instead.

1438 1455

1439Sessions authenticated with an API key, [`CLAUDE_CODE_OAUTH_TOKEN`](https://code.claude.com/docs/en/env-vars), or a third-party provider don't use the saved login and never see this message.

~~1440~~

1441You can check for this state before a request fails: [`/status`](https://code.claude.com/docs/en/commands) shows a `Login` row reading `Expired — log in again`, plus the organization and email it has saved for the expired login. The row appears only when the saved login is your active credential and can no longer be refreshed. Sessions authenticated another way don't show the row, even if an expired login remains saved. Before v2.1.210, `/status` gave no indication in this state that a login had ever existed, because the cleared credential left it nothing to report.1456You can check for this state before a request fails: [`/status`](https://code.claude.com/docs/en/commands) shows a `Login` row reading `Expired — log in again`, plus the organization and email it has saved for the expired login. The row appears only when the saved login is your active credential and can no longer be refreshed. Sessions authenticated another way don't show the row, even if an expired login remains saved. Before v2.1.210, `/status` gave no indication in this state that a login had ever existed, because the cleared credential left it nothing to report.

1442 1457

1443**What to do:**1458**What to do:**

1461Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh. This is usually transient; retry in a minute, and if it persists close other Claude Code processes or sign in again1476Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh. This is usually transient; retry in a minute, and if it persists close other Claude Code processes or sign in again

1462```1477```

1463 1478

1464Sessions authenticated with an API key, [`CLAUDE_CODE_OAUTH_TOKEN`](https://code.claude.com/docs/en/env-vars), or a third-party provider don't use the saved login and never see this message.

~~1465~~

1466**What to do:**1479**What to do:**

1467 1480

1468* Try again in a minute. If another process completes the refresh first, this session uses the renewed login.1481* Try again in a minute. If another process completes the refresh first, this session uses the renewed login.

1469* If the message keeps returning, close other Claude Code windows and processes, then retry.1482* If the message keeps returning, close other Claude Code windows and processes, then retry.

1470* If it returns with no other Claude Code process running, run `/login`. Signing in again doesn't wait on the refresh lock.1483* If it returns with no other Claude Code process running, run `/login`. Signing in again doesn't wait on the refresh lock.

1471 1484

1485### Could not refresh your login: the disk that holds the Claude Code config directory is full

1486

1487Free space on the disk that holds the Claude Code config directory, then send your message again. Signing in wouldn't help while the disk is full, because a new login couldn't be saved. The config directory is `~/.claude` in your home directory unless you set [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/en/env-vars).

1488

1489```text wrap theme={null}

1490Could not refresh your login: the disk that holds the Claude Code config directory (~/.claude by default), or your disk quota on it, is full · Delete files you no longer need on that disk, then try again · Signing in again won't help

1491```

1492

1493In [non-interactive mode](https://code.claude.com/docs/en/headless.md) (`-p`) and the [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md), the message reads:

1494

1495```text wrap theme={null}

1496Failed to refresh OAuth token: the disk that holds the Claude Code config directory (~/.claude by default), or your disk quota on it, is full. Delete files you no longer need on that disk and retry; signing in again won't help

1497```

1498

1499**What to do:**

1500

1501* For a script, rerun its `claude -p` command

1502* If the disk already shows free space, running out of disk quota or of inodes produces the same message. Delete your own files on that disk. If the message returns, delete many small files rather than a few large ones, because each file takes one inode whatever its size.

1503

1472### Couldn't save your login1504### Couldn't save your login

1473 1505

1474You signed in with claude.ai, but Claude Code couldn't save the login to its credential store, so the login didn't complete. On macOS this can happen when the login keychain locks, for example on sleep or idle, after Claude Code has already read or saved credentials in it during the same session.1506You signed in with claude.ai, but Claude Code couldn't save the login to its credential store, so the login didn't complete. On macOS this can happen when the login keychain locks, for example on sleep or idle, after Claude Code has already read or saved credentials in it during the same session.

2187This error is not a client-side network problem. Cloud sessions and [cloud scheduled tasks](https://code.claude.com/docs/en/routines.md) run inside a sandboxed VM whose outbound traffic through the session's network is filtered to the [cloud environment's](https://code.claude.com/docs/en/cloud-environments.md) allowlist:2219This error is not a client-side network problem. Cloud sessions and [cloud scheduled tasks](https://code.claude.com/docs/en/routines.md) run inside a sandboxed VM whose outbound traffic through the session's network is filtered to the [cloud environment's](https://code.claude.com/docs/en/cloud-environments.md) allowlist:

2188 2220

2189* **GitHub and connector traffic**: [GitHub operations](https://code.claude.com/docs/en/cloud-environments.md#github-proxy) and MCP connector traffic use separate channels, which is why they can keep working while other hosts are blocked2221* **GitHub and connector traffic**: [GitHub operations](https://code.claude.com/docs/en/cloud-environments.md#github-proxy) and MCP connector traffic use separate channels, which is why they can keep working while other hosts are blocked

2190* **Default environment**: the **Default** environment uses **Trusted** access, which permits the [default allowlist](https://code.claude.com/docs/en/cloud-environments.md#default-allowed-domains) of package registries, cloud provider APIs, container registries, and common development domains and blocks other domains on that path2222* **Default environment**: the **Default** environment uses **Limited** access with **Allow package managers** checked. Its sessions reach the [default allowlist](https://code.claude.com/docs/en/cloud-environments.md#default-allowed-domains) of package registries, cloud provider APIs, container registries, and common development domains.

2191 2223

2192**What to do:**2224**What to do:**

2193 2225

2194These steps change one of your own environments. An [organization-shared environment](https://code.claude.com/docs/en/cloud-environments.md#organization-shared-environments) opens read-only in the selector, so ask an Owner to change its network access from the **Cloud environments** page in [admin settings](https://claude.ai/admin-settings).2226These steps change one of your own environments. An [organization-shared environment](https://code.claude.com/docs/en/cloud-environments.md#organization-shared-environments) opens read-only in the selector, so ask an Owner to change its network access from the **Cloud environments** page in [admin settings](https://claude.ai/admin-settings).

2195 2227

2196* Open your environment for editing, either from the [cloud scheduled task's form](https://code.claude.com/docs/en/routines.md#environments-and-network-access) or from the [environment selector](https://code.claude.com/docs/en/cloud-environments.md#configure-your-environment) where you start cloud sessions.2228* Open your environment for editing, either from the [cloud scheduled task's form](https://code.claude.com/docs/en/routines.md#environments-and-network-access) or from the [environment selector](https://code.claude.com/docs/en/cloud-environments.md#configure-your-environment) where you start cloud sessions.

2197* In the **Edit cloud environment** dialog, change **Network access** from **Trusted** to **Custom**, then add the blocked domain to **Allowed domains**. Enter one domain per line. Check **Also include default list of common package managers** to keep the [default allowlist](https://code.claude.com/docs/en/cloud-environments.md#default-allowed-domains) alongside your custom domains. Select **Full** instead if you want unrestricted access.2229* In the **Edit cloud environment** dialog, select **Limited** under **Network access**, then add the blocked domain to **Allowed domains**. Enter one domain per line. Check **Allow package managers** to allow the [default allowlist](https://code.claude.com/docs/en/cloud-environments.md#default-allowed-domains) alongside your own domains. Select **Full** instead if you want unrestricted access.

2198* Click **Save changes**. The next run uses the updated allowlist. For a cloud session that's already open, see [when a network access change reaches existing sessions](https://code.claude.com/docs/en/cloud-environments.md#network-access).2230* Click **Save changes**. The next run uses the updated allowlist. For a cloud session that's already open, see [when a network access change reaches existing sessions](https://code.claude.com/docs/en/cloud-environments.md#network-access).

2199 2231

2200See [Network access](https://code.claude.com/docs/en/cloud-environments.md#network-access) for access levels and the default allowlist. Local CLI sessions are not affected by this policy.2232See [Network access](https://code.claude.com/docs/en/cloud-environments.md#network-access) for access levels and the default allowlist. Local CLI sessions are not affected by this policy.

2442 2474

2443### Context exceeds the token limit2475### Context exceeds the token limit

2444 2476

2445`/context` shows this warning at the top of its output when the conversation has grown past the model's context window. Requests fail with [`Prompt is too long`](#prompt-is-too-long) until you free space. An interactive session shows that error as the `Context limit reached` line.2477`/context` shows this warning at the top of its output when the conversation has grown past the model's context window:

2446 2478

2447```text theme={null}2479```text theme={null}

2448Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.2480Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.

2449```2481```

2450 2482

2483After a `Context exceeds` warning, you don't need to run either command while [auto-compact](https://code.claude.com/docs/en/settings-reference.md#autocompactenabled) is on, which is the default:

2484

2485* **Auto-compact on**: send your next message. If it still fails with [`Prompt is too long`](#prompt-is-too-long), see that entry.

2486* **Auto-compact off**: in the session, run `/compact` if the warning names it, or `/clear` to start over. Until you run one, messages fail with `Context limit reached`, or `Prompt is too long` in `-p` output.

2487

2451When the limit you exceeded is a compaction window, such as the 200K boundary on 1M-context models, the warning reads differently. A compaction window can sit below the model's context window, so requests past it can still succeed.2488When the limit you exceeded is a compaction window, such as the 200K boundary on 1M-context models, the warning reads differently. A compaction window can sit below the model's context window, so requests past it can still succeed.

2452 2489

2453```text theme={null}2490```text theme={null}

2458 2495

2459**What to do:**2496**What to do:**

2460 2497

2461* In a multi-turn conversation, run `/compact` to summarize earlier turns and free space. To start fresh instead, run `/clear`2498* **After a compaction-window warning**: in a multi-turn conversation, run `/compact` to summarize earlier turns and free space. To start fresh instead, run `/clear`.

2462* For more ways to reduce usage, see [Prompt is too long](#prompt-is-too-long)2499* For more ways to reduce usage, see [Prompt is too long](#prompt-is-too-long)

2463 2500

2464Before v2.1.216, `/context` showed usage above 100% with no warning line explaining what that meant or how to recover.2501Before v2.1.216, `/context` showed usage above 100% with no warning line explaining what that meant or how to recover.

3302 3339

3303### Configuration error in \~/.claude.json3340### Configuration error in \~/.claude.json

3304 3341

3305Claude Code couldn't parse `~/.claude.json`, the file that holds your account details, MCP servers, and per-project state. Your file is unchanged. A [non-interactive](https://code.claude.com/docs/en/headless.md) start such as `claude -p` exits with code 1 each time until you repair the file.3342Claude Code couldn't parse `~/.claude.json`, the file that holds your account details, MCP servers, and per-project state. A [non-interactive](https://code.claude.com/docs/en/headless.md) start such as `claude -p` exits with code 1.

3306 3343

3307When Claude Code finds a [backup](https://code.claude.com/docs/en/claude-directory.md#cleaned-up-automatically), the output names it and prints a `cp` line that copies it back:3344When Claude Code finds a [backup](https://code.claude.com/docs/en/claude-directory.md#cleaned-up-automatically), the output names it and prints a `cp` line that copies it back:

3308 3345

3317 3354

3318**What to do:**3355**What to do:**

3319 3356

3320* **The output has a `cp` line**: run that line in your terminal. On Windows, run it in PowerShell. It replaces the broken file with the backup, an earlier version of `~/.claude.json`.3357* **The output has a `cp` line**: run that line in your terminal. On Windows, run it in PowerShell.

3321* **The output has no `cp` line, or the error returns after you run it**: fix the JSON in `~/.claude.json`, copy another `.claude.json.backup.<timestamp>` file from [`~/.claude/backups/`](https://code.claude.com/docs/en/claude-directory#cleaned-up-automatically) over it if there is one, or rename it. With no file at `~/.claude.json`, Claude Code starts with default settings and none of what the file held.3358* **The output has no `cp` line, or the error returns after you run it**: if `~/.claude.json` still has your configuration, fix its JSON. If you can't, copy another `.claude.json.backup.<timestamp>` file from [`~/.claude/backups/`](https://code.claude.com/docs/en/claude-directory#cleaned-up-automatically) over it if there is one, or rename it. With no file at `~/.claude.json`, Claude Code starts with default settings and none of what the file held.

~~3322~~ 3359* **`~/.claude.json` no longer has your configuration**: find a `.claude.json.corrupted.<timestamp>` file that still has it, in [`~/.claude/backups/`](https://code.claude.com/docs/en/claude-directory#cleaned-up-automatically) or your home directory. Fix its JSON, then copy it over `~/.claude.json`. If you can't find or fix one, try the same steps with a `.claude.json.backup.<timestamp>` file that has your configuration. If none does, rename `~/.claude.json` and add your MCP servers again with [`claude mcp add`](https://code.claude.com/docs/en/mcp#installing-mcp-servers).

3323Before v2.1.318, you were left with defaults in `~/.claude.json` after a non-interactive start printed this error, so the next start ran without your configuration.

3324 3360

3325### Claude configuration file was empty and no backup holds anything3361### Claude configuration file was empty and no backup holds anything

3326 3362

3381 3417

3382Before v2.1.309, Claude Code printed only the operating system's error text when the volume was full or your quota was used up. An example is `ENOSPC: no space left on device, mkdir '/tmp/claude-501'`, and the same steps apply.3418Before v2.1.309, Claude Code printed only the operating system's error text when the volume was full or your quota was used up. An example is `ENOSPC: no space left on device, mkdir '/tmp/claude-501'`, and the same steps apply.

3383 3419

3420### Claude Code could not save because the disk is full

3421

3422This line on stderr after a [`claude -p`](https://code.claude.com/docs/en/headless) run means the disk is full or your disk quota is used up, so Claude Code couldn't save everything from the run:

3423

3424```text wrap theme={null}

3425Error: Claude Code could not save all of this session's transcript under /Users/you/.claude because the disk is full (ENOSPC). If you resume this session, part of the conversation may be missing. Free up space on that disk before the next run.

3426```

3427

3428With text or `json` output, the run exits with code 1, and the answer has already been printed. With `stream-json` output, the run keeps its usual exit code, and the answer still arrives.

3429

3430**What to do:**

3431

3432* **`the disk is full (ENOSPC)`**: before your next run, free up space on the disk that holds the path in the message

3433* **`your disk quota is used up (EDQUOT)`**: before your next run, free up space or ask for a larger quota

3434

3384### Directory couldn't be resolved to a real location3435### Directory couldn't be resolved to a real location

3385 3436

3386You ran `/add-dir` for a subdirectory of your working directory, and Claude Code couldn't resolve the directory to its real location.3437You ran `/add-dir` for a subdirectory of your working directory, and Claude Code couldn't resolve the directory to its real location.

3452 3503

3453Before v2.1.309, `claude ultrareview` didn't accept `--trust-workspace`.3504Before v2.1.309, `claude ultrareview` didn't accept `--trust-workspace`.

3454 3505

3506### Remote Control did not start because a question got no answer

3507

3508This message means [`claude remote-control`](https://code.claude.com/docs/en/remote-control) asked the first-run question quoted in the message and got no answer:

3509

3510```text theme={null}

3511Remote Control did not start: "Enable Remote Control?" got no answer. Run `claude remote-control` at a terminal and answer y once; it won't ask again.

3512Remote Control did not start: "Choose [1/2] (default: 1):" got no answer. You can run `claude remote-control` and choose, or pass --spawn=same-dir or --spawn=worktree.

3513```

3514

3515**What to do:**

3516

3517* **`Enable Remote Control?`**: in a script or a service, standard input ends before anyone can answer. Run `claude remote-control` once in a terminal, as the user your script or service runs as, and answer `y`.

3518* **`Choose [1/2] (default: 1):`**: run `claude remote-control` again and [choose a spawn mode](https://code.claude.com/docs/en/remote-control.md#set-the-default-spawn-mode-for-a-project), or pass [`--spawn=same-dir` or `--spawn=worktree`](https://code.claude.com/docs/en/remote-control#start-a-remote-control-session) to skip the question

3519

3455### Not carried over to the sessions Remote Control starts3520### Not carried over to the sessions Remote Control starts

3456 3521

3457You started [Remote Control](https://code.claude.com/docs/en/remote-control.md) with a global `claude` flag before the `remote-control` verb, one that would restrict or configure the sessions Remote Control starts, such as `--settings`, `--setting-sources`, `--permission-mode`, `--disallowed-tools`, or `--mcp-config`. A flag placed before the verb never reaches those sessions. Claude Code refuses to start instead, naming the flag:3522You started [Remote Control](https://code.claude.com/docs/en/remote-control.md) with a global `claude` flag before the `remote-control` verb, one that would restrict or configure the sessions Remote Control starts, such as `--settings`, `--setting-sources`, `--permission-mode`, `--disallowed-tools`, or `--mcp-config`. A flag placed before the verb never reaches those sessions. Claude Code refuses to start instead, naming the flag:

3499 3564

3500* You haven't started a session since installing, so Claude Code hasn't fetched the flag yet. The first `claude import` can print this even when the feature is available to you.3565* You haven't started a session since installing, so Claude Code hasn't fetched the flag yet. The first `claude import` can print this even when the feature is available to you.

3501* You use Claude Code through Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or Claude Platform on AWS, or through a [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway#availability-and-limitations). Claude Code doesn't fetch feature flags in these sessions, so `claude import` stays unavailable.3566* You use Claude Code through Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or Claude Platform on AWS, or through a [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway#availability-and-limitations). Claude Code doesn't fetch feature flags in these sessions, so `claude import` stays unavailable.

3502* You set `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `DISABLE_GROWTHBOOK`, or [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/en/env-vars), which turn off feature-flag fetching, so `claude import` stays unavailable.3567* You set `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, [`CLAUDE_CODE_DISABLE_FEATURE_FLAGS`](https://code.claude.com/docs/en/env-vars#variables), `DISABLE_GROWTHBOOK`, or [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/en/env-vars), which turn off feature-flag fetching, so `claude import` stays unavailable.

3503 3568

3504**What to do:**3569**What to do:**

3505 3570

4457* If the message ends with `EACCES`, restore your execute permission on every directory leading to the file or folder the path names. Check the directories above the path, then follow each symlink you reach and check the directories leading to where it points. For any other error code, look it up in the [causes and steps for a path that couldn't be checked](#path-could-not-be-checked).4522* If the message ends with `EACCES`, restore your execute permission on every directory leading to the file or folder the path names. Check the directories above the path, then follow each symlink you reach and check the directories leading to where it points. For any other error code, look it up in the [causes and steps for a path that couldn't be checked](#path-could-not-be-checked).

4458* To share files with other plugins in the same marketplace, link them with a symlink inside the plugin directory, following the [symlink rules](https://code.claude.com/docs/en/plugins/host-marketplace.md#share-files-within-a-marketplace-with-symlinks)4523* To share files with other plugins in the same marketplace, link them with a symlink inside the plugin directory, following the [symlink rules](https://code.claude.com/docs/en/plugins/host-marketplace.md#share-files-within-a-marketplace-with-symlinks)

4459 4524

4525### Server file path not read

4526

4527The `path not read` message means Claude Code didn't read an MCP or LSP server file that a plugin names, because of the file's path. The rest of the plugin loads, without the servers the file defines.

4528

4529A `..` part counts even when the path stays inside the plugin, as in this example:

4530

4531```text theme={null}

4532mcp-servers path not read: ./sub/../x.json is absolute or has a ".." part

4533```

4534

4535**What to do:**

4536

4537* If you installed the plugin and don't maintain it, report the message to its author

4538* If you maintain the plugin, keep the server file inside the plugin directory. Name it in the manifest or marketplace entry with a path that starts with `./` and has no `..`, for example `./servers/x.json`

4539* To share one server file between plugins in the same marketplace, link the file into each plugin with a symlink, following the [symlink rules](https://code.claude.com/docs/en/plugins/host-marketplace.md#share-files-within-a-marketplace-with-symlinks)

4540

4460### Plugin not loaded: its manifest was not read4541### Plugin not loaded: its manifest was not read

4461 4542

4462Claude Code couldn't confirm that a marketplace plugin's [manifest](https://code.claude.com/docs/en/plugins/manifest-reference.md) at `.claude-plugin/plugin.json` is inside the plugin, so it loads nothing from that plugin. For a plugin in a [local marketplace](https://code.claude.com/docs/en/plugins/loading.md#in-place-and-copied-plugins), Claude Code also couldn't confirm that the manifest is inside that marketplace. The message appears in the `/plugin` **Errors** tab, and the reason at its end says what Claude Code found.4543Claude Code couldn't confirm that a marketplace plugin's [manifest](https://code.claude.com/docs/en/plugins/manifest-reference.md) at `.claude-plugin/plugin.json` is inside the plugin, so it loads nothing from that plugin. For a plugin in a [local marketplace](https://code.claude.com/docs/en/plugins/loading.md#in-place-and-copied-plugins), Claude Code also couldn't confirm that the manifest is inside that marketplace. The message appears in the `/plugin` **Errors** tab, and the reason at its end says what Claude Code found.

5065 5146

5066Before v2.1.280, the `where it leads on disk could not be determined` refusal didn't appear.5147Before v2.1.280, the `where it leads on disk could not be determined` refusal didn't appear.

5067 5148

5149### The search failed, so this is not a "no matches" result

5150

5151A [Grep](https://code.claude.com/docs/en/tools-reference.md#grep-tool-behavior) or [Glob](https://code.claude.com/docs/en/tools-reference.md#glob-tool-behavior) search Claude ran failed before returning any result, so whether matches exist is unknown. The message Claude receives in place of results starts:

5152

5153```text wrap theme={null}

5154The search failed, so this is not a "no matches" result: matches may exist. What happened to the search program (ripgrep) is not known, and no results were read. Run the search once more. If it fails again, tell the user that searches are failing.

5155```

5156

5157**What to do:**

5158

5159* **The first time it appears**: nothing. The message asks Claude to search again first.

5160* **If Claude says searches are failing**: capture ripgrep's error for a bug report:

5161 1. From your shell, start a session with the same flags as the session where searches failed, plus [`--debug-file claude-debug.log`](https://code.claude.com/docs/en/cli-reference#cli-flags)

5162 2. Send Claude the request that led to the failed search

5163 3. If the search fails again, find the line containing `rg error (signal=` in `claude-debug.log`

5164 4. Include that line when you [report the problem](#report-an-error)

5165

5068### Task output swap refused5166### Task output swap refused

5069 5167

5070Claude Code saves each Bash command's output to a file under its temp directory. Every time it opens one of these files, it checks that the path still leads to the file it created, with no symbolic link, extra hard link, or moved directory redirecting it. This message means that check failed, so Claude Code refused the operation rather than write or read output through that path. The message appears in the Bash tool result:5168Claude Code saves each Bash command's output to a file under its temp directory. Every time it opens one of these files, it checks that the path still leads to the file it created, with no symbolic link, extra hard link, or moved directory redirecting it. This message means that check failed, so Claude Code refused the operation rather than write or read output through that path. The message appears in the Bash tool result:

5153 5251

5154Before v2.1.296, Edit and NotebookEdit applied such an edit and saved every byte they couldn't decode as `U+FFFD`. On those versions, update Claude Code.5252Before v2.1.296, Edit and NotebookEdit applied such an edit and saved every byte they couldn't decode as `U+FFFD`. On those versions, update Claude Code.

5155 5253

5254### Refusing to apply edits: a hook is configured for file edits in this session

5255

5256Claude tried to publish an [artifact](https://code.claude.com/docs/en/artifacts.md) with a [one-step update](https://code.claude.com/docs/en/artifacts.md#turn-off-one-step-artifact-updates), a small change to the artifact's file included in the publish, and Claude Code refused. Nothing was published and the file is unchanged. The message appears in the Artifact tool result:

5257

5258```text wrap theme={null}

5259Refusing to apply edits to <path>: a hook is configured for file edits in this session, so a publish can't apply edits here. Edit the file, then publish it without edits. Nothing was published.

5260```

5261

5262Claude Code doesn't allow one-step updates while your session has a [`PreToolUse` hook](https://code.claude.com/docs/en/hooks#pretooluse) or [mod](https://code.claude.com/docs/en/plugins/mods/overview.md) on `Edit` or `Write`.

5263

5264**What to do:**

5265

5266* Nothing, if Claude went on to edit the file and publish it

5267* If Claude stopped at the message, ask Claude to edit the file and publish

5268* If the message keeps coming back, quit and relaunch Claude Code

5269* If the message comes back even after a relaunch, [turn off one-step updates](https://code.claude.com/docs/en/artifacts.md#turn-off-one-step-artifact-updates)

5270

5156### The source file is not valid UTF-8 text5271### The source file is not valid UTF-8 text

5157 5272

5158Claude tried to publish an [artifact](https://code.claude.com/docs/en/artifacts.md) from a file whose bytes don't decode as text, or whose text already contains the replacement character `U+FFFD`, so Claude Code refused the publish before uploading anything. The message appears in the Artifact tool result and names the first position to fix:5273Claude tried to publish an [artifact](https://code.claude.com/docs/en/artifacts.md) from a file whose bytes don't decode as text, or whose text already contains the replacement character `U+FFFD`, so Claude Code refused the publish before uploading anything. The message appears in the Artifact tool result and names the first position to fix:

5623 5738

5624* Recreate the directory the message names, or dispatch from a directory that exists, then try again5739* Recreate the directory the message names, or dispatch from a directory that exists, then try again

5625 5740

5741### This forked session could not be started

5742

5743You [forked a Remote Control session](https://code.claude.com/docs/en/remote-control.md#fork-a-session-from-your-browser) from claude.ai, and Claude Code couldn't finish starting the [background session](https://code.claude.com/docs/en/agent-view.md) that runs the fork on your machine. This notice appears in the forked session's transcript:

5744

5745```text theme={null}

5746This forked session could not be started. Fork the conversation again to retry.

5747```

5748

5749The session you forked keeps running.

5750

5751**What to do:**

5752

5753* Go back to the session you forked and fork it again once the session is idle

5754

5626### Workspace not trusted when dispatching a background session5755### Workspace not trusted when dispatching a background session

5627 5756

5628You started or restarted a [background session](https://code.claude.com/docs/en/agent-view.md) in a directory you haven't [trusted](https://code.claude.com/docs/en/permissions.md#project-allow-rules-and-workspace-trust), and the workspace trust dialog couldn't appear to ask you. Claude Code doesn't start the session:5757You started or restarted a [background session](https://code.claude.com/docs/en/agent-view.md) in a directory you haven't [trusted](https://code.claude.com/docs/en/permissions.md#project-allow-rules-and-workspace-trust), and the workspace trust dialog couldn't appear to ask you. Claude Code doesn't start the session:

fast-mode.md +40 −18

Details

12 12

13Fast mode is a high-speed configuration for supported models, making the model up to 2.5x faster at a higher cost per token. Toggle it on with `/fast` when you need speed for interactive work such as rapid iteration or live debugging, and toggle it off when cost matters more than latency.13Fast mode is a high-speed configuration for supported models, making the model up to 2.5x faster at a higher cost per token. Toggle it on with `/fast` when you need speed for interactive work such as rapid iteration or live debugging, and toggle it off when cost matters more than latency.

14 14

15Fast mode uses the same model with a different API configuration that prioritizes speed over cost efficiency, so quality and capabilities stay the same. Fast mode is supported on Fable 5.2, Opus 5.5, Opus 5, and Opus 4.8. It is not available on Sonnet, Haiku, or other models.15Fast mode uses the same model with a different API configuration that prioritizes speed over cost efficiency, so quality and capabilities stay the same. On the Anthropic API, fast mode is supported on Fable 5.2, Opus 5.5, Opus 5, and Opus 4.8, but not on Sonnet, Haiku, or other models. For the models on Google Cloud's Agent Platform, see [Use fast mode on Agent Platform](#use-fast-mode-on-agent-platform).

16 16

17> [!WARNING]17> [!WARNING]

18>18>

25 25

26What to know:26What to know:

27 27

28* Use `/fast` to toggle on fast mode in the Claude Code CLI. The [VS Code extension](https://code.claude.com/docs/en/vs-code.md) offers a **Toggle fast mode** command when the selected model supports fast mode. Claude Code saves that toggle to your [`fastMode` setting](#toggle-fast-mode).28* Use `/fast` to toggle on fast mode in the Claude Code CLI. The [VS Code extension](https://code.claude.com/docs/en/vs-code.md) offers a **Toggle fast mode** command when the selected model supports fast mode. On the Anthropic API, Claude Code saves that toggle to your [`fastMode` setting](#toggle-fast-mode).

~~29* Fast mode pricing per MTok input/output is \$16/\$80 on Fable 5.2, \$8/\$40 on Opus 5.5, and \$10/\$50 on Opus 5 and Opus 4.8.~~29* Anthropic's fast mode pricing per MTok input/output: \$16/\$80 on Fable 5.2, \$8/\$40 on Opus 5.5, and \$10/\$50 on Opus 5 and Opus 4.8.

30* Available to Claude Code users on subscription plans (Pro/Max/Ultra/Team/Enterprise) and on Claude Console. Team and Enterprise organizations need an Owner to enable it first, and Console organizations need access provisioned first to use it with Opus 5 or Opus 4.8. [Requirements](#requirements) describes both.30* Available to Claude Code users on subscription plans (Pro/Max/Ultra/Team/Enterprise), on Claude Console, and on Google Cloud's Agent Platform [with conditions](#use-fast-mode-on-agent-platform). Team and Enterprise organizations need an Owner to enable it first, and Console organizations need access provisioned first to use it with Opus 5 or Opus 4.8. [Requirements](#requirements) describes both.

31* For Claude Code users on subscription plans (Pro/Max/Ultra/Team/Enterprise), fast mode is available via usage credits only and not included in the subscription rate limits.31* For Claude Code users on subscription plans (Pro/Max/Ultra/Team/Enterprise), fast mode is available via usage credits only and not included in the subscription rate limits.

32 32

33## Toggle fast mode33## Toggle fast mode

34 34

35On Agent Platform, `/fast` and the `fastMode` setting work differently, so follow [Use fast mode on Agent Platform](#use-fast-mode-on-agent-platform) instead.

35In the CLI, toggle fast mode in either of these ways:37In the CLI, toggle fast mode in either of these ways:

36 38

37* Run `/fast`, press Space to toggle on or off, then press Enter to confirm39* Run `/fast`, press Space to toggle on or off, then press Enter to confirm

38* On a model that supports fast mode, set `"fastMode": true` in your [user settings file](https://code.claude.com/docs/en/settings.md). If you set it on any other model, you stay on that model with fast mode off. On Fable 5.2, that setting alone has no effect until you run `/fast` while using Fable 5.2.40* On a model that supports fast mode, set `"fastMode": true` in your [user settings file](https://code.claude.com/docs/en/settings.md). If you set it on any other model, you stay on that model with fast mode off. On Fable 5.2, that setting alone has no effect until you run `/fast` while using Fable 5.2.

39 41

40By default, fast mode you turn on in an interactive session persists across sessions on a supported model. On Fable 5.2, it persists only if you [turned it on while using Fable 5.2](#switch-models-while-fast-mode-is-on). You can configure fast mode to reset each session. See [require per-session opt-in](#require-per-session-opt-in) for details.42By default on the Anthropic API, fast mode you turn on in an interactive session persists across sessions on a supported model. On Fable 5.2, fast mode persists only if you [turned it on while using Fable 5.2](#switch-models-while-fast-mode-is-on). You can configure fast mode to reset each session. See [require per-session opt-in](#require-per-session-opt-in) for details.

41 43

42Outside a [cloud session](#use-fast-mode-in-cloud-sessions), in [non-interactive mode](https://code.claude.com/docs/en/headless.md) with the `-p` flag, `/fast` works only in a session launched with fast mode in its [`--settings`](https://code.claude.com/docs/en/cli-reference#cli-flags) value, for example `claude -p --settings '{"fastMode": true}'`; the toggle then applies to that session only and isn't saved as your default. The `-p` form requires Claude Code v2.1.205 or later. Elsewhere in non-interactive mode, the command reports that fast mode isn't available.44Outside a [cloud session](#use-fast-mode-in-cloud-sessions), in [non-interactive mode](https://code.claude.com/docs/en/headless.md) with the `-p` flag, `/fast` works only in a session launched with fast mode in its [`--settings`](https://code.claude.com/docs/en/cli-reference#cli-flags) value, for example `claude -p --settings '{"fastMode": true}'`; the toggle then applies to that session only and isn't saved as your default. The `-p` form requires Claude Code v2.1.205 or later. Elsewhere in non-interactive mode, the command reports that fast mode isn't available.

43 45

47 49

48When you enable fast mode with `/fast`:50When you enable fast mode with `/fast`:

49 51

~~50* If your current model doesn't support fast mode, Claude Code switches to Opus~~52* On the Anthropic API, if your current model doesn't support fast mode, Claude Code switches to Opus

51* Fast mode on Fable 5.2 requires Claude Code v2.1.321 or later53* Fast mode on Fable 5.2 requires Claude Code v2.1.321 or later

52* You'll see a confirmation message: "Fast mode ON"54* You'll see a confirmation message: "Fast mode ON"

53* A small `↯` icon appears next to the prompt while fast mode is active55* A small `↯` icon appears next to the prompt while fast mode is active

54* Run `/fast` again at any time to check whether fast mode is on or off56* Run `/fast` again at any time to check whether fast mode is on or off

55 57

~~56Opus 5.5 is the fast mode default in Claude Code v2.1.280 and later. Before v2.1.280, fast mode defaulted to Opus 5 from v2.1.219.~~58On the Anthropic API, Opus 5.5 is the fast mode default in Claude Code v2.1.280 and later. Before v2.1.280, fast mode defaulted to Opus 5 from v2.1.219.

57 59

58When you disable fast mode with `/fast` again, you remain on your current model. To switch to a different model, use `/model`.60When you disable fast mode with `/fast` again, you remain on your current model. To switch to a different model, use `/model`.

59 61

63 65

64* **Switch away**: when you switch to a model that doesn't support fast mode, Claude Code turns fast mode off. This includes Opus 4.7; before v2.1.221, fast mode stayed on after a switch to Opus 4.7 and the API rejected the requests.66* **Switch away**: when you switch to a model that doesn't support fast mode, Claude Code turns fast mode off. This includes Opus 4.7; before v2.1.221, fast mode stayed on after a switch to Opus 4.7 and the API rejected the requests.

65* **Switch back**: fast mode comes back on a supported Opus model when your saved preference is on. With [per-session opt-in](#require-per-session-opt-in), run `/fast` instead.67* **Switch back**: fast mode comes back on a supported Opus model when your saved preference is on. With [per-session opt-in](#require-per-session-opt-in), run `/fast` instead.

66* **Switch to Fable 5.2**: fast mode turns off unless you turned it on while using Fable 5.2. To turn it on, run `/fast` on Fable 5.2. Unless you've set [per-session opt-in](#require-per-session-opt-in), that lasts across sessions until you turn it off or turn it on with another model.68* **Switch to Fable 5.2**: fast mode turns off unless you turned it on while using Fable 5.2. To turn it on, run `/fast` on Fable 5.2. Unless you've set [per-session opt-in](#require-per-session-opt-in), that choice lasts across sessions on the Anthropic API until you turn fast mode off or turn it on with another model.

67 69

68Whenever a model switch turns fast mode on or off, Claude Code shows a `Fast mode ON` or `Fast mode OFF` confirmation, and the `↯` icon appears while fast mode is on. This holds whether you switch with `/model`, with [`/config model=<model>`](https://code.claude.com/docs/en/settings), or from a device connected through [Remote Control](https://code.claude.com/docs/en/remote-control.md).70Whenever a model switch turns fast mode on or off, Claude Code shows a `Fast mode ON` or `Fast mode OFF` confirmation, and the `↯` icon appears while fast mode is on. This holds whether you switch with `/model`, with [`/config model=<model>`](https://code.claude.com/docs/en/settings), or from a device connected through [Remote Control](https://code.claude.com/docs/en/remote-control.md).

69 71

70Claude Code resends the session's fast mode status to devices connected through Remote Control after a model switch, a reconnection, or a failed [availability check](#use-fast-mode-behind-proxies-and-llm-gateways).

72### Use fast mode in cloud sessions72### Use fast mode in cloud sessions

73 73

74Fast mode works in [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) when it's available on your account, whether the session runs on Anthropic-managed infrastructure or a [self-hosted runner](https://code.claude.com/docs/en/self-hosted-environments). Requires Claude Code v2.1.271 or later in the session's environment.74Fast mode works in [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) when it's available on your account, whether the session runs on Anthropic-managed infrastructure or a [self-hosted runner](https://code.claude.com/docs/en/self-hosted-environments) on the Anthropic API. Requires Claude Code v2.1.271 or later in the session's environment.

75 75

76Type `/fast on` in the session to turn fast mode on. It stays on for that session only and isn't saved as your default. The [requirements](#requirements) apply in cloud sessions too.76Type `/fast on` in the session to turn fast mode on. It stays on for that session only and isn't saved as your default. The [requirements](#requirements) apply in cloud sessions too.

77 77

79 79

80## Understand the cost tradeoff80## Understand the cost tradeoff

81 81

~~82Fast mode has higher per-token pricing than standard speed:~~82Fast mode has higher per-token pricing than standard speed. These are Anthropic's rates:

83 83

85| - | - | - |85| - | - | - |

129 129

130Fast mode requires all of the following:130Fast mode requires all of the following:

131 131

132* **Anthropic API or subscription only**: fast mode is available through the Anthropic Console API and for Claude subscription plans using usage credits. It is not available on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or Claude Platform on AWS. Console organizations must also have [fast mode access provisioned](#enable-fast-mode-for-your-organization) to use it with Opus 5 or Opus 4.8.132* **Supported provider**: fast mode is available through the Anthropic Console API, for Claude subscription plans using usage credits, and on Google Cloud's Agent Platform [with conditions](#use-fast-mode-on-agent-platform). It is not available on Amazon Bedrock, Microsoft Foundry, or Claude Platform on AWS, where `/fast` reports "Fast mode is not available on this provider". Console organizations must also have [fast mode access provisioned](#enable-fast-mode-for-your-organization) to use it with Opus 5 or Opus 4.8.

133* **Usage credits turned on for subscription plans**: on a Pro, Max, Ultra, Team, or Enterprise plan, your account must have [usage credits](https://code.claude.com/docs/en/costs.md#add-usage-credits-to-your-subscription) turned on, which allows billing beyond your plan's included usage. Until they're on, `/fast` reports "Fast mode requires usage credits". To turn them on, follow the step for your plan:133* **Usage credits turned on for subscription plans**: on a Pro, Max, Ultra, Team, or Enterprise plan, your account must have [usage credits](https://code.claude.com/docs/en/costs.md#add-usage-credits-to-your-subscription) turned on, which allows billing beyond your plan's included usage. Until they're on, `/fast` reports "Fast mode requires usage credits". To turn them on, follow the step for your plan:

134 * On Pro, Max, and Ultra, turn them on in the **Usage credits** section of [**Settings > Usage**](https://claude.ai/settings/usage) on claude.ai, or run `/usage-credits` to open that page.134 * On Pro, Max, and Ultra, turn them on in the **Usage credits** section of [**Settings > Usage**](https://claude.ai/settings/usage) on claude.ai, or run `/usage-credits` to open that page.

135 * On Team and Enterprise, a member with billing access turns them on for the organization at [**Organization settings > Usage**](https://claude.ai/admin-settings/usage), and a member without it runs `/usage-credits` to send the organization's admins a request.135 * On Team and Enterprise, a member with billing access turns them on for the organization at [**Organization settings > Usage**](https://claude.ai/admin-settings/usage), and a member without it runs `/usage-credits` to send the organization's admins a request.

150> * **Fast mode not enabled**: if fast mode hasn't been enabled for your organization, turning fast mode on with `/fast` shows "Fast mode has been disabled by your organization."150> * **Fast mode not enabled**: if fast mode hasn't been enabled for your organization, turning fast mode on with `/fast` shows "Fast mode has been disabled by your organization."

151> * **Fast mode turned off by managed settings**: if your organization deploys [managed settings](https://code.claude.com/docs/en/managed-settings.md) that set [`fastMode: false`](https://code.claude.com/docs/en/settings-reference#fastmode), turning fast mode on with `/fast` shows the same "Fast mode has been disabled by your organization" message.151> * **Fast mode turned off by managed settings**: if your organization deploys [managed settings](https://code.claude.com/docs/en/managed-settings.md) that set [`fastMode: false`](https://code.claude.com/docs/en/settings-reference#fastmode), turning fast mode on with `/fast` shows the same "Fast mode has been disabled by your organization" message.

152> * **Per-session opt-in required**: managed settings that set [`fastModePerSessionOptIn: true`](#require-per-session-opt-in) refuse `/fast on` with the same message everywhere except an interactive terminal session.152> * **Per-session opt-in required**: managed settings that set [`fastModePerSessionOptIn: true`](#require-per-session-opt-in) refuse `/fast on` with the same message everywhere except an interactive terminal session.

153> * **Fast-mode model not allowed**: if your organization's [`availableModels`](https://code.claude.com/docs/en/model-config#restrict-model-selection) allowlist excludes the fast-mode Opus model, turning it on is refused with "is not in your organization's allowed models". In a session already running on an allowed model that supports fast mode, `/fast` instead enables fast mode on your current model without switching models.153> * **Fast-mode model not allowed**: if your organization's [`availableModels`](https://code.claude.com/docs/en/model-config#restrict-model-selection) allowlist excludes the model `/fast` switches to, turning it on is refused with "is not in your organization's allowed models". In a session already running on an allowed model that supports fast mode, `/fast` instead enables fast mode on your current model without switching models.

154 154

155### Enable fast mode for your organization155### Enable fast mode for your organization

156 156

163 163

164Another option to disable fast mode entirely is to set `CLAUDE_CODE_DISABLE_FAST_MODE=1`. See [Environment variables](https://code.claude.com/docs/en/env-vars.md).164Another option to disable fast mode entirely is to set `CLAUDE_CODE_DISABLE_FAST_MODE=1`. See [Environment variables](https://code.claude.com/docs/en/env-vars.md).

165 165

166### Use fast mode on Agent Platform

167

168On [Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md), you can turn fast mode on for Fable 5.2, with `/fast` in an interactive session or with launch flags in [non-interactive mode](https://code.claude.com/docs/en/headless.md). Requires Claude Code v2.1.322 or later.

169

170Fast mode needs the [region](https://code.claude.com/docs/en/google-vertex-ai.md#region-configuration) for Fable 5.2 to be `global`, `us`, or `eu`. In another region, `/fast` reports `Fast mode needs Vertex region global, us or eu`, and `claude -p` runs at standard speed. Set the region in your shell before you start Claude Code, for example to `global`:

171

172```bash theme={null}

173export VERTEX_REGION_CLAUDE_FABLE_5_2=global

174```

175

176Then turn fast mode on:

177

178* **In an interactive session**: run `/fast`. It switches you to Fable 5.2 from an Opus model or another model without fast mode on Agent Platform. Fast mode isn't saved as your default.

179* **In non-interactive mode**: pass Fable 5.2 as [`--model`](https://code.claude.com/docs/en/cli-reference#cli-flags) and fast mode in [`--settings`](https://code.claude.com/docs/en/cli-reference#cli-flags), for example `claude -p "Summarize this project" --model claude-fable-5-2 --settings '{"fastMode": true}'`

180

181On Agent Platform, `"fastMode": true` in your user, project, local, or managed settings has no effect.

182

183If Agent Platform refuses fast mode, Claude Code falls back to standard speed. An interactive session then shows one of these terminal messages:

184

185* `Using standard speed on Fable 5.2 · fast mode wasn't available`: run `/fast on` to try fast mode again

186* `Fast mode was refused for this project · trying again in 30m`: Agent Platform answered a fast mode request with a 403 or 404 error. To try sooner, run `/fast on`.

187

166### Use fast mode behind proxies and LLM gateways188### Use fast mode behind proxies and LLM gateways

167 189

168Before offering fast mode, Claude Code checks your organization's fast mode availability with a request directly to `api.anthropic.com`. The check doesn't follow [`ANTHROPIC_BASE_URL`](https://code.claude.com/docs/en/llm-gateway-connect#set-the-base-url-and-credential), so on a network that routes Claude traffic through an [LLM gateway](https://code.claude.com/docs/en/llm-gateway) and blocks direct egress to `api.anthropic.com`, the check fails even though inference requests work. The check does use a configured [HTTP proxy](https://code.claude.com/docs/en/network-config.md#proxy-configuration), so a network block fails the check only where `api.anthropic.com` is unreachable even through the proxy.190Before offering fast mode on the Anthropic API, Claude Code checks your organization's fast mode availability with a request directly to `api.anthropic.com`. The check doesn't follow [`ANTHROPIC_BASE_URL`](https://code.claude.com/docs/en/llm-gateway-connect#set-the-base-url-and-credential), so on a network that routes Claude traffic through an [LLM gateway](https://code.claude.com/docs/en/llm-gateway) and blocks direct egress to `api.anthropic.com`, the check fails even though inference requests work.

169 191

170If your organization has fast mode enabled and `/fast` says otherwise, find the message it shows among these cases.192The check does use a configured [HTTP proxy](https://code.claude.com/docs/en/network-config.md#proxy-configuration), so a network block fails the check only where `api.anthropic.com` is unreachable even through the proxy. If your organization has fast mode enabled and `/fast` says otherwise, find the message it shows among these cases.

171 193

172#### Fast mode unavailable due to network connectivity issues194#### Fast mode unavailable due to network connectivity issues

173 195

199 221

200### Require per-session opt-in222### Require per-session opt-in

201 223

202By default, fast mode a user turns on in an interactive session persists across sessions on a supported model. On Fable 5.2, it persists only if the user [turned it on while using Fable 5.2](#switch-models-while-fast-mode-is-on).224By default on the Anthropic API, fast mode a user turns on in an interactive session persists across sessions on a supported model. On Fable 5.2, fast mode persists only if the user [turned it on while using Fable 5.2](#switch-models-while-fast-mode-is-on).

203 225

204To make every session start with fast mode off, set `fastModePerSessionOptIn` to `true` in any [settings file](https://code.claude.com/docs/en/settings.md#where-settings-live). Users then enable it with `/fast` in each session. Owners on [Team](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_teams#team-&-enterprise) or [Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_enterprise) plans can deploy it organization-wide through [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md).226To make every session start with fast mode off, set `fastModePerSessionOptIn` to `true` in any [settings file](https://code.claude.com/docs/en/settings.md#where-settings-live). Users then enable it with `/fast` in each session. Owners on [Team](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_teams#team-&-enterprise) or [Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_enterprise) plans can deploy it organization-wide through [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md).

205 227

227If you run out of usage credits mid-session, Claude Code retries each rejected fast mode request at standard speed and pricing, so you keep working, and there is no cooldown. How you see the rejection depends on the session type:249If you run out of usage credits mid-session, Claude Code retries each rejected fast mode request at standard speed and pricing, so you keep working, and there is no cooldown. How you see the rejection depends on the session type:

228 250

229* In an interactive session, Claude Code shows a "Fast mode disabled · Out of usage credits" notification and turns fast mode off. Your saved fast mode preference doesn't change; run `/fast` to turn fast mode back on.251* In an interactive session, Claude Code shows a "Fast mode disabled · Out of usage credits" notification and turns fast mode off. Your saved fast mode preference doesn't change; run `/fast` to turn fast mode back on.

230* In [non-interactive mode](https://code.claude.com/docs/en/headless.md) with `--output-format stream-json`, and through the Agent SDK, Claude Code emits the same text on the message stream as a `system` message with subtype `notification`, once per turn while you're out of usage credits. Fast mode stays on. Requires Claude Code v2.1.221 or later.252* In [non-interactive mode](https://code.claude.com/docs/en/headless.md) with `--output-format stream-json`, and through the Agent SDK, Claude Code emits the same text on the message stream as a `system` message with subtype `notification`. The message arrives once per turn while you're out of usage credits. Fast mode stays on.

231 253

232## Research preview254## Research preview

233 255

feature-availability.md +7 −6

Details

93 <td>✓ (Opus 5 and 4.8 need provisioning)</td>93 <td>✓ (Opus 5 and 4.8 need provisioning)</td>

94 <td>✗</td>94 <td>✗</td>

95 <td>✗</td>95 <td>✗</td>

~~96 <td>✗</td>~~96 <td>✓ ([Fable 5.2, with conditions](https://code.claude.com/docs/en/fast-mode.md#use-fast-mode-on-agent-platform))</td>

97 <td>✗</td>97 <td>✗</td>

98 </tr>98 </tr>

99 99

112 <td>✓</td>112 <td>✓</td>

113 <td>✓</td>113 <td>✓</td>

114 <td>✗</td>114 <td>✗</td>

115 <td>✗</td>115 <td>✓ (Claude Code v2.1.300 or later)</td>

116 <td>✗</td>116 <td>✗</td>

117 <td>✗</td>117 <td>✗</td>

118 </tr>118 </tr>

221 221

222> [!NOTE]222> [!NOTE]

223>223>

224> If you authenticate through an [LLM gateway](https://code.claude.com/docs/en/llm-gateway), feature availability matches the underlying provider the gateway forwards to, except for the features Claude Code itself turns off. Whenever `ANTHROPIC_BASE_URL` points at a host other than `api.anthropic.com`, Claude Code turns off features such as [Remote Control](https://code.claude.com/docs/en/remote-control.md#requirements) and [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md#platform-availability), whatever the gateway forwards. Some Anthropic-only features such as the [Advisor](https://code.claude.com/docs/en/advisor.md) work only if the gateway forwards requests intact to the Anthropic API.224> If you authenticate through an [LLM gateway](https://code.claude.com/docs/en/llm-gateway), feature availability matches the underlying provider the gateway forwards to, except for the features Claude Code itself turns off. Whenever `ANTHROPIC_BASE_URL` points at a host other than `api.anthropic.com`, Claude Code turns off features such as [Remote Control](https://code.claude.com/docs/en/remote-control.md#requirements) and [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md#platform-availability), whatever the gateway forwards. Some features, such as the [Advisor](https://code.claude.com/docs/en/advisor.md#requirements), work only if the gateway forwards requests intact.

225>225>

226> For how the requests Claude Code sends differ between an Amazon Bedrock- or Agent Platform-format gateway, an `ANTHROPIC_BASE_URL` gateway, and a Claude apps gateway sign-in, see [client behavior by connection method](https://code.claude.com/docs/en/llm-gateway-protocol.md#how-the-connection-method-changes-client-behavior).226> For how the requests Claude Code sends differ between an Amazon Bedrock- or Agent Platform-format gateway, an `ANTHROPIC_BASE_URL` gateway, and a Claude apps gateway sign-in, see [client behavior by connection method](https://code.claude.com/docs/en/llm-gateway-protocol.md#how-the-connection-method-changes-client-behavior).

227 227

244 244

245> [tab] Claude Platform on AWS245> [tab] Claude Platform on AWS

246>246>

247> **Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](https://code.claude.com/docs/en/fast-mode.md), [Advisor](https://code.claude.com/docs/en/advisor.md), [Channels](https://code.claude.com/docs/en/channels.md), [GitHub Actions](https://code.claude.com/docs/en/github-actions.md), the [analytics dashboard](https://code.claude.com/docs/en/analytics.md), [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md), and the [`/design-sync` and `/import` commands](https://code.claude.com/docs/en/commands#all-commands).247> **Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](https://code.claude.com/docs/en/fast-mode.md), [Channels](https://code.claude.com/docs/en/channels.md), [GitHub Actions](https://code.claude.com/docs/en/github-actions.md), the [analytics dashboard](https://code.claude.com/docs/en/analytics.md), [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md), and the [`/design-sync` and `/import` commands](https://code.claude.com/docs/en/commands#all-commands).

248>248>

249> **Available where Amazon Bedrock is not:** [web search](https://code.claude.com/docs/en/tools-reference.md#websearch-tool-behavior).249> **Available here, not on Amazon Bedrock:** [web search](https://code.claude.com/docs/en/tools-reference.md#websearch-tool-behavior), plus the [Advisor](https://code.claude.com/docs/en/advisor.md) in Claude Code v2.1.300 or later.

250>250>

251> **Partial support:**251> **Partial support:**

252>252>

256 256

257> [tab] Google Cloud's Agent Platform257> [tab] Google Cloud's Agent Platform

258>258>

259> **Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](https://code.claude.com/docs/en/fast-mode.md), [Advisor](https://code.claude.com/docs/en/advisor.md), [Channels](https://code.claude.com/docs/en/channels.md), the [analytics dashboard](https://code.claude.com/docs/en/analytics.md), [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md), and the [`/design-sync` and `/import` commands](https://code.claude.com/docs/en/commands#all-commands).259> **Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [Advisor](https://code.claude.com/docs/en/advisor.md), [Channels](https://code.claude.com/docs/en/channels.md), the [analytics dashboard](https://code.claude.com/docs/en/analytics.md), [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md), and the [`/design-sync` and `/import` commands](https://code.claude.com/docs/en/commands#all-commands).

260>260>

261> **Partial support:**261> **Partial support:**

262>262>

263> * [Desktop](https://code.claude.com/docs/en/desktop.md): via [managed settings](https://claude.com/docs/third-party/claude-desktop/configuration) or [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)263> * [Desktop](https://code.claude.com/docs/en/desktop.md): via [managed settings](https://claude.com/docs/third-party/claude-desktop/configuration) or [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

264> * [Web search](https://code.claude.com/docs/en/tools-reference.md#websearch-tool-behavior): Opus 4, Sonnet 4, Haiku 4.5, and later models264> * [Web search](https://code.claude.com/docs/en/tools-reference.md#websearch-tool-behavior): Opus 4, Sonnet 4, Haiku 4.5, and later models

265> * [Fast mode](https://code.claude.com/docs/en/fast-mode.md#use-fast-mode-on-agent-platform): Fable 5.2 in the `global`, `us`, and `eu` regions, or standard speed if Agent Platform refuses fast mode

265> * [Auto mode](https://code.claude.com/docs/en/auto-mode-config.md): Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and Fable models only266> * [Auto mode](https://code.claude.com/docs/en/auto-mode-config.md): Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and Fable models only

266> * [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md): between your sessions on this machine only <sup>[5](#fn5)</sup>267> * [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md): between your sessions on this machine only <sup>[5](#fn5)</sup>

267> * [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md): subject to your Google Cloud agreement268> * [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md): subject to your Google Cloud agreement

gateways.md +1 −1

Details

50 50

51## Subscriptions and gateways51## Subscriptions and gateways

52 52

53When developers connect through a gateway with a gateway credential, usage is billed to your organization's provider account at API rates, and their claude.ai subscriptions aren't used or charged. Setting [`ANTHROPIC_AUTH_TOKEN`](https://code.claude.com/docs/en/env-vars) for a gateway you run, or signing in to a Claude apps gateway with `/login`, turns off subscription login for that session. Every request forwarded under that credential is charged to the account behind the gateway's provider credential.53When developers connect through a gateway with a gateway credential, usage is billed to your organization's provider account at API rates, and their claude.ai subscriptions aren't used or charged. Every request forwarded under that credential is charged to the account behind the gateway's provider credential.

54 54

55The exception is setting only `ANTHROPIC_BASE_URL`, with no gateway credential. Requests still route through the gateway, but a saved claude.ai login stays the active credential, so the subscription's usage limits and billing apply. [Other LLM gateways](https://code.claude.com/docs/en/llm-gateway#subscriptions-and-gateways) covers that configuration and what the gateway has to forward for it to work.55The exception is setting only `ANTHROPIC_BASE_URL`, with no gateway credential. Requests still route through the gateway, but a saved claude.ai login stays the active credential, so the subscription's usage limits and billing apply. [Other LLM gateways](https://code.claude.com/docs/en/llm-gateway#subscriptions-and-gateways) covers that configuration and what the gateway has to forward for it to work.

56 56

github-actions.md +1 −0

Details

135| Merge queues | Read |135| Merge queues | Read |

136| Metadata | Read |136| Metadata | Read |

137| Pull requests | Read and write |137| Pull requests | Read and write |

138| Repository creation | Read and write |

138| Repository hooks | Read and write |139| Repository hooks | Read and write |

139| Statuses | Read |140| Statuses | Read |

140| Workflows | Read and write |141| Workflows | Read and write |

github-enterprise-server.md +1 −1

Details

190A few features behave differently on GHES than on github.com. The [feature table](#what-works-with-github-enterprise-server) summarizes support; this section covers the workarounds.190A few features behave differently on GHES than on github.com. The [feature table](#what-works-with-github-enterprise-server) summarizes support; this section covers the workarounds.

191 191

192* **`/install-github-app` command**: follow the [admin setup](#admin-setup) flow on claude.ai instead. If you also want GitHub Actions workflows on GHES, adapt the [example workflow](https://github.com/anthropics/claude-code-action/blob/main/examples/claude.yml) manually.192* **`/install-github-app` command**: follow the [admin setup](#admin-setup) flow on claude.ai instead. If you also want GitHub Actions workflows on GHES, adapt the [example workflow](https://github.com/anthropics/claude-code-action/blob/main/examples/claude.yml) manually.

193* **GitHub MCP server**: use the `gh` CLI configured for your GHES host instead. Run `gh auth login --hostname github.example.com` to authenticate, then Claude can use `gh` commands in sessions.193* **GitHub MCP server**: in a session on your own machine, use the `gh` CLI configured for your GHES host instead. Run `gh auth login --hostname github.example.com` to authenticate, then Claude can use `gh` commands there.

194 194

195## Troubleshooting195## Troubleshooting

196 196

goal.md +3 −2

Details

131 131

132#### Errors you have to fix clear the goal132#### Errors you have to fix clear the goal

133 133

134If a turn fails on an error that won't clear until you fix it, Claude Code clears the goal and prints a warning naming the cause. The warning starts with `Goal cleared after an unrecoverable error` and ends with `Run /goal again to continue`. Fix the cause, then [set the goal again](#set-a-goal) with `/goal <condition>`. Four kinds of failure clear the goal:134If a turn fails on an error that won't clear until you fix it, Claude Code clears the goal and prints a warning naming the cause. The warning starts with `Goal cleared after an unrecoverable error` and ends with `Run /goal again to continue`. Fix the cause, then [set the goal again](#set-a-goal) with `/goal <condition>`. Failures that clear the goal include:

135 135

136* An authentication failure, when Claude Code manages its own credentials. When a host manages them for you, such as the desktop app or a [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md), Claude Code leaves the goal active because the host restores access on its own.136* An authentication failure, when Claude Code manages its own credentials. When a host manages them for you, such as the desktop app or a [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md), Claude Code leaves the goal active because the host restores access on its own.

137* A disk too full for Claude Code to renew your claude.ai login, when Claude Code manages its own credentials. The warning shows `(disk full)`. [Free space on the disk holding the Claude Code config directory](https://code.claude.com/docs/en/errors.md#could-not-refresh-your-login-disk-full).

137* An exhausted credit balance138* An exhausted credit balance

138* A context overflow that [auto-compaction](https://code.claude.com/docs/en/model-config.md#set-the-auto-compact-window) couldn't clear139* A context overflow that [auto-compaction](https://code.claude.com/docs/en/model-config.md#set-the-auto-compact-window) couldn't clear

139* A model that isn't available140* A model that isn't available

178 179

179## Requirements180## Requirements

180 181

181Claude Code makes `/goal` available under the same [workspace trust rule as hooks in settings files](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder), because the evaluator is part of the hooks system. `/goal` is also unavailable when [`disableAllHooks`](https://code.claude.com/docs/en/hooks#disable-or-remove-hooks) is `true` after settings precedence applies, or when [`allowManagedHooksOnly`](https://code.claude.com/docs/en/settings-reference#allowmanagedhooksonly) is set in managed settings. In each case, the command tells you why instead of silently doing nothing.182Claude Code makes `/goal` available under the same [workspace trust rule as hooks in settings files](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder), because the evaluator is part of the hooks system. `/goal` is also unavailable when [`disableAllHooks`](https://code.claude.com/docs/en/hooks#disable-or-remove-hooks) is `true` after settings precedence applies, or when [`allowManagedHooksOnly`](https://code.claude.com/docs/en/settings-reference#allowmanagedhooksonly) is set in managed settings.

182 183

183## See also184## See also

184 185

google-vertex-ai.md +1 −1

Details

139* **Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, and later**: Claude Code enables tool search by default.139* **Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, and later**: Claude Code enables tool search by default.

140* **Earlier models**: Claude Code loads MCP tool definitions upfront, because their Agent Platform serving stacks reject the required beta header. Setting `ENABLE_TOOL_SEARCH=true` doesn't override this.140* **Earlier models**: Claude Code loads MCP tool definitions upfront, because their Agent Platform serving stacks reject the required beta header. Setting `ENABLE_TOOL_SEARCH=true` doesn't override this.

141 141

142Set `ENABLE_TOOL_SEARCH=false` to disable tool search on every model. Before v2.1.221, Claude Code disabled tool search for all models on Google Cloud's Agent Platform unless you set `ENABLE_TOOL_SEARCH=true`.142Set `ENABLE_TOOL_SEARCH=false` to disable tool search on every model.

143 143

144### 5. Pin model versions144### 5. Pin model versions

145 145

hooks.md +28 −4

Details

572 572

573Claude Code reads the tool's text content the same way it reads command-hook stdout, following the [parsing rule under exit code 0](#exit-code-0). If the tool returns `isError: true`, the hook produces a non-blocking error and execution continues.573Claude Code reads the tool's text content the same way it reads command-hook stdout, following the [parsing rule under exit code 0](#exit-code-0). If the tool returns `isError: true`, the hook produces a non-blocking error and execution continues.

574 574

575If a hook error contains one of these messages, Claude Code couldn't read the tool's answer, so the hook gave no verdict:

576

577```text theme={null}

578MCP tool "security_scan" on server "my_server" gave no answer that could be read, because a message from the server was too large, so this hook gave no verdict. If this keeps happening, the tool must send a smaller answer.

579MCP tool "security_scan" on server "my_server" answered without its text, which happens when a result is too large, so this hook gave no verdict. If this keeps happening, the tool must send a smaller answer.

580```

581

582On `PreToolUse`, Claude Code refuses the tool call the hook was checking. On other events such as `UserPromptSubmit`, `PostToolUse`, and `Stop`, the error is non-blocking.

583

584If the error keeps appearing, return less data from the tool, or change the hook's [`tool` or `input`](#mcp-tool-hook-fields) so the answer is smaller.

585

575##### When the server is still connecting586##### When the server is still connecting

576 587

577On events where a hook can block or change the result, such as `PreToolUse` or `Stop`, Claude Code waits for a connecting server before it calls the tool, for at most [`MCP_TIMEOUT`](https://code.claude.com/docs/en/env-vars) and within the hook's own [`timeout`](#common-fields). On observational events, such as `Notification` or `SessionEnd`, it doesn't wait.588On events where a hook can block or change the result, such as `PreToolUse` or `Stop`, Claude Code waits for a connecting server before it calls the tool, for at most [`MCP_TIMEOUT`](https://code.claude.com/docs/en/env-vars) and within the hook's own [`timeout`](#common-fields). On observational events, such as `Notification` or `SessionEnd`, it doesn't wait.

892 903

893#### Hooks that start a background process904#### Hooks that start a background process

894 905

906A hook can start a long-running program, such as a dev server, and leave it running while the session continues. In the hook's script or [shell form](#exec-form-and-shell-form) command:

907

908* Run the program in the background

909* Redirect its stdout and stderr. For example, the Bash command `npm run dev > dev-server.log 2>&1 &` sends both to a file. If you don't redirect them, a hook that isn't [async](#run-hooks-in-the-background) takes up to 10 seconds to finish after its own process exits.

910

895If your command hook makes its decision in a background process and exits, a deny that process prints after Claude Code has stopped reading doesn't block the tool call. For a hook that isn't [async](#run-hooks-in-the-background), Claude Code finishes reading the hook's output shortly after the hook's own process exits.911If your command hook makes its decision in a background process and exits, a deny that process prints after Claude Code has stopped reading doesn't block the tool call. For a hook that isn't [async](#run-hooks-in-the-background), Claude Code finishes reading the hook's output shortly after the hook's own process exits.

896 912

897Print the decision before you start a background process, and redirect that process's stdout and stderr. If your script prints an allow, then starts a background process without redirecting that process's stdout and stderr, Claude Code blocks the tool call. The hook error includes `refusing to honor the suspect capture`.913Print the decision before you start a background process, and redirect that process's stdout and stderr. If your script prints an allow, then starts a background process without redirecting that process's stdout and stderr, Claude Code blocks the tool call. The hook error includes `stdio went quiet` and `refusing to honor the suspect capture`.

898 914

899This `PreToolUse` hook script prints the decision with `policy-check.sh`, then uploads metrics in the background:915This `PreToolUse` hook script prints the decision with `policy-check.sh`, then uploads metrics in the background:

900 916

1193 1209

1194* `PreToolUse`: `updatedInput` directly under `hookSpecificOutput` replaces a tool's arguments before it runs. See [PreToolUse decision control](#pretooluse-decision-control)1210* `PreToolUse`: `updatedInput` directly under `hookSpecificOutput` replaces a tool's arguments before it runs. See [PreToolUse decision control](#pretooluse-decision-control)

1195* `PermissionRequest`: `updatedInput` inside the `decision` object. See [PermissionRequest decision control](#permissionrequest-decision-control)1211* `PermissionRequest`: `updatedInput` inside the `decision` object. See [PermissionRequest decision control](#permissionrequest-decision-control)

1196* `PostToolUse`: `updatedToolOutput` replaces the tool's result. See [PostToolUse decision control](#posttooluse-decision-control)1212* `PostToolUse`: `updatedToolOutput` replaces the tool's result. In a [Cowork](https://claude.com/docs/cowork/overview) cloud session, Claude Code ignores `updatedToolOutput` when the tool is `AskUserQuestion` or `ExitPlanMode`, and Claude reads the original answer or plan. See [PostToolUse decision control](#posttooluse-decision-control)

1197* `UserPromptSubmit`: can't replace the prompt; it only injects `additionalContext` alongside it1213* `UserPromptSubmit`: can't replace the prompt; it only injects `additionalContext` alongside it

1198 1214

1199For redaction or transformation use cases, intercept at `PreToolUse` for outbound tool inputs and `PostToolUse` for inbound tool results.1215For redaction or transformation use cases, intercept at `PreToolUse` for outbound tool inputs and `PostToolUse` for inbound tool results.

2212 2228

2229In `rules`, for a [permission rule](https://code.claude.com/docs/en/permissions.md#permission-rule-syntax) written `Tool(specifier)`, `toolName` is the tool's name and `ruleContent` is the specifier:

2230

2231* `Bash(npm test)`: `{ "toolName": "Bash", "ruleContent": "npm test" }`

2232* `Bash` or `Bash(*)`: `{ "toolName": "Bash" }`, because both match the whole tool

2233* `mcp__github__get_issue`: `{ "toolName": "mcp__github__get_issue" }`

2234

2235Leave `ruleContent` out of an allow rule for an [MCP tool](https://code.claude.com/docs/en/permissions.md#mcp). If you add it, the rule doesn't match any call.

2236

2213> [!NOTE]2237> [!NOTE]

2214>2238>

2215> `setMode` with `bypassPermissions` only takes effect if you launched the session with bypass mode already available: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`, or `permissions.defaultMode: "bypassPermissions"` in [user, `--settings`, or managed settings](https://code.claude.com/docs/en/settings-reference#permissions-defaultmode). Otherwise the update is a no-op. The update is also a no-op when [`permissions.disableBypassPermissionsMode`](https://code.claude.com/docs/en/permissions#managed-settings) disables the mode, or when the session starts in [restricted mode](https://code.claude.com/docs/en/cli-reference.md#cli-flags).2239> `setMode` with `bypassPermissions` only takes effect if you launched the session with bypass mode already available: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`, or `permissions.defaultMode: "bypassPermissions"` in [user, `--settings`, or managed settings](https://code.claude.com/docs/en/settings-reference#permissions-defaultmode). Otherwise the update is a no-op. The update is also a no-op when [`permissions.disableBypassPermissionsMode`](https://code.claude.com/docs/en/permissions#managed-settings) disables the mode, or when the session starts in [restricted mode](https://code.claude.com/docs/en/cli-reference.md#cli-flags).

2290| `additionalContext` | String added to Claude's context alongside the tool result. See [Add context for Claude](#add-context-for-claude) |2314| `additionalContext` | String added to Claude's context alongside the tool result. See [Add context for Claude](#add-context-for-claude) |

2291| `classifierContext` | Short note about this call's result for the [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) classifier rather than for Claude. See [Annotate a result for the auto mode classifier](#annotate-a-result-for-the-auto-mode-classifier). Requires Claude Code v2.1.236 or later |2315| `classifierContext` | Short note about this call's result for the [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) classifier rather than for Claude. See [Annotate a result for the auto mode classifier](#annotate-a-result-for-the-auto-mode-classifier). Requires Claude Code v2.1.236 or later |

2292| `updatedToolOutput` | Replaces the tool's output with the provided value before it is sent to Claude. The value must match the tool's output shape |2316| `updatedToolOutput` | Replaces the tool's output with the provided value before it is sent to Claude. The value must match the tool's output shape. In a [Cowork](https://claude.com/docs/cowork/overview) cloud session, Claude Code ignores this field when the tool is `AskUserQuestion` or `ExitPlanMode`, and Claude reads the original answer or plan |

2293| `updatedMCPToolOutput` | Replaces the output for [MCP tools](#match-mcp-tools) only. Prefer `updatedToolOutput`, which works for all tools |2317| `updatedMCPToolOutput` | Replaces the output for [MCP tools](#match-mcp-tools) only. Prefer `updatedToolOutput`, which also works for built-in tools |

2294 2318

2295The example below replaces the output of a `Bash` call. The replacement value matches the `Bash` tool's output shape:2319The example below replaces the output of a `Bash` call. The replacement value matches the `Bash` tool's output shape:

2296 2320

interactive-mode.md +3 −1

Details

251| `d`/`x` | Delete selection |251| `d`/`x` | Delete selection |

252| `y` | Yank selection |252| `y` | Yank selection |

253| `c`/`s` | Change selection |253| `c`/`s` | Change selection |

254| `p` | Replace selection with register contents |254| `p`/`P` | Replace selection with register contents |

255| `r{char}` | Replace every selected character with `{char}` |255| `r{char}` | Replace every selected character with `{char}` |

256| `~`/`u`/`U` | Toggle, lowercase, or uppercase selection |256| `~`/`u`/`U` | Toggle, lowercase, or uppercase selection |

257| `>`/`<` | Indent or dedent selected lines |257| `>`/`<` | Indent or dedent selected lines |

304 304

305Accepting a match or canceling the search takes effect immediately, even while Claude Code is still loading the history.305Accepting a match or canceling the search takes effect immediately, even while Claude Code is still loading the history.

306 306

307To find an earlier prompt when all you remember is something long you pasted into it, such as an error log, press `Ctrl+R` and type a word from the paste. Requires Claude Code v2.1.314 or later.

308

307## Background Bash commands309## Background Bash commands

308 310

309Claude Code supports running Bash commands in the background, allowing you to continue working while long-running processes execute.311Claude Code supports running Bash commands in the background, allowing you to continue working while long-running processes execute.

keybindings.md +1 −1

Details

305 305

306### Diff actions306### Diff actions

307 307

308These actions reach only Claude Code's earlier diff viewer, which `/diff` opens outside [fullscreen rendering](https://code.claude.com/docs/en/fullscreen.md) after you disable the [`cc-plugin-diff` mod](https://code.claude.com/docs/en/plugins/mods/overview#mods-built-into-claude-code) in `/plugin`. While that mod is enabled, `/diff` opens the [diff dialog](https://code.claude.com/docs/en/interactive-mode.md#diff-dialog) instead. A `keybindings.json` that names these actions loads without errors either way.308These actions reach only Claude Code's earlier diff viewer, which `/diff` opens outside [fullscreen rendering](https://code.claude.com/docs/en/fullscreen.md) after you disable the [`cc-plugin-diff` mod](https://code.claude.com/docs/en/plugins/mods/overview#mods-built-into-claude-code) in `/plugin`. While that mod is enabled, `/diff` opens the [diff dialog](https://code.claude.com/docs/en/interactive-mode.md#diff-dialog) instead.

309 309

310Actions available in the `DiffDialog` context:310Actions available in the `DiffDialog` context:

311 311

large-codebases.md +4 −2

Details

197* `Marketplace "claude-plugins-official" not found`: add the marketplace with `/plugin marketplace add anthropics/claude-plugins-official`, then retry the install.197* `Marketplace "claude-plugins-official" not found`: add the marketplace with `/plugin marketplace add anthropics/claude-plugins-official`, then retry the install.

198* `Plugin "<name>" not found in marketplace "claude-plugins-official"`: your local copy of the marketplace catalog may be out of date. Refresh it with `/plugin marketplace update claude-plugins-official`, then retry the install. If the retry prints the same message, see [Plugin not found in marketplace](https://code.claude.com/docs/en/plugins/troubleshooting.md#plugin-not-found-in-marketplace).198* `Plugin "<name>" not found in marketplace "claude-plugins-official"`: your local copy of the marketplace catalog may be out of date. Refresh it with `/plugin marketplace update claude-plugins-official`, then retry the install. If the retry prints the same message, see [Plugin not found in marketplace](https://code.claude.com/docs/en/plugins/troubleshooting.md#plugin-not-found-in-marketplace).

199 199

200To enable a plugin for everyone in the repository rather than installing it yourself, add it to the [`enabledPlugins` project setting](https://code.claude.com/docs/en/settings-reference#plugin-settings).200To turn a plugin on for everyone in the repository, add it to the [`enabledPlugins` project setting](https://code.claude.com/docs/en/settings-reference#plugin-settings). Each person still [installs it](https://code.claude.com/docs/en/plugins/loading.md#enabled-in-project-settings-but-not-installed).

201 201

202Code intelligence plugins require the language's language server binary on each developer's machine. See [which binary each language requires](https://code.claude.com/docs/en/plugins/code-intelligence.md). Installing from the official marketplace requires network access to GitHub, where the marketplace is hosted. On a restricted network, [add the marketplace from an internal Git host or local path](https://code.claude.com/docs/en/plugins/install.md#add-a-marketplace) instead.202Code intelligence plugins require the language's language server binary on each developer's machine. See [which binary each language requires](https://code.claude.com/docs/en/plugins/code-intelligence.md). Installing from the official marketplace requires network access to GitHub, where the marketplace is hosted. On a restricted network, [add the marketplace from an internal Git host or local path](https://code.claude.com/docs/en/plugins/install.md#add-a-marketplace) instead.

203 203

235 235

236List directories in `sparsePaths`, not individual files. Root-level files like `package.json`, `tsconfig.base.json`, and lock files are always checked out alongside the directories you list. Root-level directories are not, so include `.claude` in the list if you want the repository root's `.claude/settings.json` or `.claude/rules/` available inside the worktree. For project skills, agents, and commands, see [What worktrees share with the main checkout](https://code.claude.com/docs/en/worktrees.md#what-worktrees-share-with-the-main-checkout).236List directories in `sparsePaths`, not individual files. Root-level files like `package.json`, `tsconfig.base.json`, and lock files are always checked out alongside the directories you list. Root-level directories are not, so include `.claude` in the list if you want the repository root's `.claude/settings.json` or `.claude/rules/` available inside the worktree. For project skills, agents, and commands, see [What worktrees share with the main checkout](https://code.claude.com/docs/en/worktrees.md#what-worktrees-share-with-the-main-checkout).

237 237

238Sparse checkout requires git to enable `extensions.worktreeConfig` in the repository's shared `.git/config` while a sparse worktree exists. Claude Code removes that entry after the last worktree is removed, but only if Claude Code added it. It never removes a value you set yourself.238> [!NOTE]

239>

240> Sparse checkout requires git to enable `extensions.worktreeConfig` in the repository's shared `.git/config` while a sparse worktree exists. Claude Code removes that entry after the last worktree is removed, but only if Claude Code added it.

239 241

240To avoid duplicating large directories like `node_modules` across worktrees, pair `sparsePaths` with `symlinkDirectories` in the same `.claude/settings.json`:242To avoid duplicating large directories like `node_modules` across worktrees, pair `sparsePaths` with `symlinkDirectories` in the same `.claude/settings.json`:

241 243

llm-gateway.md +1 −1

Details

47 47

48While a [gateway credential variable](https://code.claude.com/docs/en/llm-gateway-connect.md#set-the-credential-variable) or `apiKeyHelper` is active, requests carry that credential in place of a developer's claude.ai subscription login, and the subscription's usage limits don't apply to them. Claude Code keeps a saved claude.ai login on the machine but doesn't send it with those requests. That traffic is billed per token to whoever owns the credential the gateway forwards, such as your organization's Anthropic Console account, or your Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry account when the gateway routes there.48While a [gateway credential variable](https://code.claude.com/docs/en/llm-gateway-connect.md#set-the-credential-variable) or `apiKeyHelper` is active, requests carry that credential in place of a developer's claude.ai subscription login, and the subscription's usage limits don't apply to them. Claude Code keeps a saved claude.ai login on the machine but doesn't send it with those requests. That traffic is billed per token to whoever owns the credential the gateway forwards, such as your organization's Anthropic Console account, or your Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry account when the gateway routes there.

49 49

50[`ANTHROPIC_BASE_URL`](https://code.claude.com/docs/en/llm-gateway-connect#set-the-base-url-and-credential) is the variable that points Claude Code at the gateway. Setting only that variable, without a gateway credential, doesn't replace the subscription. Requests still route through the gateway, but a saved claude.ai login remains the active credential, so its usage limits and billing apply. Gateways that pass this traffic on to Anthropic must forward the OAuth capability in `anthropic-beta`; see the [request headers reference](https://code.claude.com/docs/en/llm-gateway-protocol.md#request-headers).50[`ANTHROPIC_BASE_URL`](https://code.claude.com/docs/en/llm-gateway-connect#set-the-base-url-and-credential) is the variable that points Claude Code at the gateway. Setting only that variable, without a gateway credential, doesn't replace the subscription. Requests still route through the gateway, but a saved claude.ai login remains the active credential, so its usage limits and billing apply. Gateways that pass this traffic on to Anthropic must forward `Authorization` and the OAuth capability in `anthropic-beta`; see the [request headers reference](https://code.claude.com/docs/en/llm-gateway-protocol.md#request-headers).

51 51

52## Related pages52## Related pages

53 53

llm-gateway-connect.md +2 −2

Details

156 156

157### Conflicts with an existing login157### Conflicts with an existing login

158 158

159A gateway credential variable takes precedence over a saved claude.ai login or Console key. Your claude.ai login stays saved and unused while the variable is set; unset the variable and Claude Code goes back to it. With `ANTHROPIC_AUTH_TOKEN`, the variable takes precedence immediately. With `ANTHROPIC_API_KEY`, you are prompted once in interactive mode to approve the key before it takes over.159A gateway credential variable takes precedence over a saved claude.ai login or Console key. With `ANTHROPIC_AUTH_TOKEN`, the variable takes precedence immediately. With `ANTHROPIC_API_KEY`, you are prompted once in interactive mode to approve the key before it takes over.

160 160

161Run `/status` to confirm which credential source is active. If startup shows an auth-conflict warning naming two sources, see the first row of the [troubleshooting table](#troubleshoot-gateway-errors) for which one to drop. To clear a saved login so only the gateway credential remains, run `/logout`.161Run `/status` to confirm which credential source is active. If startup shows an auth-conflict warning naming two sources, see the first row of the [troubleshooting table](#troubleshoot-gateway-errors) for which one to drop. To clear a saved login so only the gateway credential remains, run `/logout`.

162 162

378Setting the variable has these effects and limits:378Setting the variable has these effects and limits:

379 379

380* It disables auto-updates, so plan for another update path, such as your package manager or managed distribution.380* It disables auto-updates, so plan for another update path, such as your package manager or managed distribution.

381* It suppresses the [fast mode](https://code.claude.com/docs/en/fast-mode.md) availability check. Unless a previous check already enabled fast mode on the machine, `/fast` reports that fast mode is unavailable.381* It suppresses the [fast mode](https://code.claude.com/docs/en/fast-mode.md) availability check. On the Anthropic API, if `/fast` then reports that fast mode is unavailable, see [use fast mode behind proxies and LLM gateways](https://code.claude.com/docs/en/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) to restore fast mode.

382* It doesn't affect [gateway model discovery](#add-gateway-models-to-the-model-picker), which queries only your gateway. Before v2.1.257, the variable also stopped discovery from refreshing, so the picker kept the previously cached list.382* It doesn't affect [gateway model discovery](#add-gateway-models-to-the-model-picker), which queries only your gateway. Before v2.1.257, the variable also stopped discovery from refreshing, so the picker kept the previously cached list.

383* The WebFetch tool's [domain safety check](https://code.claude.com/docs/en/data-usage.md#webfetch-domain-safety-check) isn't affected and still calls `api.anthropic.com`. Turn it off separately with `skipWebFetchPreflight: true` in [settings](https://code.claude.com/docs/en/settings.md) if your network blocks that host.383* The WebFetch tool's [domain safety check](https://code.claude.com/docs/en/data-usage.md#webfetch-domain-safety-check) isn't affected and still calls `api.anthropic.com`. Turn it off separately with `skipWebFetchPreflight: true` in [settings](https://code.claude.com/docs/en/settings.md) if your network blocks that host.

384* For each telemetry stream and the variable that controls it, see [telemetry services](https://code.claude.com/docs/en/data-usage.md#telemetry-services).384* For each telemetry stream and the variable that controls it, see [telemetry services](https://code.claude.com/docs/en/data-usage.md#telemetry-services).

llm-gateway-protocol.md +3 −3

Details

40 40

42| :- | :- | :- | :- |42| :- | :- | :- | :- |

44| Amazon Bedrock InvokeModel | `ANTHROPIC_BEDROCK_BASE_URL` with `CLAUDE_CODE_USE_BEDROCK=1` | `/model/{model}/invoke`, `/model/{model}/invoke-with-response-stream`, `/model/{model}/count-tokens` (optional) | `anthropic_beta` and `anthropic_version` request body fields |44| Amazon Bedrock InvokeModel | `ANTHROPIC_BEDROCK_BASE_URL` with `CLAUDE_CODE_USE_BEDROCK=1` | `/model/{model}/invoke`, `/model/{model}/invoke-with-response-stream`, `/model/{model}/count-tokens` (optional) | `anthropic_beta` and `anthropic_version` request body fields |

45| Google Cloud's Agent Platform rawPredict | `ANTHROPIC_VERTEX_BASE_URL` with `CLAUDE_CODE_USE_VERTEX=1` | `:rawPredict`, `:streamRawPredict`, `count-tokens:rawPredict` (optional) | `anthropic-beta` and `anthropic-version` request headers, and the `anthropic_version` request body field |45| Google Cloud's Agent Platform rawPredict | `ANTHROPIC_VERTEX_BASE_URL` with `CLAUDE_CODE_USE_VERTEX=1` | `:rawPredict`, `:streamRawPredict`, `count-tokens:rawPredict` (optional) | `anthropic-beta` and `anthropic-version` request headers, and the `anthropic_version` request body field |

46 46

115 115

116## Request headers116## Request headers

117 117

118Claude Code includes these headers on API requests. Header names are case-insensitive on the wire. Forward `anthropic-version` and `anthropic-beta` unchanged, plus `anthropic-workspace-id` when the upstream is the [Claude Platform on AWS](https://code.claude.com/docs/en/claude-platform-on-aws.md); the rest the gateway may consume for routing, attribution, and tracing, and need not forward.118Claude Code includes these headers on API requests. Header names are case-insensitive on the wire. Forward `anthropic-version` and `anthropic-beta` unchanged, plus `anthropic-workspace-id` when the upstream is the [Claude Platform on AWS](https://code.claude.com/docs/en/claude-platform-on-aws.md). Also forward `Authorization` when your gateway authenticates to Anthropic with the developer's claude.ai login and not a key of its own. The rest the gateway may consume for routing, attribution, and tracing, and need not forward.

119 119

120| Header | Description |120| Header | Description |

121| :- | :- |121| :- | :- |

122| `Authorization`, `x-api-key` | The developer's gateway credential, in one or both headers depending on which [credential variable](https://code.claude.com/docs/en/llm-gateway-connect.md#set-the-credential-variable) they set |122| `Authorization`, `x-api-key` | The developer's gateway credential, in one or both headers depending on which [credential variable](https://code.claude.com/docs/en/llm-gateway-connect.md#set-the-credential-variable) they set. With a claude.ai login and no gateway credential, `Authorization` carries the login's token |

123| `anthropic-version` | API version, currently `2023-06-01`. Amazon Bedrock- and Google Cloud's Agent Platform-format requests also carry the `anthropic_version` body field, whose value is the provider dialect string, not this header's value |123| `anthropic-version` | API version, currently `2023-06-01`. Amazon Bedrock- and Google Cloud's Agent Platform-format requests also carry the `anthropic_version` body field, whose value is the provider dialect string, not this header's value |

124| `anthropic-beta` | Comma-separated capability values for the request. Forward the header verbatim; don't allowlist individual values, because the set changes with Claude Code releases. When the developer authenticates with a claude.ai login, which is possible when `ANTHROPIC_BASE_URL` is set without a gateway credential variable, this header also carries an OAuth capability that the upstream requires, and stripping it fails those requests with `401` |124| `anthropic-beta` | Comma-separated capability values for the request. Forward the header verbatim; don't allowlist individual values, because the set changes with Claude Code releases. When the developer authenticates with a claude.ai login, which is possible when `ANTHROPIC_BASE_URL` is set without a gateway credential variable, this header also carries an OAuth capability that the upstream requires, and stripping it fails those requests with `401` |

125| `x-claude-code-session-id` | A unique identifier for the current Claude Code session. Use it to aggregate all requests from one session without parsing request bodies |125| `x-claude-code-session-id` | A unique identifier for the current Claude Code session. Use it to aggregate all requests from one session without parsing request bodies |

llm-gateway-rollout.md +1 −1

Details

251 251

252* A login prompt means a credential gap. Run `/status` and open the **Status** tab: when the `Setting sources` line doesn't include managed settings, the distribution didn't reach the machine; when it does, the developer credential wasn't delivered, so set `ANTHROPIC_AUTH_TOKEN` or the `apiKeyHelper`252* A login prompt means a credential gap. Run `/status` and open the **Status** tab: when the `Setting sources` line doesn't include managed settings, the distribution didn't reach the machine; when it does, the developer credential wasn't delivered, so set `ANTHROPIC_AUTH_TOKEN` or the `apiKeyHelper`

253* `Failed to authenticate` errors mean the gateway is rejecting requests; its log says which credential failed. A rejection the gateway logs itself names the developer key, while a `401` from `api.anthropic.com` or your provider's endpoint means the provider credential the gateway holds was rejected253* `Failed to authenticate` errors mean the gateway is rejecting requests; its log says which credential failed. A rejection the gateway logs itself names the developer key, while a `401` from `api.anthropic.com` or your provider's endpoint means the provider credential the gateway holds was rejected

254* A one-time approval prompt for the key is expected on first use when the gateway expects keys in the `x-api-key` header, set as `ANTHROPIC_API_KEY`. With `ANTHROPIC_AUTH_TOKEN`, no prompt appears and the variable takes over silently; a previously saved claude.ai login is inactive for that session254* A one-time approval prompt for the key is expected on first use when the gateway expects keys in the `x-api-key` header, set as `ANTHROPIC_API_KEY`

255 255

256If your organization uses [fast mode](https://code.claude.com/docs/en/fast-mode.md), run `/fast` here too: the availability check calls `api.anthropic.com` directly rather than following the gateway base URL, so a gateway-routed session can report fast mode as unavailable or disabled even though inference works. [Use fast mode behind proxies and LLM gateways](https://code.claude.com/docs/en/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) maps each message to the variable that restores it, distributed with [the rest of the configuration](#distribute-the-configuration).256If your organization uses [fast mode](https://code.claude.com/docs/en/fast-mode.md), run `/fast` here too: the availability check calls `api.anthropic.com` directly rather than following the gateway base URL, so a gateway-routed session can report fast mode as unavailable or disabled even though inference works. [Use fast mode behind proxies and LLM gateways](https://code.claude.com/docs/en/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) maps each message to the variable that restores it, distributed with [the rest of the configuration](#distribute-the-configuration).

257 257

managed-mcp.md +1 −1

Details

187 187

188* `type` is `http` or `sse`. As in `.mcp.json`, `streamable-http` is accepted as an alias for `http`.188* `type` is `http` or `sse`. As in `.mcp.json`, `streamable-http` is accepted as an alias for `http`.

189* `url` is an `https://` URL. Claude Code refuses a plain `http://` URL, including one that points at `localhost`.189* `url` is an `https://` URL. Claude Code refuses a plain `http://` URL, including one that points at `localhost`.

190* The entry has no `command`, `args`, `env`, or `headersHelper` member, so a managed settings document never names a program to run on a user's machine.190* The entry has no `command`, `args`, `env`, or `headersHelper` member.

191* No value contains a `${VAR}` reference. Claude Code doesn't expand environment variables in these entries, so write literal values.191* No value contains a `${VAR}` reference. Claude Code doesn't expand environment variables in these entries, so write literal values.

192* The server name contains only letters, numbers, hyphens, and underscores, and no key or value contains control or invisible formatting characters.192* The server name contains only letters, numbers, hyphens, and underscores, and no key or value contains control or invisible formatting characters.

193 193

mcp.md +0 −2

Details

1800* **Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, and later**: tool search is on by default, the same as on the Anthropic API.1800* **Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, and later**: tool search is on by default, the same as on the Anthropic API.

1801* **Earlier Agent Platform models**: Claude Code loads all MCP tools upfront, because their serving stacks reject the required beta header. `ENABLE_TOOL_SEARCH=true` doesn't override this.1801* **Earlier Agent Platform models**: Claude Code loads all MCP tools upfront, because their serving stacks reject the required beta header. `ENABLE_TOOL_SEARCH=true` doesn't override this.

1802 1802

1803Before v2.1.221, Claude Code disabled tool search for all models on Google Cloud's Agent Platform unless you set `ENABLE_TOOL_SEARCH=true`.

~~1804~~

1805Control tool search behavior with the `ENABLE_TOOL_SEARCH` environment variable:1803Control tool search behavior with the `ENABLE_TOOL_SEARCH` environment variable:

1806 1804

1807| Value | Behavior |1805| Value | Behavior |

memory.md +1 −1

Details

163 163

164The inline form sets the variable for that one launch in Bash or Zsh. To keep it on for every session, add it to the `env` block in `~/.claude/settings.json` as shown in [Set environment variables](https://code.claude.com/docs/en/env-vars.md#set-environment-variables).164The inline form sets the variable for that one launch in Bash or Zsh. To keep it on for every session, add it to the `env` block in `~/.claude/settings.json` as shown in [Set environment variables](https://code.claude.com/docs/en/env-vars.md#set-environment-variables).

165 165

166This loads `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md`, and `CLAUDE.local.md` from the additional directory. `CLAUDE.local.md` is skipped if you exclude `local` from [`--setting-sources`](https://code.claude.com/docs/en/cli-reference).166With the variable set, Claude Code loads the additional directory's `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md`, and `.claude/rules/*.md` files except rules that set a [`paths` field](#path-specific-rules). `CLAUDE.local.md` is skipped if you exclude `local` from [`--setting-sources`](https://code.claude.com/docs/en/cli-reference).

167 167

168### Organize rules with `.claude/rules/`168### Organize rules with `.claude/rules/`

169 169

model-config.md +3 −3

Details

71* **Fable 5.2**: run `/model fable`, or launch with `claude --model fable`. In [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway) sessions, run `/model claude-fable-5-2` instead.71* **Fable 5.2**: run `/model fable`, or launch with `claude --model fable`. In [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway) sessions, run `/model claude-fable-5-2` instead.

72* **Fable 5.1 or Fable 5**: select it by model ID. On the Anthropic API, run `/model claude-fable-5-1` or `/model claude-fable-5`, or launch with `claude --model claude-fable-5-1`. On other providers, use your provider's model ID or [pin it](#pin-models-for-third-party-deployments) with `ANTHROPIC_DEFAULT_FABLE_MODEL`.72* **Fable 5.1 or Fable 5**: select it by model ID. On the Anthropic API, run `/model claude-fable-5-1` or `/model claude-fable-5`, or launch with `claude --model claude-fable-5-1`. On other providers, use your provider's model ID or [pin it](#pin-models-for-third-party-deployments) with `ANTHROPIC_DEFAULT_FABLE_MODEL`.

73 73

~~74On Pro, Max, Team, and Enterprise plans, a `claude-fable-5-1` model saved in your user settings moves to the `fable` alias:~~74On Pro, Max, Ultra, Team, and Enterprise plans, a `claude-fable-5-1` model saved in your user settings moves to the `fable` alias:

75 75

~~76* **Pro or Max plan**: the move happens the first time you run v2.1.321 or later. In the terminal, the startup model line can show `(auto-updated)` once.~~76* **Pro, Max, or Ultra plan**: the move happens the first time you run v2.1.321 or later. In the terminal, the startup model line can show `(auto-updated)` once.

77* **Team or Enterprise plan**: the move waits for your organization's settings, so it can come at a later startup, or not at all. It applies from the next session, with no `(auto-updated)` line. To check your model, run `/model`.77* **Team or Enterprise plan**: the move waits for your organization's settings, so it can come at a later startup, or not at all. It applies from the next session, with no `(auto-updated)` line. To check your model, run `/model`.

78 78

79After the move, sessions start at Fable 5.2's default effort unless you've [set a level](#adjust-effort-level) for it. Console accounts, third-party providers, and project, local, or managed settings keep `claude-fable-5-1`.79After the move, sessions start at Fable 5.2's default effort unless you've [set a level](#adjust-effort-level) for it. Console accounts, third-party providers, and project, local, or managed settings keep `claude-fable-5-1`.

97 97

98Depending on your plan and seat tier, Fable usage can bill to [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) instead of drawing on your plan's included limits. When it does, the `/model` picker shows "Requires usage credits" on the Fable row. To manage usage credits, see [Add usage credits to your subscription](https://code.claude.com/docs/en/costs.md#add-usage-credits-to-your-subscription).98Depending on your plan and seat tier, Fable usage can bill to [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) instead of drawing on your plan's included limits. When it does, the `/model` picker shows "Requires usage credits" on the Fable row. To manage usage credits, see [Add usage credits to your subscription](https://code.claude.com/docs/en/costs.md#add-usage-credits-to-your-subscription).

99 99

100In interactive sessions, Claude Code can show a Fable usage-credits consent prompt. Members of Enterprise plans with organization billing don't see the prompt. You can continue on Fable using usage credits or switch to your default model. You can also dismiss the prompt:100In interactive sessions, Claude Code can show a Fable usage-credits consent prompt. You can continue on Fable using usage credits or switch to your default model. You can also dismiss the prompt:

101 101

102* When you select a Fable model with `/model`, you keep your current model.102* When you select a Fable model with `/model`, you keep your current model.

103* Mid-session, Claude Code continues the turn on your default model.103* Mid-session, Claude Code continues the turn on your default model.

monitoring-usage.md +44 −21

Details

146 146

147### Metrics cardinality control147### Metrics cardinality control

148 148

149The following environment variables control which attributes are included in metrics to manage cardinality:149The following environment variables control which attributes are included in metrics and events to manage cardinality:

150 150

152| - | - | - | - |152| - | - | - | - |

159 159

160Lower cardinality generally means better performance and lower storage costs but less granular data for analysis.160Lower cardinality generally means better performance and lower storage costs but less granular data for analysis.

523export OTEL_METRICS_EXPORTER=otlp523export OTEL_METRICS_EXPORTER=otlp

524export OTEL_LOGS_EXPORTER=otlp524export OTEL_LOGS_EXPORTER=otlp

525export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf525export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf

526export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318526export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318/v1/metrics

527export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc527export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc

528export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317528export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317

529```529```

571 571

572To attribute telemetry in more detail, use these options:572To attribute telemetry in more detail, use these options:

573 573

574* **Identify Claude Tag sessions**: set `OTEL_METRICS_INCLUDE_ENTRYPOINT=true`, as described under [Metrics cardinality control](#metrics-cardinality-control). Metrics then carry `app.entrypoint`, whose value is `claude-in-slack` for Claude Tag sessions.574* **Identify Claude Tag sessions**: set `OTEL_METRICS_INCLUDE_ENTRYPOINT=true`, as described under [Metrics cardinality control](#metrics-cardinality-control). Metrics and events then carry `app.entrypoint`, whose value is `claude-in-slack` for Claude Tag sessions.

575* **Add custom attributes**: set [`OTEL_RESOURCE_ATTRIBUTES`](#multi-team-organization-support) in the same place you set the other `OTEL_*` variables for those sessions. If you `export` it in the environment's [setup script](https://code.claude.com/docs/en/cloud-environments.md#setup-scripts) instead, the value doesn't reach Claude Code: the setup script is a separate Bash script that runs before Claude Code launches, and variables it exports end with it.575* **Add custom attributes**: set [`OTEL_RESOURCE_ATTRIBUTES`](#multi-team-organization-support) in the same place you set the other `OTEL_*` variables for those sessions. If you `export` it in the environment's [setup script](https://code.claude.com/docs/en/cloud-environments.md#setup-scripts) instead, the value doesn't reach Claude Code: the setup script is a separate Bash script that runs before Claude Code launches, and variables it exports end with it.

576 576

577In Claude Tag channel sessions, Claude works as your organization's [shared identity](https://code.claude.com/docs/en/cloud-environments.md#set-the-environment-a-claude-tag-channel-uses) rather than as any member, so don't rely on the `user.*` attributes to identify who tagged Claude.577In Claude Tag channel sessions, Claude works as your organization's [shared identity](https://code.claude.com/docs/en/cloud-environments.md#set-the-environment-a-claude-tag-channel-uses) rather than as any member, so don't rely on the `user.*` attributes to identify who tagged Claude.

588| `ccr.session.id` | Cloud session identifier, the value of `CLAUDE_CODE_REMOTE_SESSION_ID`, on sessions that run in a [cloud environment](https://code.claude.com/docs/en/cloud-environments.md) | `OTEL_METRICS_INCLUDE_SESSION_ID` (default: true) |588| `ccr.session.id` | Cloud session identifier, the value of `CLAUDE_CODE_REMOTE_SESSION_ID`, on sessions that run in a [cloud environment](https://code.claude.com/docs/en/cloud-environments.md) | `OTEL_METRICS_INCLUDE_SESSION_ID` (default: true) |

590| `app.entrypoint` | How the session was launched, such as `cli`, `sdk-cli`, `sdk-ts`, `sdk-py`, `claude-vscode`, or `claude-in-slack` for Claude Tag sessions | `OTEL_METRICS_INCLUDE_ENTRYPOINT` (default: false) |590| `app.entrypoint` | How the session was launched, such as `cli`, `sdk-cli`, `sdk-ts`, `sdk-py`, `claude-vscode`, `claude-desktop` for Claude Desktop Code tab sessions outside the cloud, `claude-desktop-3p` for the same sessions on a [third-party deployment](https://claude.com/docs/third-party/claude-desktop/overview), or `claude-in-slack` for Claude Tag sessions. Cloud session values include `remote`, plus `remote_desktop` and `remote_mobile` for sessions you start from Claude Desktop or the mobile app | `OTEL_METRICS_INCLUDE_ENTRYPOINT` (default: false) |

593| `user.account_id` | Account ID in tagged format matching Anthropic admin APIs (when authenticated), such as `user_01BWBeN28...` | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (default: true) |593| `user.account_id` | Account ID in tagged format matching Anthropic admin APIs (when authenticated), such as `user_01BWBeN28...` | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (default: true) |

643 643

645| - | - | - |645| - | - | - |

660 660

661#### Session counter661#### Session counter

662 662

663Incremented at the start of each session.663Incremented at the start of each session. To count people instead, see [Usage monitoring](#usage-monitoring).

664 664

665**Attributes**:665**Attributes**:

666 666

711* `plugin.name`: Owning plugin when the active skill or subagent is provided by a plugin. Official-marketplace plugin names appear verbatim. Third-party plugin names are replaced with `"third-party"`. Absent when neither the skill nor the subagent has an owning plugin.711* `plugin.name`: Owning plugin when the active skill or subagent is provided by a plugin. Official-marketplace plugin names appear verbatim. Third-party plugin names are replaced with `"third-party"`. Absent when neither the skill nor the subagent has an owning plugin.

712* `marketplace.name`: Marketplace the owning plugin was installed from. Only emitted for official-marketplace plugins, even with `OTEL_LOG_TOOL_DETAILS=1` set. Absent otherwise.712* `marketplace.name`: Marketplace the owning plugin was installed from. Only emitted for official-marketplace plugins, even with `OTEL_LOG_TOOL_DETAILS=1` set. Absent otherwise.

713* `mcp_server.name`: MCP server whose tool result this request consumed. Built-in, claude.ai-proxied, and official-registry server names appear verbatim. User-configured server names are replaced with `"custom"`. Absent when the request consumed no MCP tool result. Before v2.1.222, Claude Code set this attribute on every request after an MCP tool call, not only on requests that consumed a tool result, so dashboards that aggregate it show a step down after you upgrade.713* `mcp_server.name`: MCP server whose tool result this request consumed. Built-in, claude.ai-proxied, and official-registry server names appear verbatim. User-configured server names are replaced with `"custom"`. Absent when the request consumed no MCP tool result. Before v2.1.222, Claude Code set this attribute on every request after an MCP tool call, not only on requests that consumed a tool result, so dashboards that aggregate it show a step down after you upgrade.

714* `mcp_tool.name`: MCP tool whose result this request consumed, with the same redaction and version behavior as `mcp_server.name`. Absent when the request consumed no MCP tool result.714 * From v2.1.312, the name of a remote server with a fixed URL that a plugin from Anthropic's official marketplace declares also appears verbatim, as `plugin_<plugin>_<server>`. That name is replaced with `"custom"` when the plugin's marketplace copy didn't come from Anthropic's registered source, such as one mounted from a seed directory in a cloud session.

715* `mcp_tool.name`: MCP tool whose result this request consumed, with the same redaction and version behavior as `mcp_server.name`, except that it can read `"custom"` when `mcp_server.name` shows a `plugin_<plugin>_<server>` name. Absent when the request consumed no MCP tool result.

715 716

716#### Token counter717#### Token counter

717 718

998 * A grant for the rest of the session, given at an earlier permission prompt in the same interactive CLI session999 * A grant for the rest of the session, given at an earlier permission prompt in the same interactive CLI session

999 * The tool being inherently safe1000 * The tool being inherently safe

1000 1001

1001 The `source` value doesn't indicate which of these sources matched. To find which one refused a call, look for the [Safety event](#safety-event) with the same `tool_use_id` and read its `category` and `rule_source` attributes. Some refused calls [have no safety event](#calls-without-a-safety-event).1002 The `source` value doesn't indicate which of these sources matched. When `classifier_verdict` is present, it gives the classifier outcome that decided the call. No `tool_decision` attribute names the permission rule or setting that refused the call.

1002 1003

1003 Claude Code also reports `"config"` when the permission prompt request itself fails. For example, that request fails when the Agent SDK's [`canUseTool`](https://code.claude.com/docs/en/agent-sdk/typescript#canusetool) callback or the [`--permission-prompt-tool`](https://code.claude.com/docs/en/cli-reference#cli-flags) tool returns an invalid result, or when the input stream closes while the request is pending.1004 Claude Code also reports `"config"` when the permission prompt request itself fails. For example, that request fails when the Agent SDK's [`canUseTool`](https://code.claude.com/docs/en/agent-sdk/typescript#canusetool) callback or the [`--permission-prompt-tool`](https://code.claude.com/docs/en/cli-reference#cli-flags) tool returns an invalid result, or when the input stream closes while the request is pending.

1004 * `"hook"`: A `PreToolUse` or `PermissionRequest` hook returned the decision.1005 * `"hook"`: A `PreToolUse` or `PermissionRequest` hook returned the decision.

1046 1047

1047#### Safety event1048#### Safety event

1048 1049

1049Logged when a check refuses a tool call or requires a permission prompt, except for [calls without a safety event](#calls-without-a-safety-event). Also logged when the [sandbox's network proxy](https://code.claude.com/docs/en/sandboxing.md#network-isolation) refuses a connection or request, and when a hook blocks a result. Requires Claude Code v2.1.307 or later.1050Claude Code has stopped sending `claude_code.safety_event`:

1051

1052* **v2.1.312 and later**: these versions don't send the event, and no setting turns it on

1053* **v2.1.307 through v2.1.311**: a session stops sending the event at its next feature-flag refresh. A session that doesn't [fetch feature flags](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching), such as on Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry, can keep sending it.

1054

1055To see refused tool calls, query [`tool_decision`](#tool-decision-event) events, which show that a call was refused but not always which check refused it.

1056

1057The event details here describe events from v2.1.307 through v2.1.311, where a safety event records [cases](#safety-event-categories) such as these:

1058

1059* A check refuses a tool call or requires a permission prompt, except for [calls without a safety event](#calls-without-a-safety-event)

1060* The [sandbox's network proxy](https://code.claude.com/docs/en/sandboxing.md#network-isolation) refuses a connection or request

1061* A hook blocks a result or the end of a turn

1050 1062

1051The event exports with the other events and has no separate setting. The event's own attributes hold no command text, file paths, host names, or MCP server and tool names. The record also carries the [standard attributes](#standard-attributes) every event has, which can include `workspace.host_paths` and the [repository attributes](#repository-attributes). To see the command or MCP tool behind an event, set `OTEL_LOG_TOOL_DETAILS=1` and read `tool_parameters` on the matching `tool_decision` event.1063The event exports with the other events and has no separate setting. The event's own attributes hold no command text, file paths, host names, or MCP server and tool names. The record also carries the [standard attributes](#standard-attributes) every event has, which can include `workspace.host_paths` and the [repository attributes](#repository-attributes). To see the command or MCP tool behind an event, set `OTEL_LOG_TOOL_DETAILS=1` and read `tool_parameters` on the matching `tool_decision` event.

1052 1064

1458 1470

1459Like every OTel event on this page, it goes only to the telemetry backend you configure. Requires Claude Code v2.1.227 or later.1471Like every OTel event on this page, it goes only to the telemetry backend you configure. Requires Claude Code v2.1.227 or later.

1460 1472

1461When Claude Code can't safely determine the retention period, it pauses the sweep and emits the event with `result` set to `"skipped"` and a `skip_reason`. When [managed settings](https://code.claude.com/docs/en/server-managed-settings.md) set `cleanupPeriodDays`, the managed value pins the retention period and the sweep runs even when a settings file in a lower-priority scope is broken or invalid. When `managed-settings.json` itself can't be read, Claude Code still pauses the sweep unless the [managed tier](https://code.claude.com/docs/en/managed-settings.md#how-claude-code-combines-managed-sources) supplies `cleanupPeriodDays` from elsewhere, such as server-managed settings or a `managed-settings.d/` drop-in beside the broken file. The deletion counter attributes are present only when `result` is `"complete"`.1473Read `result` to see whether the sweep ran:

1474

1475* `"complete"`: the sweep ran, and the event carries its counts

1476* `"skipped"`: Claude Code couldn't safely determine the retention period, so it paused the sweep and the event carries no counts. If `skip_reason` is `"settings_unknowable"` or `"settings_invalid_key_set"`, fix the settings error that `/status` reports on that machine so a later session can run the sweep

1477

1478When [managed settings](https://code.claude.com/docs/en/server-managed-settings.md) set `cleanupPeriodDays`, the managed value pins the retention period and the sweep runs even when a settings file in a lower-priority scope is broken or invalid.

1462 1479

1463**Event Name**: `claude_code.retention_sweep`1480**Event Name**: `claude_code.retention_sweep`

1464 1481

1469* `event.timestamp`: ISO 8601 timestamp1486* `event.timestamp`: ISO 8601 timestamp

1470* `event.sequence`: per-process counter for ordering events, described under [Event correlation attributes](#event-correlation-attributes)1487* `event.sequence`: per-process counter for ordering events, described under [Event correlation attributes](#event-correlation-attributes)

1471* `result`: `"complete"` when the sweep ran, `"skipped"` when Claude Code paused it1488* `result`: `"complete"` when the sweep ran, `"skipped"` when Claude Code paused it

1472* `period_days`: The `cleanupPeriodDays` value from merged settings, in days, or `30` when no source sets it. On skipped events, the value the sweep would have used, computed from the settings sources Claude Code could read1489* `period_days`: The retention period the sweep started with, in days: `cleanupPeriodDays` from merged settings, with any change from a [`settings.read` hook](https://code.claude.com/docs/en/plugins/mods/events#settings-read-hook) applied. `30` when that leaves the key unset. On skipped events, the value the sweep would have used, computed from the settings sources Claude Code could read

1473* `used_default`: `"true"` when no readable settings source sets `cleanupPeriodDays`, `"false"` otherwise. On complete events, `"true"` means the 30-day default applied1490* `used_default`: `"true"` when `period_days` fell back to `30`, `"false"` otherwise. On complete events, `"true"` means the 30-day default applied

1474* `skip_reason`: Why Claude Code paused the sweep. Present only when `result` is `"skipped"`:1491* `skip_reason`: Why Claude Code paused the sweep. Present only when `result` is `"skipped"`:

1475 * `"user_source_disabled"`: User settings are excluded, for example by the [`--setting-sources`](https://code.claude.com/docs/en/cli-reference#cli-flags) flag or the SDK's [`settingSources`](https://code.claude.com/docs/en/agent-sdk/typescript#options) option, and no enabled source provides `cleanupPeriodDays`1492 * `"user_source_disabled"`: User settings are excluded, for example by the [`--setting-sources`](https://code.claude.com/docs/en/cli-reference#cli-flags) flag or the SDK's [`settingSources`](https://code.claude.com/docs/en/agent-sdk/typescript#options) option, and no enabled source provides `cleanupPeriodDays`

1476 * `"settings_unknowable"`: A settings file couldn't be read or parsed, so `cleanupPeriodDays` or `desktopSessionCleanupPeriodDays` may be set to a value Claude Code can't see1493 * `"settings_unknowable"`: A settings file couldn't be read or parsed, so `cleanupPeriodDays` or `desktopSessionCleanupPeriodDays` may be set to a value Claude Code can't see

1549| Metric | Analysis Opportunity |1566| Metric | Analysis Opportunity |

1550| - | - |1567| - | - |

1551| `claude_code.token.usage` | Break down by token [`type`](#token-counter), user, team, model, `skill.name`, `plugin.name`, or `agent.name` |1568| `claude_code.token.usage` | Break down by token [`type`](#token-counter), user, team, model, `skill.name`, `plugin.name`, or `agent.name` |

1552| `claude_code.session.count` | Track adoption and engagement over time |

1553| `claude_code.lines_of_code.count` | Measure productivity by tracking code additions and removals, broken down by model |1569| `claude_code.lines_of_code.count` | Measure productivity by tracking code additions and removals, broken down by model |

1555 1571

1572To compare active users across surfaces, set `OTEL_METRICS_INCLUDE_ENTRYPOINT=true` to add [`app.entrypoint`](#standard-attributes) to metrics and events. Then count distinct `user.account_uuid` values per entrypoint on [`claude_code.user_prompt`](#user-prompt-event) events, or on `claude_code.token.usage` if you export only metrics. For example, use `cli` for interactive CLI sessions, and group `claude-desktop`, `claude-desktop-3p`, and `remote_desktop` for the Claude Desktop Code tab.

1573

1574`user.account_uuid` doesn't identify people in Claude Tag channel sessions and is missing from sessions with no Claude account: see [Attribute actions to users](#attribute-actions-to-users). When one person starts many sessions, or a session receives no prompt, [`claude_code.session.count`](#session-counter) goes up without adding an active user.

1575

1556### Cost monitoring1576### Cost monitoring

1557 1577

1558The `claude_code.cost.usage` metric helps with:1578The `claude_code.cost.usage` metric helps with:

1655 1675

1656### Map security questions to events1676### Map security questions to events

1657 1677

1678Rows for `safety_event` apply only to a session on v2.1.307 through v2.1.311 that [still sends the event](#safety-event).

1679

1658When building detection rules, look up the signal you want to monitor and query your backend for the corresponding event and attributes:1680When building detection rules, look up the signal you want to monitor and query your backend for the corresponding event and attributes:

1659 1681

1664| Auto mode classifier allowed or blocked a tool call, or Claude Code denied the call without a classifier verdict | [`tool_decision`](#tool-decision-event) where `classifier_verdict` is present. For a denial without a verdict, `classifier_verdict` is `"no_verdict"` or `"unavailable"` | `classifier_verdict`, `permission_mode`, `tool_name`; `classifier_category` when you set `OTEL_LOG_TOOL_DETAILS=1` |1686| Auto mode classifier allowed or blocked a tool call, or Claude Code denied the call without a classifier verdict | [`tool_decision`](#tool-decision-event) where `classifier_verdict` is present. For a denial without a verdict, `classifier_verdict` is `"no_verdict"` or `"unavailable"` | `classifier_verdict`, `permission_mode`, `tool_name`; `classifier_category` when you set `OTEL_LOG_TOOL_DETAILS=1` |

1668| Which tool call a hook refused, and which result or turn end a hook blocked | [`safety_event`](#safety-event) where `category` is `"hook"` and `decision` is `"reject"` for a refused call, or `category` is `"hook_review"` for a blocked result or turn end | `category`, `decision`, `hook_event`; `tool_use_id` for a tool call |1690| Tool call a hook refused | [`tool_decision`](#tool-decision-event) where `decision` is `"reject"` and `source` is `"hook"` | `decision`, `source`, `tool_use_id` |

1691| Which result or turn end a hook blocked | [`safety_event`](#safety-event) where `category` is `"hook_review"` | `category`, `hook_event`; `tool_use_id` for a tool call |

1669| Sandbox's network proxy refused a connection or request from a Bash or PowerShell command | [`safety_event`](#safety-event) where `sandbox_violation_count` is present and isn't `"0"` | `sandbox_violation_count`, `category`, `sandbox_enabled`, `tool_use_id` |1692| Sandbox's network proxy refused a connection or request from a Bash or PowerShell command | [`safety_event`](#safety-event) where `sandbox_violation_count` is present and isn't `"0"` | `sandbox_violation_count`, `category`, `sandbox_enabled`, `tool_use_id` |

1783## Security and privacy1806## Security and privacy

1784 1807

1785* OpenTelemetry export to your backend is opt-in and requires explicit configuration. For Anthropic's separate operational telemetry and how to disable it, see [Data usage](https://code.claude.com/docs/en/data-usage.md#telemetry-services)1808* OpenTelemetry export to your backend is opt-in and requires explicit configuration. For Anthropic's separate operational telemetry and how to disable it, see [Data usage](https://code.claude.com/docs/en/data-usage.md#telemetry-services)

1786* Raw file contents and code snippets are not included in metrics or events. Trace spans are a separate data path: see the `OTEL_LOG_TOOL_CONTENT` bullet below1809* By default, raw file contents and code snippets aren't included in metrics or events. If you set a variable such as `OTEL_LOG_TOOL_DETAILS` or `OTEL_LOG_RAW_API_BODIES`, events can include them. Trace spans are a separate data path: see the `OTEL_LOG_TOOL_CONTENT` bullet below

1787* When authenticated via OAuth, `user.email` is included in telemetry attributes, sent only to the OTel endpoint you configure, never to Anthropic. If this is a concern for your organization, work with your telemetry backend to filter or redact this field1810* When authenticated via OAuth, `user.email` is included in telemetry attributes, sent only to the OTel endpoint you configure, never to Anthropic. If this is a concern for your organization, work with your telemetry backend to filter or redact this field

1788* User prompt content is not collected by default. Only prompt length is recorded. To include prompt content, set `OTEL_LOG_USER_PROMPTS=1`. When enabled:1811* User prompt content is not collected by default. Only prompt length is recorded. To include prompt content, set `OTEL_LOG_USER_PROMPTS=1`. When enabled:

1789 * `user_prompt` events carry the prompt text in two attributes, `prompt` and [`prompt_text`](#user-prompt-event). If you drop or mask the event's prompt text by attribute name in your collector, name both attributes in the rule1812 * `user_prompt` events carry the prompt text in two attributes, `prompt` and [`prompt_text`](#user-prompt-event). If you drop or mask the event's prompt text by attribute name in your collector, name both attributes in the rule

permission-modes.md +5 −3

Details

25 25

26The mode that reviews every action is named **Manual** in the CLI, in `claude --help`, in the VS Code and JetBrains extensions, and in the desktop app. Its config value is `default`, which is what hooks and SDK integrations use. The CLI accepts `manual` as an alias wherever you type the value, for example `claude --permission-mode manual` or `"defaultMode": "manual"`.26The mode that reviews every action is named **Manual** in the CLI, in `claude --help`, in the VS Code and JetBrains extensions, and in the desktop app. Its config value is `default`, which is what hooks and SDK integrations use. The CLI accepts `manual` as an alias wherever you type the value, for example `claude --permission-mode manual` or `"defaultMode": "manual"`.

27 27

28Writes to [protected paths](#protected-paths) are never auto-approved except in `bypassPermissions` mode and in plan-mode sessions where bypass permissions are available, meaning interactive terminal sessions started in a way that [puts `bypassPermissions` in the mode cycle](#switch-permission-modes).28Each mode has its own rule for writes to [protected paths](#protected-paths).

29 29

30Modes set the baseline. Layer [permission rules](https://code.claude.com/docs/en/permissions.md#manage-permissions) on top to pre-approve or block specific tools. Deny rules block in every mode, including `bypassPermissions`. Deny and ask rules don't apply to [`EndConversation`](https://code.claude.com/docs/en/tools-reference#endconversation-tool-behavior) as long as Claude still has at least one other tool it can call. Allow rules have no effect in `bypassPermissions`.30Modes set the baseline. Layer [permission rules](https://code.claude.com/docs/en/permissions.md#manage-permissions) on top to pre-approve or block specific tools. Deny rules block in every mode, including `bypassPermissions`. Deny and ask rules don't apply to [`EndConversation`](https://code.claude.com/docs/en/tools-reference#endconversation-tool-behavior) as long as Claude still has at least one other tool it can call. Allow rules have no effect in `bypassPermissions`.

31 31

686* **If you accept**: Claude Code sets `skipDangerousModePermissionPrompt` to `true` in `~/.claude/settings.json`, so later sessions skip the dialog. To see the dialog again, remove the key from that file or set it to `false`. The [`skipDangerousModePermissionPrompt` reference](https://code.claude.com/docs/en/settings-reference#skipdangerousmodepermissionprompt) lists the other settings files where you or your organization can set it.686* **If you accept**: Claude Code sets `skipDangerousModePermissionPrompt` to `true` in `~/.claude/settings.json`, so later sessions skip the dialog. To see the dialog again, remove the key from that file or set it to `false`. The [`skipDangerousModePermissionPrompt` reference](https://code.claude.com/docs/en/settings-reference#skipdangerousmodepermissionprompt) lists the other settings files where you or your organization can set it.

687* **If you decline**: Claude Code exits.687* **If you decline**: Claude Code exits.

688 688

689If you pass [`--setting-sources`](https://code.claude.com/docs/en/cli-reference#cli-flags) without `user`, the dialog can appear again although you accepted it earlier. To skip it, add `user`, as in `--setting-sources user,project`.

690

689In [non-interactive mode](https://code.claude.com/docs/en/headless.md) no dialog is shown.691In [non-interactive mode](https://code.claude.com/docs/en/headless.md) no dialog is shown.

690 692

691A [background session](https://code.claude.com/docs/en/agent-view.md) honors your acceptance when it's recorded in user or managed settings:693A [background session](https://code.claude.com/docs/en/agent-view.md) honors your acceptance when it's recorded in user or managed settings:

728 730

729## Protected paths731## Protected paths

730 732

731Writes to a small set of paths are never auto-approved, except in `bypassPermissions` mode and in interactive terminal sessions in plan mode with [bypass permissions](#skip-all-checks-with-bypasspermissions-mode) available. This prevents accidental corruption of repository state and Claude's own configuration.733A small set of paths holds repository state and Claude's own configuration, so each mode has its own rule for writes to them:

732 734

733| Mode | Protected-path writes |735| Mode | Protected-path writes |

734| :- | :- |736| :- | :- |

736| `plan` | Allowed in interactive terminal sessions with [bypass permissions](#skip-all-checks-with-bypasspermissions-mode) available. Otherwise, routed to the classifier when [auto mode](#eliminate-prompts-with-auto-mode) is available during planning, and prompted when it isn't |738| `plan` | Allowed in interactive terminal sessions with [bypass permissions](#skip-all-checks-with-bypasspermissions-mode) available. Otherwise, routed to the classifier when [auto mode](#eliminate-prompts-with-auto-mode) is available during planning, and prompted when it isn't |

740 742

permissions.md +2 −0

Details

578* `mcp__puppeteer__*` uses wildcard syntax and also matches all tools from the `puppeteer` server578* `mcp__puppeteer__*` uses wildcard syntax and also matches all tools from the `puppeteer` server

579* `mcp__puppeteer__puppeteer_navigate` matches the `puppeteer_navigate` tool provided by the `puppeteer` server579* `mcp__puppeteer__puppeteer_navigate` matches the `puppeteer_navigate` tool provided by the `puppeteer` server

580 580

581Write allow rules for MCP tools without a [specifier](#use-specifiers-for-fine-grained-control), which a [permission update](https://code.claude.com/docs/en/hooks.md#permission-update-entries) calls `ruleContent`. If you add one to allow only some of a tool's calls, the rule doesn't match any call. To block some calls instead, see [Match by input parameter](#match-by-input-parameter).

582

581For `<server>`, write the server's name the way it appears in that server's tool names. These examples show the rule to write for a name with special characters, a server from a plugin, and a name that contains `__` or ends in `_`:583For `<server>`, write the server's name the way it appears in that server's tool names. These examples show the rule to write for a name with special characters, a server from a plugin, and a name that contains `__` or ends in `_`:

582 584

583* **Names with characters such as `.` or spaces**: those characters become `_`, so for a server you configured as `my.server`, write `mcp__my_server__*`585* **Names with characters such as `.` or spaces**: those characters become `_`, so for a server you configured as `my.server`, write `mcp__my_server__*`

plugins/cli-reference.md +2 −2

Details

94* **stdin or stdout isn't a TTY, and you pass neither `-y` nor `--accept-command`**: the install is refused. The output says the command was only displayed, and the exit code is `1`94* **stdin or stdout isn't a TTY, and you pass neither `-y` nor `--accept-command`**: the install is refused. The output says the command was only displayed, and the exit code is `1`

95* **Claude runs the command through its Bash tool**: `-y` is ignored. Run the command from your own terminal instead95* **Claude runs the command through its Bash tool**: `-y` is ignored. Run the command from your own terminal instead

96 96

~~97Install a plugin for everyone who clones the project:~~97To share a plugin with everyone who clones the project, run `claude plugin install` with `--scope project` and commit `.claude/settings.json`. Then have each person [add the marketplace](https://code.claude.com/docs/en/plugins/install.md#add-a-marketplace) and [run the same command](https://code.claude.com/docs/en/plugins/loading.md#enabled-in-project-settings-but-not-installed) in their own clone:

98 98

99```bash theme={null}99```bash theme={null}

100claude plugin install formatter@my-marketplace --scope project100claude plugin install formatter@my-marketplace --scope project

333| `notes` | array of strings | Warnings that aren't load errors, such as authoring issues or [packages that aren't installed](https://code.claude.com/docs/en/plugins/loading.md#when-the-dependency-install-fails-or-is-skipped) |333| `notes` | array of strings | Warnings that aren't load errors, such as authoring issues or [packages that aren't installed](https://code.claude.com/docs/en/plugins/loading.md#when-the-dependency-install-fails-or-is-skipped) |

334| `errorDetails` | array of objects | One object per `errors` entry, giving its diagnostic `type` and the names it refers to, such as the plugin, marketplace, server, or file. Requires Claude Code v2.1.268 or later |334| `errorDetails` | array of objects | One object per `errors` entry, giving its diagnostic `type` and the names it refers to, such as the plugin, marketplace, server, or file. Requires Claude Code v2.1.268 or later |

336| `hasUserConfig` | boolean | Present and `true` when the plugin loaded and its manifest declares [`userConfig` options](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration). Absent for a plugin that failed to load, whatever its manifest declares. Saved values are never included. Requires Claude Code v2.1.285 or later |336| `hasUserConfig` | boolean | Present and `true` when the plugin loaded and its manifest declares [`userConfig` options](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration). Absent for a plugin that failed to load, whatever its manifest declares. Requires Claude Code v2.1.285 or later |

337| `projectEnabled` | boolean | Whether the project's shared `.claude/settings.json` turns the plugin on. Marketplace installs only. Requires Claude Code v2.1.285 or later |337| `projectEnabled` | boolean | Whether the project's shared `.claude/settings.json` turns the plugin on. Marketplace installs only. Requires Claude Code v2.1.285 or later |

338| `dataDirSize` | object | With `--data-size`, the size of the plugin's [saved data directory](#what-an-uninstall-deletes-and-keeps) as `bytes` and `human`; absent when the directory is missing or empty. Marketplace installs only. Requires Claude Code v2.1.285 or later |338| `dataDirSize` | object | With `--data-size`, the size of the plugin's [saved data directory](#what-an-uninstall-deletes-and-keeps) as `bytes` and `human`; absent when the directory is missing or empty. Marketplace installs only. Requires Claude Code v2.1.285 or later |

339| `dataDirUnreadable` | boolean | With `--data-size`, `true` when the saved data directory exists but couldn't be measured. Marketplace installs only. Requires Claude Code v2.1.285 or later |339| `dataDirUnreadable` | boolean | With `--data-size`, `true` when the saved data directory exists but couldn't be measured. Marketplace installs only. Requires Claude Code v2.1.285 or later |

plugins/create.md +7 −1

Details

169 169

170### Load a plugin for one session170### Load a plugin for one session

171 171

172You can load a plugin for a single session in three ways: from a directory or `.zip` archive on disk with `--plugin-dir`, from a URL with `--plugin-url`, or from an environment variable when you can't add a flag. Each plugin loads for that session only, and nothing is written to your settings for it. When you edit the plugin's files during the session, run `/reload-plugins` to load the changes.172You can load a plugin for a single session in three ways:

173

174* From a directory or `.zip` archive on disk with `--plugin-dir`

175* From a URL with `--plugin-url`

176* From an environment variable when you can't add a flag

177

178When you edit the plugin's files during the session, run `/reload-plugins` to load the changes.

173 179

174#### Load a plugin from a directory or `.zip`180#### Load a plugin from a directory or `.zip`

175 181

plugins/host-marketplace.md +1 −1

Details

123 123

124These entry sources need no git account:124These entry sources need no git account:

125 125

126* **`archive`**: a zip downloaded over HTTPS. Users need neither `git` nor an account, only network access to the URL. Requires Claude Code v2.1.224 or later. Pin each archive with `sha256` so Claude Code refuses a changed download. To send credentials with the download, see [Authenticate archive downloads](#authenticate-archive-downloads).126* **`archive`**: a zip downloaded over HTTPS. Users need neither `git` nor an account, only network access to the URL. Pin each archive with `sha256` so Claude Code refuses a changed download. To send credentials with the download, see [Authenticate archive downloads](#authenticate-archive-downloads).

127* **A public git repository**: Claude Code clones a public `url` or `git-subdir` source over HTTPS without credentials when the entry gives an `https://` URL. For a `github` source, or a `git-subdir` source written as `owner/repo`, tell users without a GitHub SSH key to set `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`.127* **A public git repository**: Claude Code clones a public `url` or `git-subdir` source over HTTPS without credentials when the entry gives an `https://` URL. For a `github` source, or a `git-subdir` source written as `owner/repo`, tell users without a GitHub SSH key to set `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`.

128 128

129Keep `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1` in your instructions even if `claude plugin install` succeeds without it from the shell on a machine with no SSH key. For a `github` source, that command can fall back to HTTPS on its own, printing `SSH not configured, cloning via HTTPS`. Installs from `/plugin` inside a session and plugin updates don't fall back, so without the variable they fail for users who have no GitHub SSH key.129Keep `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1` in your instructions even if `claude plugin install` succeeds without it from the shell on a machine with no SSH key. For a `github` source, that command can fall back to HTTPS on its own, printing `SSH not configured, cloning via HTTPS`. Installs from `/plugin` inside a session and plugin updates don't fall back, so without the variable they fail for users who have no GitHub SSH key.

plugins/install.md +1 −1

Details

132A plugin's install scope decides who gets the plugin and which settings file records it as enabled:132A plugin's install scope decides who gets the plugin and which settings file records it as enabled:

133 133

134* **User scope**: the plugin is enabled for you in every project on this machine. The entry goes in `enabledPlugins` in `~/.claude/settings.json`.134* **User scope**: the plugin is enabled for you in every project on this machine. The entry goes in `enabledPlugins` in `~/.claude/settings.json`.

135* **Project scope**: the plugin is enabled for everyone who works in this repository. The entry goes in `.claude/settings.json`, which you commit. Committing that entry turns the plugin on for your collaborators but doesn't download it to their machines, so each collaborator also runs `claude plugin install <name>@<marketplace> --scope project` once; see [Enabled in project settings but not installed](https://code.claude.com/docs/en/plugins/loading.md#enabled-in-project-settings-but-not-installed).135* **Project scope**: the plugin is enabled for everyone who works in this repository. The entry goes in `.claude/settings.json`, which you commit. Committing that entry turns the plugin on for your collaborators but doesn't download it to their machines. Each collaborator also runs `claude plugin install <name>@<marketplace> --scope project` once per clone; see [Enabled in project settings but not installed](https://code.claude.com/docs/en/plugins/loading.md#enabled-in-project-settings-but-not-installed).

136* **Local scope**: the plugin is enabled for you in this repository only. The entry goes in `.claude/settings.local.json`.136* **Local scope**: the plugin is enabled for you in this repository only. The entry goes in `.claude/settings.local.json`.

137 137

138Some plugins are set by their author to start turned off, through the [`defaultEnabled`](https://code.claude.com/docs/en/plugins/manifest-reference#defaultenabled) field. Such a plugin is installed but stays off until you turn it on with `claude plugin enable <name>` in your shell, or from the **Installed** tab of `/plugin` in a session.138Some plugins are set by their author to start turned off, through the [`defaultEnabled`](https://code.claude.com/docs/en/plugins/manifest-reference#defaultenabled) field. Such a plugin is installed but stays off until you turn it on with `claude plugin enable <name>` in your shell, or from the **Installed** tab of `/plugin` in a session.

plugins/loading.md +33 −3

Details

173 173

174To opt out of a project-enabled plugin on your machine, set the id to `false` in `.claude/settings.local.json`, which has higher precedence than the project file.174To opt out of a project-enabled plugin on your machine, set the id to `false` in `.claude/settings.local.json`, which has higher precedence than the project file.

175 175

176### Enabled in an `--add-dir` directory but not loaded

177

178Claude Code reads an `enabledPlugins` entry of `true` in one of the added directory's files only when that file's setting sources are on:

179

180* **`.claude/settings.json`**: `project`

181* **`.claude/settings.local.json`**: `project` and `local`

182

183Check which setting sources the session loads. You set them with [`--setting-sources`](https://code.claude.com/docs/en/cli-reference#cli-flags). In the CLI, `user`, `project`, and `local` are all on by default.

184

185For example, if you run `claude --setting-sources user --add-dir ./shared` in your shell, Claude Code reads neither file in `./shared`. Pass the flag for the file that holds the `true`:

186

187* **`settings.json`**: `--setting-sources user,project`

188* **`settings.local.json`**: `--setting-sources user,project,local`

189

176### Enabled in project settings but not installed190### Enabled in project settings but not installed

177 191

178When a plugin's only `true` is in the project's `.claude/settings.json`, Claude Code doesn't fetch it onto a machine where it isn't installed, unless its marketplace entry has a [relative-path source](https://code.claude.com/docs/en/plugins/marketplace-reference.md#plugin-sources) or a [seed directory](https://code.claude.com/docs/en/plugins/org.md#seed-containers-and-ci) already holds it. Instead, the `/plugin` **Errors** tab shows `Plugin "<name>" is enabled in project settings but isn't installed here`.192By default, a plugin enabled only in your project's `.claude/settings.json` doesn't load at session start until you install it on your machine. With the marketplace on your machine, the `/plugin` **Errors** tab shows [`Plugin "<name>" is enabled in project settings but isn't installed here`](https://code.claude.com/docs/en/plugins/troubleshooting#plugin-is-enabled-in-project-settings-but-isnt-installed-here) or [`Plugin "<name>" not cached at <path>`](https://code.claude.com/docs/en/plugins/troubleshooting#plugin-not-cached-at).

193

194> [!NOTE]

195>

196> If the tab shows neither message, [add the marketplace](https://code.claude.com/docs/en/plugins/install.md#add-a-marketplace) before you install. Find its source in the `extraKnownMarketplaces` setting of `.claude/settings.json`, or ask your maintainer.

197

198To install, run this in a shell from the project, using the plugin's key in `enabledPlugins`:

199

200```shell theme={null}

201claude plugin install <name>@<marketplace> --scope project

202```

203

204To load the plugin, run `/reload-plugins` in your session or start a new session. Repeat the install in each of your clones, or use `--scope user` to cover all your projects.

205

206You can load a plugin without an install in these cases:

179 207

180A relative-path plugin needs no install record because it loads from the marketplace itself.208* **In a [seed directory](https://code.claude.com/docs/en/plugins/org.md#seed-containers-and-ci)**: you have nothing to run

209* **Listed by a [relative path](https://code.claude.com/docs/en/plugins/marketplace-reference.md#plugin-sources) in a marketplace you added from a local path**: you have nothing to run, because the plugin loads at session start

210* **Listed by a relative path, such as `./plugins/formatter`, in the `marketplace.json` of a git marketplace you've added**: run `/reload-plugins` to load it for the current session only. To load it for one [non-interactive `-p` run](https://code.claude.com/docs/en/headless), set [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1`](https://code.claude.com/docs/en/env-vars).

181 211

182Claude Code fetches a plugin with an external source only when one of these sources sets it to `true`:212Claude Code fetches a plugin with an external source only when one of these sources sets the plugin to `true`:

183 213

184* Your user settings214* Your user settings

185* A `.claude/settings.local.json` that git doesn't track215* A `.claude/settings.local.json` that git doesn't track

plugins/manifest-reference.md +3 −3

Details

189 189

190### `metadata`190### `metadata`

191 191

192A free-form object for your own data, such as catalog or entitlement fields. Claude Code doesn't read it. Requires Claude Code v2.1.222 or later.192A free-form object for your own data, such as catalog or entitlement fields. Claude Code doesn't read it.

193 193

194### Directory listing fields194### Directory listing fields

195 195

394 394

395Every component path in a manifest is relative to the plugin root and must start with `./`. A path such as `commands/foo.md` fails validation. `skills` and `mcpServers` each accept one form outside that rule:395Every component path in a manifest is relative to the plugin root and must start with `./`. A path such as `commands/foo.md` fails validation. `skills` and `mcpServers` each accept one form outside that rule:

396 396

397* **`skills`**: also accepts `"."`. Both `"."` and `"./"` denote the plugin root. Before v2.1.221, `"."` failed manifest validation, so use `"./"` when the plugin must load on earlier versions397* **`skills`**: also accepts `"."`. Both `"."` and `"./"` denote the plugin root

398* **`mcpServers`**: also accepts an `https://` bundle URL398* **`mcpServers`**: also accepts an `https://` bundle URL

399 399

400`experimental.evals` isn't a component path, so the rules in this section don't cover it, and `claude plugin eval` checks the value when it runs instead. It names a directory below the plugin root, such as `"quality/evals"`, with or without the `./` prefix. With an array, only the first entry is used. For what the value accepts and what happens with an unusable one, see [Use a different eval directory](https://code.claude.com/docs/en/plugin-evals.md#use-a-different-eval-directory).400`experimental.evals` isn't a component path, so the rules in this section don't cover it, and `claude plugin eval` checks the value when it runs instead. It names a directory below the plugin root, such as `"quality/evals"`, with or without the `./` prefix. With an array, only the first entry is used. For what the value accepts and what happens with an unusable one, see [Use a different eval directory](https://code.claude.com/docs/en/plugin-evals.md#use-a-different-eval-directory).

403 403

404Every component path must resolve inside the plugin root and must exist. `claude plugin validate` checks the paths under every component key:404Every component path must resolve inside the plugin root and must exist. `claude plugin validate` checks the paths under every component key:

405 405

406* **Containment**: a path that resolves outside the plugin root doesn't load, and the `/plugin` **Errors** tab shows `<component> path escapes plugin directory: <path>`. A path containing `..` is the usual case, and `claude plugin validate` reports the error `Path contains ".." which could be a path traversal attempt`406* **Containment**: a path that resolves outside the plugin root doesn't load, and the `/plugin` **Errors** tab shows `<component> path escapes plugin directory: <path>`. A path containing `..` is the usual case, and `claude plugin validate` reports the error `Path contains ".." which could be a path traversal attempt`. For an `mcpServers` or `lspServers` file, a [`path not read`](https://code.claude.com/docs/en/errors#server-file-path-not-read) message means the path is absolute or contains `..`

407* **Existence**: a path that doesn't exist doesn't load, and the `/plugin` **Errors** tab shows `<component> path not found: <path>`. `claude plugin validate` reports the error `Path not found`407* **Existence**: a path that doesn't exist doesn't load, and the `/plugin` **Errors** tab shows `<component> path not found: <path>`. `claude plugin validate` reports the error `Path not found`

408 408

409For `outputStyles`, `lspServers`, `monitors`, and `themes` paths, the `claude plugin validate` check requires Claude Code v2.1.283 or later.409For `outputStyles`, `lspServers`, `monitors`, and `themes` paths, the `claude plugin validate` check requires Claude Code v2.1.283 or later.

plugins/marketplace-reference.md +2 −2

Details

94| `dependencies` | array | Plugins that must be enabled for this one to work. Each item is `"name"`, `"name@marketplace"`, or an object. See [Plugin dependencies](https://code.claude.com/docs/en/plugins/dependencies.md) |94| `dependencies` | array | Plugins that must be enabled for this one to work. Each item is `"name"`, `"name@marketplace"`, or an object. See [Plugin dependencies](https://code.claude.com/docs/en/plugins/dependencies.md) |

95| `defaultEnabled` | boolean | Default `true`. Whether the plugin starts enabled when the user hasn't set it in [`enabledPlugins`](https://code.claude.com/docs/en/settings-reference#enabledplugins). The entry value takes precedence over `plugin.json` |95| `defaultEnabled` | boolean | Default `true`. Whether the plugin starts enabled when the user hasn't set it in [`enabledPlugins`](https://code.claude.com/docs/en/settings-reference#enabledplugins). The entry value takes precedence over `plugin.json` |

98| `headers` | object | HTTP headers Claude Code sends when it downloads this entry's [archive](#archive-plugin-source). A header set here replaces a header of the same name from the marketplace source's [`headers`](#fields-by-type). Requires Claude Code v2.1.238 or later |98| `headers` | object | HTTP headers Claude Code sends when it downloads this entry's [archive](#archive-plugin-source). A header set here replaces a header of the same name from the marketplace source's [`headers`](#fields-by-type). Requires Claude Code v2.1.238 or later |

99| `headersHelper` | string | Command that prints this entry's archive-download headers as one JSON object, for a credential that expires. The entry must also set [`"strict": false`](#strict-mode). Requires Claude Code v2.1.238 or later. See [Authenticate archive downloads](https://code.claude.com/docs/en/plugins/host-marketplace.md#authenticate-archive-downloads) |99| `headersHelper` | string | Command that prints this entry's archive-download headers as one JSON object, for a credential that expires. The entry must also set [`"strict": false`](#strict-mode). Requires Claude Code v2.1.238 or later. See [Authenticate archive downloads](https://code.claude.com/docs/en/plugins/host-marketplace.md#authenticate-archive-downloads) |

100 100

142| `url` | `url`, `ref`, `sha` | Any git repository by URL |142| `url` | `url`, `ref`, `sha` | Any git repository by URL |

144| `npm` | `package`, `version`, `registry` | npm registry package or tarball link, fetched with your npm client and unpacked without running install scripts |144| `npm` | `package`, `version`, `registry` | npm registry package or tarball link, fetched with your npm client and unpacked without running install scripts |

147 147

148The names `url` and `github` are also [marketplace source](#marketplace-sources) types, where `url` means a direct link to a `marketplace.json` file rather than a git repository. `git` exists only as a marketplace source, and `npm` exists as both. `git-subdir`, `archive`, and `command` exist only as plugin sources.148The names `url` and `github` are also [marketplace source](#marketplace-sources) types, where `url` means a direct link to a `marketplace.json` file rather than a git repository. `git` exists only as a marketplace source, and `npm` exists as both. `git-subdir`, `archive`, and `command` exist only as plugin sources.

plugins/mods/create.md +5 −5

Details

21 21

22Describe the mod you want in an interactive Claude Code session, and Claude writes it. Claude works from a built-in [skill](https://code.claude.com/docs/en/skills.md) named `plugin-authoring`, which tells it where to write the mod, which events and methods your version has, and how the mod gets loaded. Claude can load the skill when you ask for a mod, or you can load it yourself by running `/plugin-authoring` at the Claude Code prompt.22Describe the mod you want in an interactive Claude Code session, and Claude writes it. Claude works from a built-in [skill](https://code.claude.com/docs/en/skills.md) named `plugin-authoring`, which tells it where to write the mod, which events and methods your version has, and how the mod gets loaded. Claude can load the skill when you ask for a mod, or you can load it yourself by running `/plugin-authoring` at the Claude Code prompt.

23 23

~~24The mod runs once you approve it, except in [sessions where a mod Claude writes can't load](#sessions-that-skip-the-approval).~~24In the `auto` and `bypassPermissions` [permission modes](https://code.claude.com/docs/en/permission-modes.md), the mod can run when the turn ends. Otherwise, it runs once you approve it, except in [sessions where a mod Claude writes can't load](#sessions-that-skip-the-approval).

25 25

26**1. Describe the mod**26**1. Describe the mod**

27 27

33 33

34**2. Approve the mod**34**2. Approve the mod**

35 35

~~36When Claude saves the first file, Claude Code asks whether to enable hot reloading for the session. Hot reloading runs the mods Claude writes in this session and picks up each later change.~~36When Claude saves the first file, Claude Code asks whether to enable hot reloading for the session. Hot reloading runs the mods Claude writes in this session and picks up each later change. If no question appears, skip this step.

37 37

38Choose one of these answers:38Choose one of these answers:

39 39

40* **Enable for this session**: the mods in the session's mods folder load when the turn ends, and reload at the end of each turn that changes them. Your answer lasts for the session, including after you resume it.40* **Turn them on**: the mods in the session's mods folder load when the turn ends, and reload at the end of each turn that changes them. Your answer lasts for the session, including after you resume it.

41* **Not now**: nothing loads for now. The files stay where Claude wrote them, and the mods load the next time that session starts. To keep a mod from ever loading, delete its directory.41* **Not now**: nothing loads for now. The files stay where Claude wrote them, and the mods load the next time that session starts. To keep a mod from ever loading, delete its directory.

42 42

43**3. Check that the mod loaded**43**3. Check that the mod loaded**

59 59

60### Sessions where a mod Claude writes can't load60### Sessions where a mod Claude writes can't load

61 61

~~62A mod Claude writes loads only after you approve it, in a trusted workspace where mods are allowed to run. In these sessions it doesn't load:~~62A mod Claude writes loads in a trusted workspace where mods are allowed to run, after you approve it in the modes that ask. In these sessions it doesn't load:

63 63

~~64* **Nobody is there to approve**: the session can't show you a prompt, as in a `claude -p` run or [`dontAsk` mode](https://code.claude.com/docs/en/permission-modes)~~64* **Nobody is there to approve**: the session can't show you a prompt, as in a `claude -p` run outside `auto` and `bypassPermissions` modes, or [`dontAsk` mode](https://code.claude.com/docs/en/permission-modes)

65* **The workspace isn't trusted**: you haven't accepted the trust prompt for the directory65* **The workspace isn't trusted**: you haven't accepted the trust prompt for the directory

66* **Mods are disabled**: you started with `--safe-mode` or `--bare`, you set `disableAllHooks`, or your organization's [managed settings block it](https://code.claude.com/docs/en/plugins/mods/admin.md#choose-how-much-to-allow)66* **Mods are disabled**: you started with `--safe-mode` or `--bare`, you set `disableAllHooks`, or your organization's [managed settings block it](https://code.claude.com/docs/en/plugins/mods/admin.md#choose-how-much-to-allow)

67 67

plugins/mods/reference.md +6 −7

Details

39| `next.origin` | `{ plugin, tier }` of whoever fired the event. Claude Code itself is `{ plugin: 'engine', tier: 'core' }`. A mod's `tier` is its priority group in the [order mods run in](https://code.claude.com/docs/en/plugins/mods/events.md#the-order-mods-run-in): `prepend`, `user`, `append`, or `builtin`. |39| `next.origin` | `{ plugin, tier }` of whoever fired the event. Claude Code itself is `{ plugin: 'engine', tier: 'core' }`. A mod's `tier` is its priority group in the [order mods run in](https://code.claude.com/docs/en/plugins/mods/events.md#the-order-mods-run-in): `prepend`, `user`, `append`, or `builtin`. |

40| `next.budget` | The hook's time limit in milliseconds: `next.budget.ms` is the whole limit, and `next.budget.remainingMs` is what's left now |40| `next.budget` | The hook's time limit in milliseconds: `next.budget.ms` is the whole limit, and `next.budget.remainingMs` is what's left now |

41| `next.to(e, tier)` | Skips to a later tier, which is `append`, `builtin`, or `core`. `next.to(e, 'append')` skips the mods a user installed. Only a mod in `prependPlugins` or `appendPlugins` can call it. |41| `next.to(e, tier)` | Skips to a later tier, which is `append`, `builtin`, or `core`. `next.to(e, 'append')` skips the mods a user installed. Only a mod in `prependPlugins` or `appendPlugins` can call it. |

42| `next.error` | In a `.catch` handler only. `kind` is `throw` or `timeout` when the hook failed, and `message` is the error's text. `kind` is `re-entry` when the hook was skipped because the event came from inside a mods API call by that hook or by your mod's code outside its hooks. `re-entry` requires Claude Code v2.1.292 or later. |42| `next.error` | In a `.catch` handler only. `kind` is `throw` or `timeout`, and `message` is the error's text. |

43| `next.error.cause` | Set only when `kind` is `re-entry`. `rewritten` if a `tool.call` or [`PreToolUse`](https://code.claude.com/docs/en/hooks#pretooluse) hook changed the mods API call the event came from, or an `agent.spawn` hook changed an agent started by that call. `lent` when a method another mod adds to the mods API fired that event, unless `rewritten` also applies. `lent` requires Claude Code v2.1.292 or later and `rewritten` v2.1.300 or later. |

44| `next.called` | In a `.catch` handler only. `true` when the hook had called `next`. |43| `next.called` | In a `.catch` handler only. `true` when the hook had called `next`. |

45 44

46## Events45## Events

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

266 265

plugins/mods/troubleshoot.md +1 −1

Details

14 14

15When a module doesn't load, a hook is skipped, or another mod refuses yours, Claude Code writes one line that names your mod. Where you read that line depends on the session:15When a module doesn't load, a hook is skipped, or another mod refuses yours, Claude Code writes one line that names your mod. Where you read that line depends on the session:

16 16

17* **A session that hot-reloads a plugin directory**: a dim line in the transcript. That's an interactive session you started with `--plugin-dir`, or one where you [enabled hot reloading](https://code.claude.com/docs/en/plugins/mods/create.md#ask-claude-for-a-mod) for mods Claude wrote.17* **A session that hot-reloads a plugin directory**: a dim line in the transcript. That's an interactive session you started with `--plugin-dir`, or one where [hot reloading is on](https://code.claude.com/docs/en/plugins/mods/create.md#ask-claude-for-a-mod) for mods Claude wrote.

18* **Any other interactive session, such as one that runs a mod you installed from a marketplace**: the [debug log](#read-the-debug-log) only. To get one, start the session with `claude --debug`.18* **Any other interactive session, such as one that runs a mod you installed from a marketplace**: the [debug log](#read-the-debug-log) only. To get one, start the session with `claude --debug`.

19* **A `claude -p` run with `--plugin-dir`**: stderr, in the default text output format. A refusal by another mod goes to the debug log only.19* **A `claude -p` run with `--plugin-dir`**: stderr, in the default text output format. A refusal by another mod goes to the debug log only.

20 20

plugins/org.md +2 −2

Details

89* **Interactive sessions**: Claude Code registers the marketplace only after the contributor accepts the [workspace trust dialog](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder) for that folder.89* **Interactive sessions**: Claude Code registers the marketplace only after the contributor accepts the [workspace trust dialog](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder) for that folder.

90* **[Non-interactive `-p` runs](https://code.claude.com/docs/en/headless)**: the entries apply only in a folder whose trust the user already accepted interactively, or whose `hasTrustDialogAccepted` flag you set in `~/.claude.json`.90* **[Non-interactive `-p` runs](https://code.claude.com/docs/en/headless)**: the entries apply only in a folder whose trust the user already accepted interactively, or whose `hasTrustDialogAccepted` flag you set in `~/.claude.json`.

91 91

92A plugin that the marketplace lists by a relative path loads from the marketplace copy once the repository's `extraKnownMarketplaces` entries apply. A plugin whose marketplace entry points at an external source instead, such as the plugin's own GitHub repository, doesn't install from the repository's settings alone. Each contributor sees `Plugin "<name>" is enabled in project settings but isn't installed` until they run `claude plugin install <name>@<marketplace> --scope project`, as [Install plugins](https://code.claude.com/docs/en/plugins/install.md) describes.92Setting `enabledPlugins` in the repository doesn't install the plugin. Once the marketplace is registered, ask each contributor to run `claude plugin install <name>@<marketplace> --scope project`. Until they do, the `/plugin` **Errors** tab can show `Plugin "<name>" is enabled in project settings but isn't installed here` or [`not cached`](https://code.claude.com/docs/en/plugins/troubleshooting#plugin-not-cached-at). Contributors don't need the install when a local `directory` or `file` marketplace lists the plugin with a [relative-path `source`](https://code.claude.com/docs/en/plugins/marketplace-reference#plugin-sources).

93 93

94If you use a local `directory` or `file` source with a relative path, the path resolves against your repository's main checkout. When you run Claude Code from a git worktree, the path still points at the main checkout, so all worktrees share the same marketplace location.94If you use a local `directory` or `file` source with a relative path, the path resolves against your repository's main checkout. When you run Claude Code from a git worktree, the path still points at the main checkout, so all worktrees share the same marketplace location.

95 95

185| `disableSideloadFlags` | Rejects `--plugin-dir`, `--plugin-url`, `--agents`, the Agent SDK `plugins` option, and folders named in the [`CLAUDE_CODE_PLUGIN_DIRS`](https://code.claude.com/docs/en/env-vars#variables) variable at startup, and `--mcp-config` too unless every server in it is an in-process `type: "sdk"` entry. Refuses plugin folders an Agent SDK application adds mid-session with [`addPlugins`](https://code.claude.com/docs/en/agent-sdk/typescript#load-more-plugin-folders-with-addplugins) | Doesn't restrict `.mcp.json`, `claude mcp add`, or SDK-provided servers. Pair it with [`allowedMcpServers`](https://code.claude.com/docs/en/managed-mcp) |185| `disableSideloadFlags` | Rejects `--plugin-dir`, `--plugin-url`, `--agents`, the Agent SDK `plugins` option, and folders named in the [`CLAUDE_CODE_PLUGIN_DIRS`](https://code.claude.com/docs/en/env-vars#variables) variable at startup, and `--mcp-config` too unless every server in it is an in-process `type: "sdk"` entry. Refuses plugin folders an Agent SDK application adds mid-session with [`addPlugins`](https://code.claude.com/docs/en/agent-sdk/typescript#load-more-plugin-folders-with-addplugins) | Doesn't restrict `.mcp.json`, `claude mcp add`, or SDK-provided servers. Pair it with [`allowedMcpServers`](https://code.claude.com/docs/en/managed-mcp) |

186| `disableCommandPluginSources` | Blocks plugins with a `command` source from installing, updating, or loading. A `command` source is one whose plugin directory is produced by running a command on the machine. When unset, it takes the value of `allowManagedHooksOnly` | Doesn't affect other source types |186| `disableCommandPluginSources` | Blocks plugins with a `command` source from installing, updating, or loading. A `command` source is one whose plugin directory is produced by running a command on the machine. When unset, it takes the value of `allowManagedHooksOnly` | Doesn't affect other source types |

187| `allowManagedHooksOnly` | Restricts which hooks run. See [`allowManagedHooksOnly`](https://code.claude.com/docs/en/settings-reference#allowmanagedhooksonly) | Doesn't trust hooks from plugins users enable themselves |187| `allowManagedHooksOnly` | Restricts which hooks run. See [`allowManagedHooksOnly`](https://code.claude.com/docs/en/settings-reference#allowmanagedhooksonly) | Doesn't trust hooks from plugins users enable themselves |

188| `strictPluginOnlyCustomization` | Blocks skills, agents, hooks, and MCP servers that don't come from a plugin, managed settings, or Claude Code's built-ins. It also stops [skills-directory plugins](#keep-skills-directory-plugins-loading) loading. Set `true` to cover all four types, or an array of `skills`, `agents`, `hooks`, and `mcp` values such as `["skills", "hooks"]` to cover some | Doesn't restrict which plugins users install. Pair it with `strictKnownMarketplaces` |188| `strictPluginOnlyCustomization` | Blocks skills, agents, hooks, and MCP servers from user and project sources. It also stops [skills-directory plugins](#keep-skills-directory-plugins-loading) loading. Set `true` to cover all four types, or an array of `skills`, `agents`, `hooks`, and `mcp` values such as `["skills", "hooks"]` to cover some | Doesn't restrict which plugins users install, or reject the CLI flags that sideload plugins, agents, and MCP servers. Pair it with `strictKnownMarketplaces` and `disableSideloadFlags` |

189| `pluginSuggestionMarketplaces` | Marketplaces whose plugins may appear as install suggestions in the terminal. See [Recommend plugins](#recommend-plugins) | Doesn't affect the built-in tips |189| `pluginSuggestionMarketplaces` | Marketplaces whose plugins may appear as install suggestions in the terminal. See [Recommend plugins](#recommend-plugins) | Doesn't affect the built-in tips |

191| `allowedChannelPlugins` | Replaces the default list of plugins allowed to push channel messages. Requires `channelsEnabled: true` | See [Restrict which channel plugins can run](https://code.claude.com/docs/en/channels.md#restrict-which-channel-plugins-can-run) |191| `allowedChannelPlugins` | Replaces the default list of plugins allowed to push channel messages. Requires `channelsEnabled: true` | See [Restrict which channel plugins can run](https://code.claude.com/docs/en/channels.md#restrict-which-channel-plugins-can-run) |

plugins/troubleshooting.md +10 −4

Details

322 322

323### Marketplace updates keep failing offline323### Marketplace updates keep failing offline

324 324

325You work in an environment where the marketplace's git host is unreachable, and every session repeats a failed refresh in the background. Your existing checkout of the marketplace stays in place and startup isn't delayed.325You work in an environment where the marketplace's git host is unreachable, and every session repeats a failed refresh in the background. Your existing checkout of the marketplace stays in place.

326 326

327Each session, for a marketplace with [auto-update on](https://code.claude.com/docs/en/plugins/loading.md#which-marketplaces-and-plugins-auto-update), Claude Code checks the marketplace's git host for new commits in the background. When that check can't reach the host, it tries to clone the marketplace again, and offline that clone fails too.327Each session, for a marketplace with [auto-update on](https://code.claude.com/docs/en/plugins/loading.md#which-marketplaces-and-plugins-auto-update), Claude Code checks the marketplace's git host for new commits in the background. When that check can't reach the host, it tries to clone the marketplace again, and offline that clone fails too.

328 328

675 675

676### `Plugin "<name>" not cached at <path>`676### `Plugin "<name>" not cached at <path>`

677 677

678The **Errors** tab shows this line with the guidance `Run /plugin to refresh the plugin cache`. Claude Code has an install record for the plugin, but the directory the record points at is missing, for example after you cleared the cache.678The **Errors** tab shows this line with the guidance `Run /plugin to refresh the plugin cache`. It means Claude Code found no usable copy of the plugin. For example, you cleared the cache, so the directory its install record points at is missing. Or you opened a repository whose settings enable the plugin, and you haven't installed it.

679 679

680Reinstall the plugin from your shell. `claude plugin install <name>@<marketplace>` re-downloads a plugin whose install directory is missing even though its record exists:680Install the plugin from your shell. If you opened a repository whose `.claude/settings.json` enables the plugin, run this from the project with the plugin's key from `enabledPlugins`, as [Enabled in project settings but not installed](https://code.claude.com/docs/en/plugins/loading.md#enabled-in-project-settings-but-not-installed) describes:

681

682```shell theme={null}

683claude plugin install <name>@<marketplace> --scope project

684```

685

686Otherwise, run this, which re-downloads a plugin whose install directory is missing even though its record exists:

681 687

682```shell theme={null}688```shell theme={null}

683claude plugin install <name>@<marketplace>689claude plugin install <name>@<marketplace>

684```690```

685 691

686Then run `/reload-plugins` in your session. The **Errors** tab entry disappears and the plugin is back under **Installed**.692Then run `/reload-plugins` in your session. The **Errors** tab entry disappears and the plugin is listed under **Installed**.

687 693

688### `installed_plugins.json holds a record under "<id>" that this version of Claude Code cannot read`694### `installed_plugins.json holds a record under "<id>" that this version of Claude Code cannot read`

689 695

prompt-caching.md +1 −1

Details

103[Fast mode](https://code.claude.com/docs/en/fast-mode.md) and standard speed keep separate caches, so after you turn fast mode on or off, the next request can't use what the other speed cached. The first time you turn fast mode on in a conversation, the next request reads the whole conversation so far uncached at [fast mode rates](https://code.claude.com/docs/en/fast-mode.md#understand-the-cost-tradeoff). To keep that cost small, turn it on at the start of a session.103[Fast mode](https://code.claude.com/docs/en/fast-mode.md) and standard speed keep separate caches, so after you turn fast mode on or off, the next request can't use what the other speed cached. The first time you turn fast mode on in a conversation, the next request reads the whole conversation so far uncached at [fast mode rates](https://code.claude.com/docs/en/fast-mode.md#understand-the-cost-tradeoff). To keep that cost small, turn it on at the start of a session.

104 104

105* If you turn it on while Claude is working, that turn finishes at standard speed, and you pay for any uncached read on your next turn's first request.105* If you turn it on while Claude is working, that turn finishes at standard speed, and you pay for any uncached read on your next turn's first request.

106* If your current model doesn't support fast mode, running `/fast` also [switches you to Opus](https://code.claude.com/docs/en/fast-mode.md#toggle-fast-mode). That [model switch](#switching-models) starts a fresh cache on its own from the next request in the running turn.106* If your current model doesn't support fast mode, running `/fast` also [switches your model](https://code.claude.com/docs/en/fast-mode.md#toggle-fast-mode). That [model switch](#switching-models) starts a fresh cache on its own from the next request in the running turn.

107 107

108Each later toggle reads uncached whatever the speed you switch to doesn't have cached. Speed changes Claude Code makes on its own, such as the [fallback to standard speed](https://code.claude.com/docs/en/fast-mode.md#handle-rate-limits) after a rate limit and the return to fast mode later, count as toggles too.108Each later toggle reads uncached whatever the speed you switch to doesn't have cached. Speed changes Claude Code makes on its own, such as the [fallback to standard speed](https://code.claude.com/docs/en/fast-mode.md#handle-rate-limits) after a rate limit and the return to fast mode later, count as toggles too.

109 109

remote-control.md +16 −5

Details

33 * You point [`ANTHROPIC_BASE_URL`](https://code.claude.com/docs/en/env-vars) at a host other than `api.anthropic.com`, such as an [LLM gateway](https://code.claude.com/docs/en/llm-gateway) or proxy. Unset the variable to use Remote Control.33 * You point [`ANTHROPIC_BASE_URL`](https://code.claude.com/docs/en/env-vars) at a host other than `api.anthropic.com`, such as an [LLM gateway](https://code.claude.com/docs/en/llm-gateway) or proxy. Unset the variable to use Remote Control.

34 * You sign in through an enterprise [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway).34 * You sign in through an enterprise [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway).

35* **Feature-flag evaluation**: if you set an [environment variable that turns off feature-flag evaluation](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching), whether Remote Control is available depends on which one:35* **Feature-flag evaluation**: if you set an [environment variable that turns off feature-flag evaluation](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching), whether Remote Control is available depends on which one:

36 * If you set `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` or `DISABLE_GROWTHBOOK`, Remote Control is unavailable. Unset the variable wherever it's set, in your shell environment or in the `env` block of a [`settings.json` file](https://code.claude.com/docs/en/settings-reference#all-settings), to use Remote Control.36 * If you set `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` or [`CLAUDE_CODE_DISABLE_FEATURE_FLAGS`](https://code.claude.com/docs/en/env-vars#variables), Remote Control is unavailable. Unset the variable wherever it's set, in your shell environment or in the `env` block of a [`settings.json` file](https://code.claude.com/docs/en/settings-reference#all-settings), to use Remote Control.

37 * If you set only `DISABLE_TELEMETRY` or `DO_NOT_TRACK`, Remote Control stays available unless your organization requires [Trusted Devices](#trusted-devices). If it does, unset the variable to use Remote Control. Using Remote Control with either variable set requires Claude Code v2.1.283 or later, or v2.1.304 or later in the Claude Desktop app.37 * If you set only `DISABLE_TELEMETRY` or `DO_NOT_TRACK`, Remote Control stays available unless your organization requires [Trusted Devices](#trusted-devices). If it does, unset the variable to use Remote Control. Using Remote Control with either variable set requires Claude Code v2.1.283 or later, or v2.1.304 or later in the Claude Desktop app.

38* **Workspace trust**: in a directory you haven't trusted yet, `claude remote-control` prints what trusting it turns on and asks `Trust <directory>? [y/N]` before it starts. Answering `y` saves the choice, except in your home directory, where trust is never saved and the question returns on every run. When its standard input or output isn't a terminal, the command can't ask and exits with a [`Workspace not trusted`](https://code.claude.com/docs/en/errors#workspace-not-trusted-when-starting-remote-control) error.38* **Workspace trust**: in a directory you haven't trusted yet, `claude remote-control` prints what trusting it turns on and asks `Trust <directory>? [y/N]` before it starts. Answering `y` saves the choice, except in your home directory, where trust is never saved and the question returns on every run. When its standard input or output isn't a terminal, the command can't ask and exits with a [`Workspace not trusted`](https://code.claude.com/docs/en/errors#workspace-not-trusted-when-starting-remote-control) error.

39 39

185* **Effort level**: when you set the [effort level](https://code.claude.com/docs/en/model-config.md#adjust-effort-level) from a connected device, with `/effort` or the device's effort control, Claude Code applies it to the session on your machine. If you pinned a level with `CLAUDE_CODE_EFFORT_LEVEL`, the session keeps that level, and Claude Code refuses a different pick from the effort control. Picking a level from the effort control requires Claude Code v2.1.234 or later on your machine.185* **Effort level**: when you set the [effort level](https://code.claude.com/docs/en/model-config.md#adjust-effort-level) from a connected device, with `/effort` or the device's effort control, Claude Code applies it to the session on your machine. If you pinned a level with `CLAUDE_CODE_EFFORT_LEVEL`, the session keeps that level, and Claude Code refuses a different pick from the effort control. Picking a level from the effort control requires Claude Code v2.1.234 or later on your machine.

186* **Reconnecting after a connection failure**: run `/remote-control` to reconnect. If compaction rewrote the conversation or you switched conversations with `/resume` in the meantime, Claude Code archives the server session it was using instead of leaving it in the session list. You can still find that session among your [archived sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md#find-an-archived-session) at claude.ai/code. Switching conversations while a device is still connected doesn't archive the session.186* **Reconnecting after a connection failure**: run `/remote-control` to reconnect. If compaction rewrote the conversation or you switched conversations with `/resume` in the meantime, Claude Code archives the server session it was using instead of leaving it in the session list. You can still find that session among your [archived sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md#find-an-archived-session) at claude.ai/code. Switching conversations while a device is still connected doesn't archive the session.

187 187

188### Fork a session from your browser

189

190To try a different direction without interrupting a session, open it at [claude.ai/code](https://claude.ai/code) and select **Fork** in the session's menu, or fork from an earlier message in the transcript. The fork opens as a new session in your session list and continues the conversation from that point while the original keeps running. Forking requires Claude Code v2.1.277 or later on your machine.

191

192A `claude remote-control` server started with `--spawn session` has room only for its one session, so it can't run a fork.

193

194Claude Code declines the fork in cases such as these:

195

196* The session is busy. Fork when it's idle.

197* The session is hosted by the VS Code extension or another app built on the [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md).

198

188### Enable Remote Control for all sessions199### Enable Remote Control for all sessions

189 200

190Remote Control only activates when you explicitly run `claude remote-control`, `claude --remote-control`, or `/remote-control`, unless auto-connect is turned on. To turn auto-connect on for every interactive session, run `/config` inside Claude Code and set **Enable Remote Control for all sessions**. The toggle takes three values:201Remote Control only activates when you explicitly run `claude remote-control`, `claude --remote-control`, or `/remote-control`, unless auto-connect is turned on. To turn auto-connect on for every interactive session, run `/config` inside Claude Code and set **Enable Remote Control for all sessions**. The toggle takes three values:

198* **VS Code extension**: **Enable Remote Control for all sessions** in the [command menu's](https://code.claude.com/docs/en/vs-code.md#use-the-prompt-box) Settings section.209* **VS Code extension**: **Enable Remote Control for all sessions** in the [command menu's](https://code.claude.com/docs/en/vs-code.md#use-the-prompt-box) Settings section.

199* **Desktop app**: **Connect new sessions to Remote Control** in **Settings > Code** or **Settings > Claude Code**. See [Control which sessions appear on your other devices](https://code.claude.com/docs/en/desktop.md#control-which-sessions-appear-on-your-other-devices).210* **Desktop app**: **Connect new sessions to Remote Control** in **Settings > Code** or **Settings > Claude Code**. See [Control which sessions appear on your other devices](https://code.claude.com/docs/en/desktop.md#control-which-sessions-appear-on-your-other-devices).

200 211

201To turn auto-connect on from a settings file instead, set [`remoteControlAtStartup`](https://code.claude.com/docs/en/settings-reference#remotecontrolatstartup) to `true` in your user `~/.claude/settings.json` or in [managed settings](https://code.claude.com/docs/en/managed-settings.md). In project or local settings (`.claude/settings.json`, `.claude/settings.local.json`), Claude Code honors a `false` and turns auto-connect off for that repository, but ignores a `true`, so a checked-in file can't turn on Remote Control for everyone who opens the repository.212To turn auto-connect on from a settings file instead, set [`remoteControlAtStartup`](https://code.claude.com/docs/en/settings-reference#remotecontrolatstartup) to `true` in your user `~/.claude/settings.json` or in [managed settings](https://code.claude.com/docs/en/managed-settings.md). In project or local settings (`.claude/settings.json`, `.claude/settings.local.json`), Claude Code honors a `false` and turns auto-connect off for that repository. It ignores a `true`, so you can't use a checked-in file to turn on Remote Control for everyone who opens the repository.

202 213

203Auto-connect signs in with your own claude.ai account, so a session it starts appears only in your own account's Claude apps and grants no one else access.214Auto-connect signs in with your own claude.ai account, so a session it starts appears only in your own account's Claude apps and grants no one else access.

204 215

206 217

207#### Auto-connect with `DISABLE_TELEMETRY` or `DO_NOT_TRACK` set218#### Auto-connect with `DISABLE_TELEMETRY` or `DO_NOT_TRACK` set

208 219

209With only `DISABLE_TELEMETRY` or `DO_NOT_TRACK` set, your sessions don't auto-connect through your organization's admin default or Claude Code's own default. If something else makes Remote Control unavailable for you, such as `DISABLE_GROWTHBOOK` or an LLM gateway, start with [Requirements](#requirements) instead.220With only `DISABLE_TELEMETRY` or `DO_NOT_TRACK` set, your sessions don't auto-connect through your organization's admin default or Claude Code's own default. If something else makes Remote Control unavailable for you, such as [`CLAUDE_CODE_DISABLE_FEATURE_FLAGS`](https://code.claude.com/docs/en/env-vars#variables) or an LLM gateway, start with [Requirements](#requirements) instead.

210 221

211Before you turn auto-connect on with only `DISABLE_TELEMETRY` or `DO_NOT_TRACK` set, confirm that your Claude Code version meets the [requirement for these variables](#requirements). Then check whether your organization requires [Trusted Devices](#trusted-devices):222Before you turn auto-connect on with only `DISABLE_TELEMETRY` or `DO_NOT_TRACK` set, confirm that your Claude Code version meets the [requirement for these variables](#requirements). Then check whether your organization requires [Trusted Devices](#trusted-devices):

212 223

447 458

448An [environment variable](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching) that turns off feature-flag evaluation is set, and the full message names the variable Claude Code found. On versions before 2.1.154, the same configuration produces "Remote Control is not yet enabled for your account" instead. What to do depends on the variable the message names:459An [environment variable](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching) that turns off feature-flag evaluation is set, and the full message names the variable Claude Code found. On versions before 2.1.154, the same configuration produces "Remote Control is not yet enabled for your account" instead. What to do depends on the variable the message names:

449 460

450* **`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` or `DISABLE_GROWTHBOOK`**: unset the variable wherever it's set, in your shell environment or in the `env` block of a [`settings.json` file](https://code.claude.com/docs/en/settings-reference#all-settings).461* **`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, `CLAUDE_CODE_DISABLE_FEATURE_FLAGS`, or `DISABLE_GROWTHBOOK`**: unset the variable wherever it's set, in your shell environment or in the `env` block of a [`settings.json` file](https://code.claude.com/docs/en/settings-reference#all-settings).

451* **`DISABLE_TELEMETRY` or `DO_NOT_TRACK`**: on a Pro, Max, Ultra, Team, or Enterprise plan with `DISABLE_GROWTHBOOK` unset, Remote Control stays available with these variables set, unless your organization requires [Trusted Devices](#trusted-devices). If it does, unset the variable wherever it's set to use Remote Control. On v2.1.154 through v2.1.282, you see this message with either variable set, so update Claude Code to a version that meets the [requirement for these variables](#requirements).462* **`DISABLE_TELEMETRY` or `DO_NOT_TRACK`**: on a Pro, Max, Ultra, Team, or Enterprise plan with `CLAUDE_CODE_DISABLE_FEATURE_FLAGS` and `DISABLE_GROWTHBOOK` unset, Remote Control stays available with these variables set, unless your organization requires [Trusted Devices](#trusted-devices). If it does, unset the variable wherever it's set to use Remote Control. On v2.1.154 through v2.1.282, you see this message with either variable set, so update Claude Code to a version that meets the [requirement for these variables](#requirements).

452 463

453### "Remote Control is only available when using Claude via api.anthropic.com"464### "Remote Control is only available when using Claude via api.anthropic.com"

454 465

routines.md +5 −5

Details

111* **Environment variables**: provide values Claude can use during each run. They're [visible to anyone who uses the environment](https://code.claude.com/docs/en/cloud-environments.md#what-carries-over-from-your-setup), so in an Anthropic-hosted environment, store keys for the APIs Claude calls during a run as [network secrets](https://code.claude.com/docs/en/cloud-environments.md#add-network-secrets) instead. That section also lists the requests that never get a secret111* **Environment variables**: provide values Claude can use during each run. They're [visible to anyone who uses the environment](https://code.claude.com/docs/en/cloud-environments.md#what-carries-over-from-your-setup), so in an Anthropic-hosted environment, store keys for the APIs Claude calls during a run as [network secrets](https://code.claude.com/docs/en/cloud-environments.md#add-network-secrets) instead. That section also lists the requests that never get a secret

112* **Setup script**: install dependencies and tools the task needs. The result is [cached](https://code.claude.com/docs/en/cloud-environments.md#environment-caching), so the script doesn't re-run on every session112* **Setup script**: install dependencies and tools the task needs. The result is [cached](https://code.claude.com/docs/en/cloud-environments.md#environment-caching), so the script doesn't re-run on every session

113 113

114A **Default** environment is provided with **Trusted** network access, which allows only the [default allowlist](https://code.claude.com/docs/en/cloud-environments.md#default-allowed-domains) of package registries, cloud provider APIs, container registries, and common development domains through the session's network. Connectors you add to the task reach their services through Anthropic's servers, so they don't need allowlist changes.114A **Default** environment is provided with **Limited** network access and **Allow package managers** checked. Its runs reach the [default allowlist](https://code.claude.com/docs/en/cloud-environments.md#default-allowed-domains): package registries, cloud provider APIs, container registries, and common development domains. Connectors you add to the task reach their services through Anthropic's servers, so they don't need allowlist changes.

115 115

116If your task needs to reach your own services directly, or a domain outside that list, edit the environment's [network access](https://code.claude.com/docs/en/cloud-environments.md#network-access) before running. To use a separate environment, [create one](https://code.claude.com/docs/en/cloud-environments.md#configure-your-environment) first.116If your task needs to reach your own services directly, or a domain outside that list, edit the environment's [network access](https://code.claude.com/docs/en/cloud-environments.md#network-access) before running. To use a separate environment, [create one](https://code.claude.com/docs/en/cloud-environments.md#configure-your-environment) first.

117 117

431 431

432Each scheduled task uses a [cloud environment](https://code.claude.com/docs/en/cloud-environments.md) that controls network access, environment variables, and setup scripts. The task inherits the environment's network policy on every run.432Each scheduled task uses a [cloud environment](https://code.claude.com/docs/en/cloud-environments.md) that controls network access, environment variables, and setup scripts. The task inherits the environment's network policy on every run.

433 433

434The **Default** environment uses **Trusted** network access, which allows only the [default allowlist](https://code.claude.com/docs/en/cloud-environments.md#default-allowed-domains) through the session's network. Requests on that path to hosts outside the allowlist fail with `403` and `x-deny-reason: host_not_allowed`. MCP connector traffic is routed through Anthropic's servers rather than that path, so the connectors you add to the task work without adding their hosts to **Allowed domains**. Remove any connectors you don't need under [Connectors](#connectors).434The **Default** environment uses **Limited** access with **Allow package managers** checked, so its runs reach the [default allowlist](https://code.claude.com/docs/en/cloud-environments.md#default-allowed-domains). A request to a blocked host fails with `403` and `x-deny-reason: host_not_allowed`. MCP connector traffic is routed through Anthropic's servers, so the connectors you add to the task work without adding their hosts to **Allowed domains**. Remove any connectors you don't need under [Connectors](#connectors).

435 435

436To allow additional domains on one of your own environments, follow these steps. An [organization-shared environment](https://code.claude.com/docs/en/cloud-environments.md#organization-shared-environments) opens read-only here, so an Owner changes its network access from the **Cloud environments** page in [admin settings](https://claude.ai/admin-settings) instead.436To allow additional domains on one of your own environments, follow these steps. An [organization-shared environment](https://code.claude.com/docs/en/cloud-environments.md#organization-shared-environments) opens read-only here, so an Owner changes its network access from the **Cloud environments** page in [admin settings](https://claude.ai/admin-settings) instead.

437 437

447 447

448Hover over the environment in the list and click the settings icon that appears on the right.448Hover over the environment in the list and click the settings icon that appears on the right.

449 449

450**4. Change the network access level**450**4. Add the domains**

451 451

452In the **Edit cloud environment** dialog, change **Network access** to **Custom** and enter your domains in **Allowed domains**. Check **Also include default list of common package managers** to keep the [default allowlist](https://code.claude.com/docs/en/cloud-environments.md#default-allowed-domains) alongside your custom domains. Select **Full** instead for unrestricted access.452In the **Edit cloud environment** dialog, select **Limited** under **Network access** and enter your domains in **Allowed domains**. Check **Allow package managers** to allow the [default allowlist](https://code.claude.com/docs/en/cloud-environments.md#default-allowed-domains) alongside your own domains. Select **Full** instead for unrestricted access.

453 453

454**5. Save**454**5. Save**

455 455

528* [`/loop` and in-session scheduling](https://code.claude.com/docs/en/scheduled-tasks): schedule local tasks within an open CLI session528* [`/loop` and in-session scheduling](https://code.claude.com/docs/en/scheduled-tasks): schedule local tasks within an open CLI session

529* [Desktop scheduled tasks](https://code.claude.com/docs/en/desktop-scheduled-tasks.md): local scheduled tasks that run on your machine with access to local files529* [Desktop scheduled tasks](https://code.claude.com/docs/en/desktop-scheduled-tasks.md): local scheduled tasks that run on your machine with access to local files

530* [Cloud environments](https://code.claude.com/docs/en/cloud-environments.md): configure network access, environment variables, and setup scripts for cloud sessions530* [Cloud environments](https://code.claude.com/docs/en/cloud-environments.md): configure network access, environment variables, and setup scripts for cloud sessions

531* [Projects](https://code.claude.com/docs/en/claude-projects.md): ongoing work Claude coordinates across parallel cloud sessions; scheduled tasks created from a project appear on its **Scheduled tasks** tab531* [Projects](https://code.claude.com/docs/en/claude-projects.md): ongoing work Claude coordinates across parallel cloud sessions; scheduled tasks created from a project appear in its **Scheduled tasks** view

532* [MCP connectors](https://code.claude.com/docs/en/mcp.md): connect external services like Slack, Linear, and Google Drive532* [MCP connectors](https://code.claude.com/docs/en/mcp.md): connect external services like Slack, Linear, and Google Drive

533* [GitHub Actions](https://code.claude.com/docs/en/github-actions.md): run Claude in your CI pipeline on repository events533* [GitHub Actions](https://code.claude.com/docs/en/github-actions.md): run Claude in your CI pipeline on repository events

sandbox-environments.md +2 −3

Details

6 6

7> Compare Claude Code sandbox options: the built-in sandboxed Bash tool, sandbox runtime, dev containers, Docker, and VMs. Choose the right isolation for your threat model.7> Compare Claude Code sandbox options: the built-in sandboxed Bash tool, sandbox runtime, dev containers, Docker, and VMs. Choose the right isolation for your threat model.

8 8

9Isolating Claude Code limits what a session can read, write, and reach on the network. This matters most when you let Claude work with fewer permission prompts, run it unattended, or point it at code you do not fully trust.9Isolating Claude Code limits what a session can read, write, and reach on the network. This matters most when you let Claude work with fewer permission prompts or run it unattended.

10 10

11Claude Code can run in several kinds of isolated environments, ranging from a lightweight per-command sandbox to a fully separate virtual machine. This page compares them by what they isolate and what they require, helps you choose one for your threat model, and shows how to enforce that choice across an organization.11Claude Code can run in several kinds of isolated environments, ranging from a lightweight per-command sandbox to a fully separate virtual machine. This page compares them by what they isolate and what they require, helps you choose one for your threat model, and shows how to enforce that choice across an organization.

12 12

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), 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| Work on an untrusted repository | A dedicated virtual machine, or a [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md) if you have a Claude subscription; GitHub is not required when you launch with `claude --cloud` |

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

49| Use Claude Code from a device with no local setup | A [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md), which requires a Claude subscription, and a connected GitHub account to clone a GitHub repository |48| Use Claude Code from a device with no local setup | A [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md), which requires a Claude subscription, and a connected GitHub account to clone a GitHub repository |

50| Require isolation for every developer in your organization | [Enforce isolation across an organization](#enforce-isolation-across-an-organization) |49| Require isolation for every developer in your organization | [Enforce isolation across an organization](#enforce-isolation-across-an-organization) |

157 156

158## Virtual machine157## Virtual machine

159 158

160A dedicated virtual machine provides the strongest separation, with its own kernel and, in cloud or microVM deployments, its own virtualized hardware. Options include cloud instances, local hypervisors, and microVMs such as Firecracker. Use this approach when you are evaluating untrusted code, when your security policy requires kernel-level separation between the agent and the host, or when no host-level approach meets your compliance requirements.159A dedicated virtual machine provides the strongest separation, with its own kernel and, in cloud or microVM deployments, its own virtualized hardware. Options include cloud instances, local hypervisors, and microVMs such as Firecracker. Use this approach when your security policy requires kernel-level separation between the agent and the host, or when no host-level approach meets your compliance requirements.

161 160

162[Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) provides a microVM with its own Docker daemon and workspace sync, which can run Claude Code on any host with Docker Sandboxes installed. It is a free, standalone product from Docker that does not require Docker Desktop.161[Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) provides a microVM with its own Docker daemon and workspace sync, which can run Claude Code on any host with Docker Sandboxes installed. It is a free, standalone product from Docker that does not require Docker Desktop.

163 162

sandboxing.md +4 −0

Details

903 903

904After the failure, Claude may [offer to rerun the command outside the sandbox](#the-unsandboxed-retry-escape-hatch). Approve that retry, or run the git command yourself in another terminal. If you've set `allowUnsandboxedCommands` to `false`, Claude can't offer the retry, so run the command yourself.904After the failure, Claude may [offer to rerun the command outside the sandbox](#the-unsandboxed-retry-escape-hatch). Approve that retry, or run the git command yourself in another terminal. If you've set `allowUnsandboxedCommands` to `false`, Claude can't offer the retry, so run the command yourself.

905 905

906### A git command fails with `Unable to create '…/index.lock'`

907

908If you started Claude Code in a repository's subdirectory, this error can mean `.git` is outside [what sandboxed commands can write to](#filesystem-isolation). Start Claude Code from the repository root instead, or from the worktree's root in a [linked worktree](https://code.claude.com/docs/en/worktrees.md).

909

906### A folder named `objects` or `refs` disappears after a command910### A folder named `objects` or `refs` disappears after a command

907 911

908A top-level `objects` or `refs` folder that appeared during the session can be [deleted after a sandboxed command ends](#when-the-sandbox-deletes-head-objects-or-refs). It doesn't matter whether a command, Claude, or you created it. To keep a folder, leave something in it. If a `HEAD` file or symlink has been at the top level during the session, move it away, then restart every Claude Code session open there.912A top-level `objects` or `refs` folder that appeared during the session can be [deleted after a sandboxed command ends](#when-the-sandbox-deletes-head-objects-or-refs). It doesn't matter whether a command, Claude, or you created it. To keep a folder, leave something in it. If a `HEAD` file or symlink has been at the top level during the session, move it away, then restart every Claude Code session open there.

scheduled-tasks.md +4 −2

Details

92* tend to the current branch's pull request: review comments, failed CI runs, merge conflicts92* tend to the current branch's pull request: review comments, failed CI runs, merge conflicts

93* run cleanup passes such as bug hunts or simplification when nothing else is pending93* run cleanup passes such as bug hunts or simplification when nothing else is pending

94 94

~~95Claude does not start new initiatives outside that scope, and irreversible actions such as pushing or deleting only proceed when they continue something the transcript already authorized.~~95Each run goes through your session's [permission checks](https://code.claude.com/docs/en/permissions.md) before it pushes or deletes anything.

97A bare `/loop` runs this prompt at a [dynamically chosen interval](#let-claude-choose-the-interval):

96 98

97```text theme={null}99```text theme={null}

98/loop100/loop

99```101```

100 102

101A bare `/loop` runs this prompt at a [dynamically chosen interval](#let-claude-choose-the-interval). Add an interval, for example `/loop 15m`, to run it on a fixed schedule instead. To replace the built-in prompt with your own default, see [Customize the default prompt with loop.md](#customize-the-default-prompt-with-loop-md).103Add an interval, for example `/loop 15m`, to run it on a fixed schedule instead. To replace the built-in prompt with your own default, see [Customize the default prompt with loop.md](#customize-the-default-prompt-with-loop-md).

102 104

103### Customize the default prompt with loop.md105### Customize the default prompt with loop.md

104 106

security-guidance.md +2 −0

Details

54}54}

55```55```

56 56

57Each teammate also [runs `claude plugin install security-guidance@claude-plugins-official --scope project`](https://code.claude.com/docs/en/plugins/loading#enabled-in-project-settings-but-not-installed) once per clone.

57Administrators can enable the plugin organization-wide by setting [`enabledPlugins`](https://code.claude.com/docs/en/settings-reference#enabledplugins) in [managed settings](https://code.claude.com/docs/en/admin-setup.md).59Administrators can enable the plugin organization-wide by setting [`enabledPlugins`](https://code.claude.com/docs/en/settings-reference#enabledplugins) in [managed settings](https://code.claude.com/docs/en/admin-setup.md).

58 60

59## What the plugin checks61## What the plugin checks

self-hosted-environments-configuration.md +9 −7

Details

235set -u235set -u

236export GIT_ALLOW_PROTOCOL=${GIT_ALLOW_PROTOCOL:-https:http:ssh}236export GIT_ALLOW_PROTOCOL=${GIT_ALLOW_PROTOCOL:-https:http:ssh}

237IFS=':'237IFS=':'

238rc=0 # becomes 1 when a step fails; a non-zero exit makes the runner log it

238# -c overrides beat repo-local settings, blocking session-written fsmonitor,239# -c overrides beat repo-local settings, blocking session-written fsmonitor,

239# hook-path, and gpg-program config from executing code with the hook's240# hook-path, and gpg-program config from executing code with the hook's

240# privileges. -c commit.gpgsign=false also leaves these rescue commits241# privileges. -c commit.gpgsign=false also leaves these rescue commits

245g() { git -c core.fsmonitor=false -c core.hooksPath=/dev/null \246g() { git -c core.fsmonitor=false -c core.hooksPath=/dev/null \

246 -c commit.gpgsign=false "$@"; }247 -c commit.gpgsign=false "$@"; }

247for ws in $CLAUDE_RUNNER_WORKSPACE_PATHS; do248for ws in $CLAUDE_RUNNER_WORKSPACE_PATHS; do

248 cd "$ws" 2>/dev/null || continue249 cd "$ws" || { rc=1; continue; }

249 [ -z "$(g status --porcelain 2>/dev/null)" ] && continue250 g add -A || rc=1

250 g add -A251 g diff-index --cached --quiet HEAD && continue # nothing to save

251 g commit -q -m "runner snapshot: $CLAUDE_RUNNER_SESSION_ID ($CLAUDE_RUNNER_EXIT_REASON)" || continue252 g commit -q -m "runner snapshot: $CLAUDE_RUNNER_SESSION_ID ($CLAUDE_RUNNER_EXIT_REASON)" || { rc=1; continue; }

252 g push -q origin "HEAD:refs/heads/rescue/$CLAUDE_RUNNER_SESSION_ID" || true253 g push -q origin "HEAD:refs/heads/rescue/$CLAUDE_RUNNER_SESSION_ID" || rc=1

253done254done

255exit "$rc"

254```256```

255 257

256The `GIT_ALLOW_PROTOCOL` line in the script limits git to HTTPS, HTTP, and SSH remotes. If the runner's environment already sets a non-empty `GIT_ALLOW_PROTOCOL` list of its own, the script keeps that list.258The `GIT_ALLOW_PROTOCOL` line in the script limits git to HTTPS, HTTP, and SSH remotes. If the runner's environment already sets a non-empty `GIT_ALLOW_PROTOCOL` list of its own, the script keeps that list.

636 638

637* The enterprise-scope [managed MCP file](https://code.claude.com/docs/en/managed-mcp.md) at its standard system path: `/etc/claude-code/managed-mcp.json` on Linux runner hosts, `/Library/Application Support/ClaudeCode/managed-mcp.json` on macOS hosts. Use it for locked-down fleets where only administrator-listed servers may load. See [exclusive control with managed-mcp.json](https://code.claude.com/docs/en/managed-mcp.md#exclusive-control-with-managed-mcp-json) for the precedence rules. When this file is on the runner host, Claude Code skips the MCP servers Anthropic's control plane delivers to a session, including claude.ai connectors, and names them in a warning on the session child's stderr, which the runner records at the `debug` log level. Before v2.1.229, those sessions exited at startup with `You cannot dynamically configure MCP servers when an enterprise MCP config is present`.639* The enterprise-scope [managed MCP file](https://code.claude.com/docs/en/managed-mcp.md) at its standard system path: `/etc/claude-code/managed-mcp.json` on Linux runner hosts, `/Library/Application Support/ClaudeCode/managed-mcp.json` on macOS hosts. Use it for locked-down fleets where only administrator-listed servers may load. See [exclusive control with managed-mcp.json](https://code.claude.com/docs/en/managed-mcp.md#exclusive-control-with-managed-mcp-json) for the precedence rules. When this file is on the runner host, Claude Code skips the MCP servers Anthropic's control plane delivers to a session, including claude.ai connectors, and names them in a warning on the session child's stderr, which the runner records at the `debug` log level. Before v2.1.229, those sessions exited at startup with `You cannot dynamically configure MCP servers when an enterprise MCP config is present`.

638* The [`managedMcpServers`](https://code.claude.com/docs/en/settings-reference#managedmcpservers) key in [managed settings](https://code.claude.com/docs/en/managed-settings.md) on the runner host: provides HTTP and SSE servers without taking exclusive control, so servers from the other sources still load. Requires Claude Code v2.1.259 or later.640* The [`managedMcpServers`](https://code.claude.com/docs/en/settings-reference#managedmcpservers) key in [managed settings](https://code.claude.com/docs/en/managed-settings.md) on the runner host: provides HTTP and SSE servers without taking exclusive control, so servers from the other sources still load. Requires Claude Code v2.1.259 or later.

639* `<repo>/.mcp.json`: project scope. Outside a [project](https://code.claude.com/docs/en/claude-projects.md#what-threads-pick-up-from-your-repositories) thread, commit the file to the repository, and its servers are auto-approved in cloud sessions. In a session with several repositories, [at most one repository's file loads](#repository-settings-in-sessions-with-several-repositories).641* `<repo>/.mcp.json`: project scope. Outside a [project](https://code.claude.com/docs/en/claude-projects.md#what-threads-pick-up-from-your-repositories) thread, commit the file to the repository, and its servers are auto-approved in cloud sessions. In a session with several repositories, [at most one repository's file loads](#repository-settings-in-sessions-with-several-repositories). With [`--trust-workspace false`](https://code.claude.com/docs/en/self-hosted-environments-reference#runner-cli-flags), sessions skip the file's servers unless settings the repository doesn't commit approve them, such as [`enabledMcpjsonServers`](https://code.claude.com/docs/en/settings-reference#enabledmcpjsonservers) in the host's `~/.claude/settings.json`. Requires Claude Code v2.1.319 or later.

640* A [`--mcp-config`](https://code.claude.com/docs/en/cli-reference#cli-flags) file from your wrapper script: append the flag after `"$@"`, as in `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --mcp-config /etc/claude/mcp.json`. To keep that file's servers running when the session's delivered servers are updated mid-session, have your wrapper pass the [full environment](#wrapper-scripts) to the child, as `exec` does. Before v2.1.299, the stdio, HTTP, and SSE servers in that file shut down at the first such update that didn't name them.642* A [`--mcp-config`](https://code.claude.com/docs/en/cli-reference#cli-flags) file from your wrapper script: append the flag after `"$@"`, as in `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --mcp-config /etc/claude/mcp.json`. To keep that file's servers running when the session's delivered servers are updated mid-session, have your wrapper pass the [full environment](#wrapper-scripts) to the child, as `exec` does. Before v2.1.299, the stdio, HTTP, and SSE servers in that file shut down at the first such update that didn't name them.

641 643

642When connector delivery is enabled for your organization, Anthropic's control plane delivers the connectors you've configured on claude.ai to interactively-created sessions through server-provided MCP configuration, routed through `api.anthropic.com`. Sessions created programmatically, such as [CLI dispatches](https://code.claude.com/docs/en/self-hosted-environments-testing.md#run-the-test-loop), don't receive connector delivery; give them MCP servers through any of the other sources this section lists instead. The child's OAuth token doesn't carry a scope for fetching connectors directly, so the child doesn't attempt that fetch itself; delivery is server-driven.644When connector delivery is enabled for your organization, Anthropic's control plane delivers the connectors you've configured on claude.ai to interactively-created sessions through server-provided MCP configuration, routed through `api.anthropic.com`. Sessions created programmatically, such as [CLI dispatches](https://code.claude.com/docs/en/self-hosted-environments-testing.md#run-the-test-loop), don't receive connector delivery; give them MCP servers through any of the other sources this section lists instead. The child's OAuth token doesn't carry a scope for fetching connectors directly, so the child doesn't attempt that fetch itself; delivery is server-driven.

906 908

907In any other session with several repositories, Claude Code reads project settings from the directory the session starts in, so at most one repository's `.claude/settings.json` takes effect as project settings. A hook defined in another repository's file doesn't run, a deny rule in it doesn't apply, and its `env` isn't set.909In any other session with several repositories, Claude Code reads project settings from the directory the session starts in, so at most one repository's `.claude/settings.json` takes effect as project settings. A hook defined in another repository's file doesn't run, a deny rule in it doesn't apply, and its `env` isn't set.

908 910

909* **`--capacity 1`, the default, with the built-in checkout**: the session starts in the first repository in its list of repositories. That repository's `.claude/settings.json` takes effect as project settings and its `.mcp.json` loads, and the other repositories' don't.911* **`--capacity 1`, the default, with the built-in checkout**: the session starts in the first repository in its list of repositories. That repository's `.claude/settings.json` takes effect as project settings and its [`.mcp.json`](#mcp-servers) loads, and the other repositories' don't.

910* **A `--capacity` above one, or a [`checkout` hook](#checkout)**: the session starts in a per-session directory that contains the checkouts. No repository's `.claude/settings.json` takes effect as project settings, no repository's `.mcp.json` loads, and [`$CLAUDE_PROJECT_DIR`](https://code.claude.com/docs/en/hooks#reference-scripts-by-path) in a hook command is that directory, not a checkout.912* **A `--capacity` above one, or a [`checkout` hook](#checkout)**: the session starts in a per-session directory that contains the checkouts. No repository's `.claude/settings.json` takes effect as project settings, no repository's `.mcp.json` loads, and [`$CLAUDE_PROJECT_DIR`](https://code.claude.com/docs/en/hooks#reference-scripts-by-path) in a hook command is that directory, not a checkout.

911 913

912Each repository's `CLAUDE.md` loads wherever the session starts. Outside a project thread, its skills load too. The runner passes every repository to Claude Code as an [additional directory](https://code.claude.com/docs/en/permissions.md#additional-directories-grant-file-access-not-configuration), so Claude Code also reads the `enabledPlugins` and `extraKnownMarketplaces` keys from each repository's `.claude/settings.json`.914Each repository's `CLAUDE.md` loads wherever the session starts. Outside a project thread, its skills load too. The runner passes every repository to Claude Code as an [additional directory](https://code.claude.com/docs/en/permissions.md#additional-directories-grant-file-access-not-configuration), so Claude Code also reads the `enabledPlugins` and `extraKnownMarketplaces` keys from each repository's `.claude/settings.json`.

self-hosted-environments-deploy.md +5 −3

Details

23 * **With [Anthropic-managed git](#use-the-anthropic-git-proxy)**: with such a credential, Claude reaches GitHub directly instead of through Anthropic-managed git.23 * **With [Anthropic-managed git](#use-the-anthropic-git-proxy)**: with such a credential, Claude reaches GitHub directly instead of through Anthropic-managed git.

24 * **Without Anthropic-managed git**: a clone credential can stay in the image if you scope it as tightly as [Ship git config in your image](#ship-git-config-in-your-image) describes.24 * **Without Anthropic-managed git**: a clone credential can stay in the image if you scope it as tightly as [Ship git config in your image](#ship-git-config-in-your-image) describes.

25* **Keep the environment secret off session-running hosts**: the environment secret can register runners and pick up any session queued on the environment. On a fixed fleet it lives on every runner host, where any session's code can read the secret file. Prefer [on-demand runners](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#on-demand-runners), where the secret stays on the orchestrator host, which never runs user code, and each runner receives a single-use work order that registers exactly one runner. On a fixed fleet, treat the environment-secret file as readable by every session and rotate the secret after any suspected session compromise.25* **Keep the environment secret off session-running hosts**: the environment secret can register runners and pick up any session queued on the environment. On a fixed fleet it lives on every runner host, where any session's code can read the secret file. Prefer [on-demand runners](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#on-demand-runners), where the secret stays on the orchestrator host, which never runs user code, and each runner receives a single-use work order that registers exactly one runner. On a fixed fleet, treat the environment-secret file as readable by every session and rotate the secret after any suspected session compromise.

26 * **After a suspected compromise**: have an [Owner](https://code.claude.com/docs/en/cloud-environments.md#organization-shared-environments) create a new secret and revoke the old one from the environment's **Configuration** tab, then roll out the new one. Anthropic refuses every orchestrator and runner on the old secret, on-demand runners from its work orders included. Your runners exit, interrupting their sessions.26 * **After a suspected compromise, first revoke the suspect session**: before you stop its runner or revoke the secret, select **Revoke token** in the session's menu on the **Activity** tab. No runner can then resume it.

27 * **Then replace the secret**: have an [Owner](https://code.claude.com/docs/en/cloud-environments.md#organization-shared-environments) create a new secret and revoke the old one from the environment's **Configuration** tab, then roll out the new one. Anthropic refuses every orchestrator and runner on the old secret, on-demand runners from its work orders included. Your runners exit, interrupting their sessions.

27* **Default-deny network egress**: restrict runner and session container outbound traffic at your own network boundary on every environment; [Default-deny egress](#default-deny-egress) covers what to allow and why.28* **Default-deny network egress**: restrict runner and session container outbound traffic at your own network boundary on every environment; [Default-deny egress](#default-deny-egress) covers what to allow and why.

28* **Least-privilege host IAM**: the compute identity attached to the runner host, such as an instance profile or node service account, should grant only what the runner itself needs. Sessions should obtain their own credentials through your wrapper script rather than inheriting the host's.29* **Least-privilege host IAM**: the compute identity attached to the runner host, such as an instance profile or node service account, should grant only what the runner itself needs. Sessions should obtain their own credentials through your wrapper script rather than inheriting the host's.

29* **Block the cloud metadata endpoint from sessions**: keeping sessions off the host identity requires blocking their access to the cloud metadata endpoint, and subnet-level egress policies don't intercept link-local metadata traffic, so block it in the container itself:30* **Block the cloud metadata endpoint from sessions**: keeping sessions off the host identity requires blocking their access to the cloud metadata endpoint, and subnet-level egress policies don't intercept link-local metadata traffic, so block it in the container itself:

243 244

244For each session, a runner on Claude Code v2.1.267 or later also logs either a `[runner:session]` line containing `governed git ACTIVE` when Anthropic serves the session's git, or one `[runner:warn]` line containing `the server withheld Anthropic-managed git for this session` when it doesn't. Find the line you're seeing among these cases:245For each session, a runner on Claude Code v2.1.267 or later also logs either a `[runner:session]` line containing `governed git ACTIVE` when Anthropic serves the session's git, or one `[runner:warn]` line containing `the server withheld Anthropic-managed git for this session` when it doesn't. Find the line you're seeing among these cases:

245 246

246* **Neither `governed git ACTIVE` nor the `withheld` line**: a runner older than Claude Code v2.1.267 logs neither line, and Anthropic doesn't serve its sessions. Update the runner to v2.1.267 or later by following [Pin the version](#pin-the-version).247* **Neither `governed git ACTIVE` nor the `withheld` line**: if the runner is older than Claude Code v2.1.267, Anthropic doesn't serve its sessions. Update the runner to v2.1.267 or later by following [Pin the version](#pin-the-version).

247* **The `withheld` line**: Anthropic didn't serve the session. A runner that worked with the git proxy before can fail this way with no change on your side.248* **The `withheld` line**: Anthropic didn't serve the session. A runner that worked with the git proxy before can fail this way with no change on your side.

248 * **A repository isn't on github.com**: a session with even one repository on another git host, such as GitHub Enterprise Server, isn't served, including its github.com repositories. [Turn the Anthropic git proxy off](#turn-the-anthropic-git-proxy-off) for that environment's runners.249 * **A repository isn't on github.com**: a session with even one repository on another git host, such as GitHub Enterprise Server, isn't served, including its github.com repositories. [Turn the Anthropic git proxy off](#turn-the-anthropic-git-proxy-off) for that environment's runners.

249 * **Every repository is on github.com**: report the failure to [your Anthropic account team](#report-an-issue) with the session ID from the `withheld` line. Anthropic records the reason on its side.250 * **Every repository is on github.com**: report the failure to [your Anthropic account team](#report-an-issue) with the session ID from the `withheld` line. Anthropic records the reason on its side.

396Swap `linux-x64` for `linux-arm64` if your nodes are ARM, or for `linux-x64-musl` or `linux-arm64-musl` on a musl-based image such as Alpine; see [Alpine Linux setup](https://code.claude.com/docs/en/setup.md#alpine-linux-and-musl-based-distributions) for the extra packages musl images need. The URL is the standard Claude Code release location, so you can verify the downloaded binary against the release's signed manifest as described in [Binary integrity and code signing](https://code.claude.com/docs/en/setup.md#binary-integrity-and-code-signing). The runner requires Claude Code version 2.1.224 or later, or 2.1.229 or later to serve Claude Tag sessions. Build the image, then push it to your registry and reference it in the recipes below:397Swap `linux-x64` for `linux-arm64` if your nodes are ARM, or for `linux-x64-musl` or `linux-arm64-musl` on a musl-based image such as Alpine; see [Alpine Linux setup](https://code.claude.com/docs/en/setup.md#alpine-linux-and-musl-based-distributions) for the extra packages musl images need. The URL is the standard Claude Code release location, so you can verify the downloaded binary against the release's signed manifest as described in [Binary integrity and code signing](https://code.claude.com/docs/en/setup.md#binary-integrity-and-code-signing). The runner requires Claude Code version 2.1.224 or later, or 2.1.229 or later to serve Claude Tag sessions. Build the image, then push it to your registry and reference it in the recipes below:

397 398

398```bash theme={null}399```bash theme={null}

400# If your model needs a newer release, change stable to latest in the URL

399docker build \401docker build \

400 --build-arg CLAUDE_CODE_VERSION="$(curl -fsSL https://downloads.claude.ai/claude-code-releases/stable)" \402 --build-arg CLAUDE_CODE_VERSION="$(curl -fsSL https://downloads.claude.ai/claude-code-releases/stable)" \

401 -t <your-registry>/claude-runner:latest .403 -t <your-registry>/claude-runner:latest .

429The runner uses `--capacity` to cap how many sessions it runs at once. It doesn't divide CPU or memory between them, so the sessions on a runner share the container's CPU and memory. To keep one session's memory use from ending the others, run one session per runner with [its own memory limit](#give-each-session-its-own-memory-limit).431The runner uses `--capacity` to cap how many sessions it runs at once. It doesn't divide CPU or memory between them, so the sessions on a runner share the container's CPU and memory. To keep one session's memory use from ending the others, run one session per runner with [its own memory limit](#give-each-session-its-own-memory-limit).

430 432

431* **One session per runner**: give each container one session's values. Use this sizing at `--capacity 1`, which the [hardening section](#harden-your-deployment) recommends, and for [on-demand runners](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#on-demand-runners), where you set the values on the workload your [`spawn-runner` hook](https://code.claude.com/docs/en/self-hosted-environments-configuration#the-spawn-runner-hook) submits, such as a Kubernetes Job's pod template.433* **One session per runner**: give each container one session's values. Use this sizing at `--capacity 1`, which the [hardening section](#harden-your-deployment) recommends, and for [on-demand runners](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#on-demand-runners), where you set the values on the workload your [`spawn-runner` hook](https://code.claude.com/docs/en/self-hosted-environments-configuration#the-spawn-runner-hook) submits, such as a Kubernetes Job's pod template.

432* **Several sessions per runner**: at a `--capacity` above one, multiply one session's values by the capacity, because up to that many sessions can run in the container at the same time. The [Kubernetes](#kubernetes) and [Docker Compose](#docker-compose) recipes run `--capacity 4` with no CPU or memory limits, so add limits sized for the capacity you run.434* **Several sessions per runner**: at a `--capacity` above one, multiply one session's values by the capacity, because up to that many sessions can run in the container at the same time, [idle ones included](#release-idle-sessions-on-a-fixed-fleet). The [Kubernetes](#kubernetes) and [Docker Compose](#docker-compose) recipes run `--capacity 4` with no CPU or memory limits, so add limits sized for the capacity you run.

433* **Several runner containers on one host**: size the host for the sum of the runners' capacities, because each runner counts only its own sessions against `--capacity`:435* **Several runner containers on one host**: size the host for the sum of the runners' capacities, because each runner counts only its own sessions against `--capacity`:

434 436

435 * **Memory**: multiply one session's memory by the sum, then add what the host's own processes use437 * **Memory**: multiply one session's memory by the sum, then add what the host's own processes use

self-hosted-environments-reference.md +2 −2

Details

56| `--session-stop-grace-sec <n>` | `SELF_HOSTED_RUNNER_SESSION_STOP_GRACE_MS` | `5` | How long to wait for the Claude process to exit cleanly after a session ends, before force-killing it. Raise the value if the child's own `SessionEnd` hooks need more time. |56| `--session-stop-grace-sec <n>` | `SELF_HOSTED_RUNNER_SESSION_STOP_GRACE_MS` | `5` | How long to wait for the Claude process to exit cleanly after a session ends, before force-killing it. Raise the value if the child's own `SessionEnd` hooks need more time. |

57| `--startup-timeout-min <n>` | `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS` | `15` | How long to wait on a child process that hasn't initialized before releasing the session's slot. See [Session startup timeout](#session-startup-timeout) for where the count starts and which sessions it leaves running. `0` disables the timeout. |57| `--startup-timeout-min <n>` | `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS` | `15` | How long to wait on a child process that hasn't initialized before releasing the session's slot. See [Session startup timeout](#session-startup-timeout) for where the count starts and which sessions it leaves running. `0` disables the timeout. |

58| `--trust-workspace [bool]` | `SELF_HOSTED_RUNNER_TRUST_WORKSPACE` | on | Seed persisted trust for each session's repository paths so repo-committed `permissions.allow` and `additionalDirectories` are honored. Set `false` to drop repo-committed permission grants and configure allow rules in the host config's `settings.json` instead; repository-committed `sandbox.*` settings still apply either way, which is why the [repo-settings guard](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#harden-your-deployment) scans them regardless of this flag. |58| `--trust-workspace [bool]` | `SELF_HOSTED_RUNNER_TRUST_WORKSPACE` | on | Seed persisted trust for each session's repository paths so repo-committed `permissions.allow` and `additionalDirectories` are honored. Set `false` to drop repo-committed permission grants and configure allow rules in the host config's `settings.json` instead; repository-committed `sandbox.*` settings still apply either way, which is why the [repo-settings guard](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#harden-your-deployment) scans them regardless of this flag. |

59| `--use-anthropic-git-proxy` | `CLAUDE_RUNNER_USE_GIT_PROXY=1` | off | Clone repositories on github.com via the [Anthropic git proxy](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#use-the-anthropic-git-proxy) instead of customer-managed git auth. Requires `--capacity 1` and git 2.32 or later; the runner refuses to start otherwise. Supersedes the rewrite flags. |59| `--use-anthropic-git-proxy` | `CLAUDE_RUNNER_USE_GIT_PROXY=1` | off | Clone repositories on github.com via the [Anthropic git proxy](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#use-the-anthropic-git-proxy) instead of customer-managed git auth. Requires `--capacity 1` and git 2.32 or later; the runner refuses to start otherwise. Also requires Claude Code v2.1.267 or later. Supersedes the rewrite flags. |

60 60

61Most duration flags have a maximum, chosen to keep each timeout inside the runtime's 32-bit timer ceiling of roughly 24.85 days. The `--*-min` flags cap at 10080 minutes, 7 days; `--drain-grace-sec` at 604800 seconds, also 7 days; and `--drain-wait-sec` at 86400 seconds, 24 hours. `--session-stop-grace-sec` and `--post-session-hook-timeout-sec` are uncapped. Overrunning a cap behaves differently per surface:61Most duration flags have a maximum, chosen to keep each timeout inside the runtime's 32-bit timer ceiling of roughly 24.85 days. The `--*-min` flags cap at 10080 minutes, 7 days; `--drain-grace-sec` at 604800 seconds, also 7 days; and `--drain-wait-sec` at 86400 seconds, 24 hours. `--session-stop-grace-sec` and `--post-session-hook-timeout-sec` are uncapped. Overrunning a cap behaves differently per surface:

62 62

135 135

136Session children send operational telemetry to Anthropic unless you turn it off. No code or repository content is sent. Set telemetry variables on the runner process; the runner re-asserts them after applying server-provided environment variables, so the operator's setting always takes precedence.136Session children send operational telemetry to Anthropic unless you turn it off. No code or repository content is sent. Set telemetry variables on the runner process; the runner re-asserts them after applying server-provided environment variables, so the operator's setting always takes precedence.

137 137

138One control is specific to self-hosted environments: `CLAUDE_CODE_BYOC_ENABLE_DATADOG=1` opts in to Datadog operational metrics, which are off by default in self-hosted environments. The general Claude Code telemetry controls, `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `DISABLE_ERROR_REPORTING`, and `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, apply to session children as documented in the [environment variable reference](https://code.claude.com/docs/en/env-vars.md). `DISABLE_GROWTHBOOK` is related but different: setting `DISABLE_GROWTHBOOK=1` disables feature-flag fetching, and telemetry stays on unless `DISABLE_TELEMETRY` is also set.138One control is specific to self-hosted environments: `CLAUDE_CODE_BYOC_ENABLE_DATADOG=1` opts in to Datadog operational metrics, which are off by default in self-hosted environments. The general Claude Code telemetry controls, `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `DISABLE_ERROR_REPORTING`, and `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, apply to session children as documented in the [environment variable reference](https://code.claude.com/docs/en/env-vars.md). [`CLAUDE_CODE_DISABLE_FEATURE_FLAGS`](https://code.claude.com/docs/en/env-vars#variables) is related but different: setting `CLAUDE_CODE_DISABLE_FEATURE_FLAGS=1` disables feature-flag fetching, and telemetry stays on unless `DISABLE_TELEMETRY` is also set. `CLAUDE_CODE_DISABLE_FEATURE_FLAGS` requires Claude Code v2.1.319 or later.

139 139

140`CLAUDE_CODE_ENABLE_TELEMETRY` is unrelated: it enables OpenTelemetry export to your own collector, as described in [Monitoring](https://code.claude.com/docs/en/monitoring-usage.md), and doesn't control Anthropic's analytics.140`CLAUDE_CODE_ENABLE_TELEMETRY` is unrelated: it enables OpenTelemetry export to your own collector, as described in [Monitoring](https://code.claude.com/docs/en/monitoring-usage.md), and doesn't control Anthropic's analytics.

141 141

self-hosted-environments-testing.md +1 −1

Details

12 12

13In a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments), Claude Code [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) run on a runner image you build and maintain. Before rolling a new image to your production environment, drive a full session against a test environment from a script: create a session, read Claude's reply, send a follow-up, and read that reply too. This is the shape of a CI smoke test that verifies your runner image, git access, and any custom tools before you promote a change.13In a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments), Claude Code [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) run on a runner image you build and maintain. Before rolling a new image to your production environment, drive a full session against a test environment from a script: create a session, read Claude's reply, send a follow-up, and read that reply too. This is the shape of a CI smoke test that verifies your runner image, git access, and any custom tools before you promote a change.

14 14

15This recipe assumes you've already [set up an environment and a runner](https://code.claude.com/docs/en/self-hosted-environments-quickstart.md#set-up-an-environment-and-runner), and that your CI job starts the runner process on the same host as the test script, the natural setup for testing a new runner image. A Stop hook you install on the runner writes each turn's final reply to a local file, and the script reads it from there, so the only calls to the Anthropic API are the two dispatches themselves. If your test runners are on separate infrastructure, see [Remote test runners](#remote-test-runners).15This recipe assumes you've already [set up an environment and a runner](https://code.claude.com/docs/en/self-hosted-environments-quickstart.md#set-up-an-environment-and-runner), and that your CI job starts the runner process on the same host as the test script. A Stop hook you install on the runner writes each turn's final reply to a local file, and the script reads it from there. If your test runners are on separate infrastructure, see [Remote test runners](#remote-test-runners).

16 16

17## Install the capture hook on your test runner17## Install the capture hook on your test runner

18 18

server-managed-settings.md +6 −2

Details

62 62

63Hooks use the same format as in `settings.json`.63Hooks use the same format as in `settings.json`.

64 64

~~65This example runs an audit script after every file edit across the organization:~~65This example runs an audit script after `Edit` and `Write` tool calls across the organization:

66 66

67```json theme={null}67```json theme={null}

68{68{

95 95

96To confirm that settings are being applied, ask a user to restart Claude Code. If the configuration includes settings that trigger the [security approval dialog](#security-approval-dialogs), the user sees a prompt describing the managed settings the next time Claude Code fetches them: at the next start, or within an hour in a running interactive session. You can also verify that managed permission rules are active by having a user run `/permissions` to view their effective permission rules.96To confirm that settings are being applied, ask a user to restart Claude Code. If the configuration includes settings that trigger the [security approval dialog](#security-approval-dialogs), the user sees a prompt describing the managed settings the next time Claude Code fetches them: at the next start, or within an hour in a running interactive session. You can also verify that managed permission rules are active by having a user run `/permissions` to view their effective permission rules.

97 97

98In a session, have the user run `/status`. The [`Setting sources` line](https://code.claude.com/docs/en/managed-settings#read-the-source-in-/status) lists `Enterprise managed settings` with `remote` in parentheses when server-managed settings apply.

98To check the fetch outcome on a specific machine, have the user run `claude doctor` and read the `Managed settings (remote)` line. Requires Claude Code v2.1.248 or later. The line reports one of four outcomes:100To check the fetch outcome on a specific machine, have the user run `claude doctor` and read the `Managed settings (remote)` line. Requires Claude Code v2.1.248 or later. The line reports one of four outcomes:

99 101

100* The delivered settings loaded102* The delivered settings loaded

247* If the gateway answers an attended interactive launch with a `401` and this setting is off, the gateway has ended that sign-in. Claude Code prints [`Cloud gateway session expired — run /login to reconnect.`](https://code.claude.com/docs/en/errors#cloud-gateway-session-expired) and opens the session signed out of the gateway until the user runs `/login`.249* If the gateway answers an attended interactive launch with a `401` and this setting is off, the gateway has ended that sign-in. Claude Code prints [`Cloud gateway session expired — run /login to reconnect.`](https://code.claude.com/docs/en/errors#cloud-gateway-session-expired) and opens the session signed out of the gateway until the user runs `/login`.

248* When the fetch fails in any other way, or in any other kind of launch except a `claude auth` subcommand, the client exits with an error.250* When the fetch fails in any other way, or in any other kind of launch except a `claude auth` subcommand, the client exits with an error.

249 251

250When this setting is active in a session that fetches server-managed settings, the CLI blocks at startup until remote settings are freshly fetched. If the fetch fails, the CLI exits rather than proceeding without the policy. This setting self-perpetuates: once delivered from the server, it is also cached locally so that subsequent startups enforce the same behavior even before the first successful fetch of a new session. A session that [doesn't fetch server-managed settings](#platform-availability) starts without waiting.252When this setting is active in a session that fetches server-managed settings, the CLI blocks at startup until remote settings are freshly fetched. If the fetch fails, the CLI exits rather than proceeding without the policy. A session that [doesn't fetch server-managed settings](#platform-availability) starts without waiting.

251 253

252To enable this, add the key to your managed settings configuration:254To enable this, add the key to your managed settings configuration:

253 255

259 261

260You can also set this key in an [endpoint-managed](https://code.claude.com/docs/en/managed-settings.md#delivery-mechanisms) MDM profile or system `managed-settings.json` file to enforce fail-closed behavior on first launch, before any server payload has arrived. This flag is an exception to the [precedence rule](#settings-precedence) above: Claude Code honors it when any admin-controlled managed source sets it, even if a cached server-managed payload is also present, so it doesn't ignore an MDM-delivered value when server-managed settings exist.262You can also set this key in an [endpoint-managed](https://code.claude.com/docs/en/managed-settings.md#delivery-mechanisms) MDM profile or system `managed-settings.json` file to enforce fail-closed behavior on first launch, before any server payload has arrived. This flag is an exception to the [precedence rule](#settings-precedence) above: Claude Code honors it when any admin-controlled managed source sets it, even if a cached server-managed payload is also present, so it doesn't ignore an MDM-delivered value when server-managed settings exist.

261 263

264On later startups, Claude Code reads a server-delivered value from the cached settings, so the setting is active before the new session's first fetch. To keep the setting active without relying on the cached copy, also set the key in an endpoint-managed source.

265

262When a [`policyHelper`](https://code.claude.com/docs/en/settings-reference#policyhelper) supplies managed settings, its output replaces every other managed source for the keys Claude Code reads after startup. For the sources Claude Code reads this key from, see [its settings entry](https://code.claude.com/docs/en/settings-reference.md#forceremotesettingsrefresh). The `policyHelper` entry says which sources Claude Code reads the helper from and when it runs.266When a [`policyHelper`](https://code.claude.com/docs/en/settings-reference#policyhelper) supplies managed settings, its output replaces every other managed source for the keys Claude Code reads after startup. For the sources Claude Code reads this key from, see [its settings entry](https://code.claude.com/docs/en/settings-reference.md#forceremotesettingsrefresh). The `policyHelper` entry says which sources Claude Code reads the helper from and when it runs.

263 267

264The settings fetch also sends a `Cache-Control: no-cache` header so intermediate HTTP proxies don't serve a stale response.268The settings fetch also sends a `Cache-Control: no-cache` header so intermediate HTTP proxies don't serve a stale response.

settings.md +2 −2

Details

66 66

67### Share settings with your team67### Share settings with your team

68 68

69Commit `.claude/settings.json` so everyone who clones the repository gets the same permissions, hooks, and plugins. Each teammate can still override it for themselves in their own `.claude/settings.local.json`, so personal exceptions don't need a commit. For a complete team file, see [a team's shared settings](https://code.claude.com/docs/en/settings-example.md#a-teams-shared-settings).69Commit `.claude/settings.json` so everyone who clones the repository gets the same permissions, hooks, and plugin settings. Each teammate can still override it for themselves in their own `.claude/settings.local.json`, so personal exceptions don't need a commit. For a complete team file, see [a team's shared settings](https://code.claude.com/docs/en/settings-example.md#a-teams-shared-settings).

70 70

71Some of what you commit waits until each teammate [trusts the folder](https://code.claude.com/docs/en/permissions.md#project-allow-rules-and-workspace-trust), and a few keys never take effect from a repository file; [Troubleshoot a setting that doesn't apply](#common-cases) covers both.71Some of what you commit waits until each teammate [trusts the folder](https://code.claude.com/docs/en/permissions.md#project-allow-rules-and-workspace-trust), and a few keys never take effect from a repository file; [Troubleshoot a setting that doesn't apply](#common-cases) covers both.

72 72

199* **Settings Error**: a user, project, or local file has invalid JSON or a value the schema rejects. At the start of an interactive session Claude Code shows a dialog that lets you fix the file with Claude's help, exit, or continue without the broken settings.199* **Settings Error**: a user, project, or local file has invalid JSON or a value the schema rejects. At the start of an interactive session Claude Code shows a dialog that lets you fix the file with Claude's help, exit, or continue without the broken settings.

200* **Settings Warning**: only individual entries fail, such as a malformed permission rule or an unknown hook event name. Claude Code skips those values and keeps the rest of the file in effect.200* **Settings Warning**: only individual entries fail, such as a malformed permission rule or an unknown hook event name. Claude Code skips those values and keeps the rest of the file in effect.

201* **Managed settings**: Claude Code keeps enforcing the rest of the file. [Invalid entries in managed settings](https://code.claude.com/docs/en/managed-settings.md#invalid-entries-in-managed-settings) says what it drops and which keys fall back to a stricter value until you fix them. For a managed settings document that isn't valid JSON, see [Managed settings document could not be parsed](https://code.claude.com/docs/en/errors.md#managed-settings-document-could-not-be-parsed).201* **Managed settings**: Claude Code keeps enforcing the rest of the file. [Invalid entries in managed settings](https://code.claude.com/docs/en/managed-settings.md#invalid-entries-in-managed-settings) says what it drops and which keys fall back to a stricter value until you fix them. For a managed settings document that isn't valid JSON, see [Managed settings document could not be parsed](https://code.claude.com/docs/en/errors.md#managed-settings-document-could-not-be-parsed).

202* **Configuration error**: [`~/.claude.json`](https://code.claude.com/docs/en/claude-directory#ce-claude-json) can't be parsed. A `claude -p` run exits, and your file is unchanged. See [Configuration error in \~/.claude.json](https://code.claude.com/docs/en/errors.md#configuration-error-in-claude-json) to restore an earlier copy. Claude Code copies the broken file to `~/.claude/backups/.claude.json.corrupted.<timestamp>`, and in an interactive session asks whether to exit and fix it or reset to the default configuration. When the file is blank and there's no backup to restore, Claude Code starts with default settings.202* **Configuration error**: [`~/.claude.json`](https://code.claude.com/docs/en/claude-directory#ce-claude-json) can't be parsed. A `claude -p` run exits. See [Configuration error in \~/.claude.json](https://code.claude.com/docs/en/errors.md#configuration-error-in-claude-json) to restore an earlier copy. Claude Code copies the broken file to `~/.claude/backups/.claude.json.corrupted.<timestamp>`, and in an interactive session asks whether to exit and fix it or reset to the default configuration. When the file is blank and there's no backup to restore, Claude Code starts with default settings.

203 203

204After you continue, run `/status` to see the affected files and `claude doctor` for the details of each error.204After you continue, run `/status` to see the affected files and `claude doctor` for the details of each error.

205 205

settings-reference.md +16 −18

Details

231| [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) | Block [skills](https://code.claude.com/docs/en/skills.md), [agents](https://code.claude.com/docs/en/sub-agents.md), [hooks](https://code.claude.com/docs/en/hooks.md), and [MCP servers](https://code.claude.com/docs/en/mcp.md) from user and project sources | Plugins and skills | Managed |231| [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) | Block [skills](https://code.claude.com/docs/en/skills.md), [agents](https://code.claude.com/docs/en/sub-agents.md), [hooks](https://code.claude.com/docs/en/hooks.md), and [MCP servers](https://code.claude.com/docs/en/mcp.md) from user and project sources | Plugins and skills | Managed |

236| [`subagentPromptCacheTtl`](#subagentpromptcachettl) | Choose the [prompt cache lifetime](https://code.claude.com/docs/en/prompt-caching.md#cache-lifetime) for subagents and other requests outside the main conversation | Model and responses | Any file |236| [`subagentPromptCacheTtl`](#subagentpromptcachettl) | Choose the [prompt cache lifetime](https://code.claude.com/docs/en/prompt-caching.md#cache-lifetime) for subagents and other requests outside the main conversation | Model and responses | Any file |

238| [`switchModelsOnFlag`](#switchmodelsonflag) | Switch models automatically or pause when a [safety classifier](https://code.claude.com/docs/en/model-config.md#ask-before-switching) flags a request | Model and responses | Any file |238| [`switchModelsOnFlag`](#switchmodelsonflag) | Switch models automatically or pause when a [safety classifier](https://code.claude.com/docs/en/model-config.md#ask-before-switching) flags a request | Model and responses | Any file |

289}289}

290```290```

291 291

292The key has no effect on providers where the advisor [isn't available](https://code.claude.com/docs/en/advisor.md#requirements), such as Amazon Bedrock and Claude Platform on AWS. `"fable"` requires [Fable access](https://code.claude.com/docs/en/advisor.md#choose-an-advisor-model).292The key has no effect on providers where the advisor [isn't available](https://code.claude.com/docs/en/advisor.md#requirements), such as Amazon Bedrock. On Claude Platform on AWS, the key requires Claude Code v2.1.300 or later. `"fable"` requires [Fable access](https://code.claude.com/docs/en/advisor.md#choose-an-advisor-model).

293 293

294### `alwaysThinkingEnabled`294### `alwaysThinkingEnabled`

295 295

449 449

450Turn [fast mode](https://code.claude.com/docs/en/fast-mode.md) on for sessions where it's available, for interactive work such as rapid iteration or live debugging where you want speed at a higher cost per token. You don't usually edit this key yourself. Running `/fast` writes `fastMode: true` to `~/.claude/settings.json`, and running it again to turn fast mode off removes the key.450Turn [fast mode](https://code.claude.com/docs/en/fast-mode.md) on for sessions where it's available, for interactive work such as rapid iteration or live debugging where you want speed at a higher cost per token. You don't usually edit this key yourself. Running `/fast` writes `fastMode: true` to `~/.claude/settings.json`, and running it again to turn fast mode off removes the key.

451 451

452Only Fable 5.2, Opus 5.5, Opus 5, and Opus 4.8 support fast mode. Running `/fast` from another model switches you to Opus, and switching to an unsupported model turns fast mode off. See [Switch models while fast mode is on](https://code.claude.com/docs/en/fast-mode.md#switch-models-while-fast-mode-is-on).452On the Anthropic API, only Fable 5.2, Opus 5.5, Opus 5, and Opus 4.8 support fast mode. Running `/fast` from another model switches you to Opus, and switching to an unsupported model turns fast mode off. See [Switch models while fast mode is on](https://code.claude.com/docs/en/fast-mode.md#switch-models-while-fast-mode-is-on). On Google Cloud's Agent Platform, [`/fast` switches you to Fable 5.2](https://code.claude.com/docs/en/fast-mode#use-fast-mode-on-agent-platform) instead and doesn't write this key, and Claude Code ignores a saved `true`.

453 453

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

455* **Type**: Boolean455* **Type**: Boolean

1263 1263

1264Skip the confirmation dialog Claude Code shows before a session enters `bypassPermissions` mode, whether from `--dangerously-skip-permissions` or from `defaultMode: "bypassPermissions"`. Claude Code writes `true` here in your user settings when you accept that dialog once.1264Skip the confirmation dialog Claude Code shows before a session enters `bypassPermissions` mode, whether from `--dangerously-skip-permissions` or from `defaultMode: "bypassPermissions"`. Claude Code writes `true` here in your user settings when you accept that dialog once.

1265 1265

1266* **Scope**: [`User, local, or managed`](#scopes). An untrusted repository can't skip the dialog for you.1266* **Scope**: [`User, local, or managed`](#scopes), and files passed with `--settings`. [Background sessions](https://code.claude.com/docs/en/permission-modes.md#bypass-permissions-ignored-in-a-background-session) count only user and managed settings. An untrusted repository can't skip the dialog for you.

1267* **Type**: Boolean1267* **Type**: Boolean

1268 * `true`: Claude Code skips the confirmation dialog before a session enters `bypassPermissions` mode1268 * `true`: Claude Code skips the confirmation dialog before a session enters `bypassPermissions` mode

1269 * `false`: the same as unset; the dialog appears unless another of these files sets `true`1269 * `false`: the same as unset; the dialog appears unless another of these files sets `true`

3193 3193

3194### `syntaxHighlightingDisabled`3194### `syntaxHighlightingDisabled`

3195 3195

3196Claude Code colors code by language in the diffs, code blocks, and file previews it shows in the terminal, with its built-in highlighter; no plugin or language server is involved. Set this key to `true` to show them as plain text instead, for example if the colors clash with your terminal theme or slow a screen reader.3196Claude Code colors code by language in the diffs, code blocks, and file previews it shows in the terminal, with its built-in highlighter. Set this key to `true` to show them as plain text instead, for example if the colors clash with your terminal theme or slow a screen reader.

3197 3197

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

3199* **Type**: Boolean3199* **Type**: Boolean

4171 4171

4172### `strictPluginOnlyCustomization`4172### `strictPluginOnlyCustomization`

4173 4173

4174Block skills, agents, hooks, and MCP servers from user and project sources, so they can come only from plugins or managed settings. Combine it with [`strictKnownMarketplaces`](#strictknownmarketplaces) to control the full customization supply chain: the marketplace allowlist controls which plugins users can install.4174Block skills, agents, hooks, and MCP servers from user and project sources. Combine it with [`strictKnownMarketplaces`](#strictknownmarketplaces) to choose which marketplaces users can install plugins from. Add [`disableSideloadFlags`](#disablesideloadflags) to reject the CLI flags that sideload plugins, agents, and MCP servers for a single run.

4175 4175

4176* **Scope**: [`Managed`](#scopes)4176* **Scope**: [`Managed`](#scopes)

4177* **Type**: `true` to lock all four kinds of customization, or an array naming the kinds to lock, from `"skills"`, `"agents"`, `"hooks"`, and `"mcp"`4177* **Type**: `true` to lock all of them, or an array naming the ones to lock, from `"skills"`, `"agents"`, `"hooks"`, and `"mcp"`

4178* **Default**: unset, so nothing is locked4178* **Default**: unset, so nothing is locked

4179 4179

4180This example locks skills and hooks and leaves agents and MCP servers unlocked:4180This example locks skills and hooks and leaves agents and MCP servers unlocked:

4277Each scope serves a different purpose:4277Each scope serves a different purpose:

4278 4278

4279* **User settings**: your personal plugin preferences4279* **User settings**: your personal plugin preferences

4280* **Project settings**: plugins shared with everyone in the repository4280* **Project settings**: plugins turned on for everyone in the repository. This doesn't install them, so each user [installs them](https://code.claude.com/docs/en/plugins/org.md#require-plugins-per-repository).

4281* **Local settings**: per-machine overrides, gitignored when Claude Code saves a setting there4281* **Local settings**: per-machine overrides, gitignored when Claude Code saves a setting there

4282* **Managed settings**: organization-wide policy. A plugin set to `false` here is blocked from installation at every scope and hidden from the marketplace4282* **Managed settings**: organization-wide policy. A plugin set to `false` here is blocked from installation at every scope and hidden from the marketplace

4283 4283

4284Project settings take precedence over user settings, so setting a plugin to `false` in `~/.claude/settings.json` doesn't disable a plugin that the project's `.claude/settings.json` enables. To opt out of a project-enabled plugin on your machine, set it to `false` in `.claude/settings.local.json` instead. Plugins force-enabled by managed settings can't be disabled this way, since managed settings override local settings.4284Project settings take precedence over user settings, so setting a plugin to `false` in `~/.claude/settings.json` doesn't disable a plugin that the project's `.claude/settings.json` enables. To opt out of a project-enabled plugin on your machine, set it to `false` in `.claude/settings.local.json` instead. Plugins force-enabled by managed settings can't be disabled this way, since managed settings override local settings.

4285 4285

4286Enabling a plugin from an external source such as a GitHub repository or npm package in a project's `.claude/settings.json` doesn't install it for other people. On every path that loads plugins, Claude Code reports the plugin as not installed until each user [installs it themselves](https://code.claude.com/docs/en/plugins/org.md#require-plugins-per-repository).

~~4287~~

4288### `extraKnownMarketplaces`4286### `extraKnownMarketplaces`

4289 4287

4290Register additional plugin marketplaces by name, so that people who open the repository, or everyone your managed settings reach, get the marketplace without adding it themselves. Claude Code registers each marketplace it doesn't already know. Whether a plugin that [`enabledPlugins`](#enabledplugins) names from it installs depends on the plugin's source and which file enables it; that entry has the rules.4288Register additional plugin marketplaces by name, so that people who open the repository, or everyone your managed settings reach, get the marketplace without adding it themselves. Claude Code registers each marketplace it doesn't already know. Whether a plugin that [`enabledPlugins`](#enabledplugins) names from it installs depends on the plugin's source and which file enables it; [Enabled in project settings but not installed](https://code.claude.com/docs/en/plugins/loading.md#enabled-in-project-settings-but-not-installed) has the rules.

4291 4289

4292* **Scope**: [`Any file`](#scopes). Claude Code honors entries in a repository's `.claude/settings.json` or `.claude/settings.local.json` only after you accept the workspace trust dialog for that folder; in a folder you haven't trusted, including a `-p` run there, it ignores them without a message.4290* **Scope**: [`Any file`](#scopes). Claude Code honors entries in a repository's `.claude/settings.json` or `.claude/settings.local.json` only after you accept the workspace trust dialog for that folder; in a folder you haven't trusted, including a `-p` run there, it ignores them without a message.

4293* **Type**: object mapping a marketplace name to an object with a `source` object and an optional `autoUpdate` Boolean4291* **Type**: object mapping a marketplace name to an object with a `source` object and an optional `autoUpdate` Boolean

4673 4671

4674### `crossSessionInbound`4672### `crossSessionInbound`

4675 4673

4676Choose what this session does with [messages arriving from your other Claude Code sessions](https://code.claude.com/docs/en/cross-session-messaging.md#control-inbound-messages). When no value applies, Claude Code decides per message from the two sessions' permission-mode classes. Requires Claude Code v2.1.224 or later.4674Choose what this session does with [messages arriving from your other Claude Code sessions](https://code.claude.com/docs/en/cross-session-messaging.md#control-inbound-messages). When no value applies, Claude Code decides per message from the two sessions' permission-mode classes.

4677 4675

4678* **Scope**: [`Any file`](#scopes). A project or local value applies only when it's stricter than the value managed settings, the `--settings` flag, or user settings give.4676* **Scope**: [`Any file`](#scopes). A project or local value applies only when it's stricter than the value managed settings, the `--settings` flag, or user settings give.

4679* **Type**: string, one of:4677* **Type**: string, one of:

5280 5278

5281### `forceLoginMethod`5279### `forceLoginMethod`

5282 5280

5283Restrict which kind of account people can log in with. Set `"claudeai"` to allow only claude.ai accounts, `"console"` to allow only Claude Console accounts, or `"gateway"` to send people to a [cloud gateway](https://code.claude.com/docs/en/claude-apps-gateway) instead of a first-party login. Administrators set it in managed settings and pair it with [`forceLoginOrgUUID`](#forceloginorguuid) to keep developers' claude.ai logins inside one organization.5281Restrict which kind of account people can log in with: `"claudeai"` for claude.ai sign-in or `"console"` for Claude Console sign-in. Set `"gateway"` to send people to a [cloud gateway](https://code.claude.com/docs/en/claude-apps-gateway) instead of a first-party login. Administrators set it in managed settings and pair it with [`forceLoginOrgUUID`](#forceloginorguuid) to keep developers' claude.ai logins inside one organization.

5284 5282

5285If you set it to `"claudeai"` in any settings file, Claude Code also stops offering the [keyless Console sign-in](https://code.claude.com/docs/en/authentication.md#sign-in-without-an-api-key) in the sessions that file applies to. With `"console"` alone, people can still reach the keyless sign-in after a failed login. To stop Claude Code offering it, see [Stop offering the keyless sign-in on managed machines](https://code.claude.com/docs/en/authentication.md#stop-offering-the-keyless-sign-in-on-managed-machines), which also lists what else `forceLoginOrgUUID` changes.5283If you set it to `"claudeai"` in any settings file, Claude Code also stops offering the [keyless Console sign-in](https://code.claude.com/docs/en/authentication.md#sign-in-without-an-api-key) in the sessions that file applies to. With `"console"` alone, people can still reach the keyless sign-in after a failed login. To stop Claude Code offering it, see [Stop offering the keyless sign-in on managed machines](https://code.claude.com/docs/en/authentication.md#stop-offering-the-keyless-sign-in-on-managed-machines), which also lists what else `forceLoginOrgUUID` changes.

5286 5284

5287* **Scope**: [`Any file`](#scopes). Claude Code honors `"gateway"` from the same sources as [`forceLoginGatewayUrl`](#forcelogingatewayurl) and treats it as unset everywhere else.5285* **Scope**: [`Any file`](#scopes). Claude Code honors `"gateway"` from the same sources as [`forceLoginGatewayUrl`](#forcelogingatewayurl) and treats it as unset everywhere else.

5288* **Type**: string, one of:5286* **Type**: string, one of:

5289 * `"claudeai"`: only claude.ai accounts can log in5287 * `"claudeai"`: claude.ai sign-in

5290 * `"console"`: only Claude Console accounts can log in5288 * `"console"`: Claude Console sign-in

5291 * `"gateway"`: Claude Code sends people to a cloud gateway instead of a first-party login5289 * `"gateway"`: Claude Code sends people to a cloud gateway instead of a first-party login

5292* **Default**: unset, so people pick a login method5290* **Default**: unset, so people pick a login method

5293 5291

skills.md +1 −1

Details

22 22

23Claude Code includes a set of bundled skills, such as `/doctor`, `/code-review`, `/batch`, `/debug`, `/loop`, and `/claude-api`. Bundled skills are prompt-based: they give Claude detailed instructions and let it orchestrate the work using its tools. Most built-in commands instead execute fixed logic directly.23Claude Code includes a set of bundled skills, such as `/doctor`, `/code-review`, `/batch`, `/debug`, `/loop`, and `/claude-api`. Bundled skills are prompt-based: they give Claude detailed instructions and let it orchestrate the work using its tools. Most built-in commands instead execute fixed logic directly.

24 24

25You invoke a bundled skill the same way as any other skill, by typing `/` followed by the skill name. Claude invokes some bundled skills automatically when relevant; others, including `/verify`, run only when you invoke them, which keeps you in control of when these longer-running checks spend time and tokens.25You invoke a bundled skill by typing `/` followed by the skill name. Claude invokes some bundled skills automatically when relevant; others, including [`/verify`](#run-and-verify-your-app), run only when you invoke them.

26 26

27Most bundled skills are available in every session. A few depend on a specific feature: `/workflow-authoring`, for example, is available only when [dynamic workflows](https://code.claude.com/docs/en/workflows.md) are enabled.27Most bundled skills are available in every session. A few depend on a specific feature: `/workflow-authoring`, for example, is available only when [dynamic workflows](https://code.claude.com/docs/en/workflows.md) are enabled.

28 28

terminal-config.md +1 −1

Details

346 346

347Claude Code keeps the content behind each `[Pasted text #N]` placeholder under `~/.claude/paste-cache/`, so when you recall a prompt from [command history](https://code.claude.com/docs/en/interactive-mode.md#command-history) and resubmit it, the full pasted content is sent again, including in a later session.347Claude Code keeps the content behind each `[Pasted text #N]` placeholder under `~/.claude/paste-cache/`, so when you recall a prompt from [command history](https://code.claude.com/docs/en/interactive-mode.md#command-history) and resubmit it, the full pasted content is sent again, including in a later session.

348 348

349Cache files older than [`cleanupPeriodDays`](https://code.claude.com/docs/en/settings-reference#cleanupperioddays) are deleted under the [retention sweep rules](https://code.claude.com/docs/en/claude-directory.md#cleaned-up-automatically), so a recalled prompt can reference pasted text that no longer exists. When you submit such a prompt, Claude Code never sends the literal `[Pasted text #N]` string, and shows a notification naming the missing paste:349Cache files older than [`cleanupPeriodDays`](https://code.claude.com/docs/en/settings-reference#cleanupperioddays) are deleted under the [retention sweep rules](https://code.claude.com/docs/en/claude-directory.md#cleaned-up-automatically), so a recalled prompt can reference pasted text that no longer exists. When you submit such a prompt, Claude Code doesn't send the literal `[Pasted text #N]` string, and shows a notification naming the missing paste:

350 350

351* In a plain prompt with text remaining, Claude Code removes the placeholder and sends the remaining text.351* In a plain prompt with text remaining, Claude Code removes the placeholder and sends the remaining text.

352* In a [shell mode](https://code.claude.com/docs/en/interactive-mode.md#shell-mode-with-prefix) command or a `/` command, where the removal would change what runs, and in any prompt the removal leaves empty, Claude Code cancels the submission and keeps the original text in the input, with the placeholder still in it. Delete the placeholder or edit the command, then resubmit.352* In a [shell mode](https://code.claude.com/docs/en/interactive-mode.md#shell-mode-with-prefix) command or a `/` command, where the removal would change what runs, and in any prompt the removal leaves empty, Claude Code cancels the submission and keeps the original text in the input, with the placeholder still in it. Delete the placeholder or edit the command, then resubmit.

troubleshoot-install.md +12 −8

Details

29| `EACCES: permission denied` during install | [Fix the install directory's permissions](#permission-errors-during-installation) |29| `EACCES: permission denied` during install | [Fix the install directory's permissions](#permission-errors-during-installation) |

30| `TLS connect error` or `SSL/TLS secure channel` | [Update CA certificates](#tls-or-ssl-connection-errors) |30| `TLS connect error` or `SSL/TLS secure channel` | [Update CA certificates](#tls-or-ssl-connection-errors) |

31| `CRYPT_E_NO_REVOCATION_CHECK` or `CRYPT_E_REVOCATION_OFFLINE` | [Work around blocked revocation checks](#tls-or-ssl-connection-errors) |31| `CRYPT_E_NO_REVOCATION_CHECK` or `CRYPT_E_REVOCATION_OFFLINE` | [Work around blocked revocation checks](#tls-or-ssl-connection-errors) |

~~32| `Failed to fetch version` or can't reach download server | [Check network and proxy settings](#check-network-connectivity) |~~32| `Failed to fetch version` or can't reach download server | [Check network and proxy settings](#check-network-connectivity), or for a certificate error, [configure corporate CA certificates](#tls-or-ssl-connection-errors) |

33| `The connection dropped while downloading the update` or `Download timed out: exceeded the total deadline` | [Run the update again or set your proxy](#the-connection-dropped-while-downloading-the-update) |33| `The connection dropped while downloading the update` or `Download timed out: exceeded the total deadline` | [Run the update again or set your proxy](#the-connection-dropped-while-downloading-the-update) |

34| `Release verification failed for Claude Code` | [Run `claude update` or `claude install` again](#release-verification-failed) |34| `Release verification failed for Claude Code` | [Run `claude update` or `claude install` again](#release-verification-failed) |

35| `Auto-update failed · Run claude doctor` in red in the session footer | [Run `claude update` from your shell](#auto-update-failed) |35| `Auto-update failed · Run claude doctor` in red in the session footer | [Run `claude update` from your shell](#auto-update-failed) |

94* `403`: usually a proxy or network filter blocking the host, or Claude Code is [not available in your region](https://www.anthropic.com/supported-countries)94* `403`: usually a proxy or network filter blocking the host, or Claude Code is [not available in your region](https://www.anthropic.com/supported-countries)

95* `5xx`: usually a temporary service issue; wait a few minutes and retry95* `5xx`: usually a temporary service issue; wait a few minutes and retry

96 96

~~97If you see no output, `Could not resolve host`, or a connection timeout, your network is blocking the connection. Common causes:~~97If you see no output, or the installer shows `Could not resolve host` or a connection timeout, the connection failed, so check for these causes:

98 98

99* Corporate firewalls or proxies blocking `downloads.claude.ai`99* Corporate firewalls or proxies blocking `downloads.claude.ai`

100* Regional network restrictions: try a VPN or alternative network100* Regional network restrictions: try a VPN or alternative network

101* TLS/SSL issues: update your system's CA certificates, or check if `HTTPS_PROXY` is configured101* TLS/SSL issues: see [TLS or SSL connection errors](#tls-or-ssl-connection-errors)

102 102

103If you're behind a corporate proxy, set `HTTPS_PROXY` and `HTTP_PROXY` to your proxy's address before installing. Ask your IT team for the proxy URL if you don't know it, or check your browser's proxy settings.103If you're behind a corporate proxy, set `HTTPS_PROXY` and `HTTP_PROXY` to your proxy's address before installing. Ask your IT team for the proxy URL if you don't know it, or check your browser's proxy settings.

104 104

566 irm https://claude.ai/install.ps1 | iex566 irm https://claude.ai/install.ps1 | iex

567 ```567 ```

568 568

5693. **Check for proxy or firewall interference**: corporate proxies that perform TLS inspection can cause these errors, including `unable to get local issuer certificate` and `SELF_SIGNED_CERT_IN_CHAIN`. For the install step, make the install download trust your corporate proxy's CA:5693. **Check for proxy or firewall interference**: corporate proxies that perform TLS inspection can cause these errors, including `unable to get local issuer certificate`, `unable to verify the first certificate`, and `SELF_SIGNED_CERT_IN_CHAIN`. Make the install download trust your corporate proxy's CA:

570 570

571 > [tab] macOS/Linux571 > [tab] macOS/Linux

572 >572 >

573 > Set `CURL_CA_BUNDLE` for the install script's `curl` downloads, and [`NODE_EXTRA_CA_CERTS`](https://code.claude.com/docs/en/network-config#custom-ca-certificates) for the `claude install` command the script then runs. Ask your IT team for a PEM file with your proxy's root CA certificate if you don't have it. This example sets both to your proxy's CA file and runs the script in the same terminal:

574 >

573 > ```bash theme={null}575 > ```bash theme={null}

574 > curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash576 > export CURL_CA_BUNDLE=/path/to/corporate-ca.pem

577 > export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

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

575 > ```579 > ```

580 >

581 > If the install still fails with one of those certificate errors, ask your IT team for a file with both the public root certificates and your proxy's full CA chain. Then set both variables to that file.

576 582

577 > [tab] Windows PowerShell583 > [tab] Windows PowerShell

578 >584 >

596 > $env:NODE_EXTRA_CA_CERTS = 'C:\path\to\corporate-ca.pem'602 > $env:NODE_EXTRA_CA_CERTS = 'C:\path\to\corporate-ca.pem'

597 > ```603 > ```

598 604

599 Ask your IT team for the certificate file if you don't have it. You can also try on a direct connection to confirm the proxy is the cause.

~~600~~

6014. **On Windows, work around blocked revocation checks**. The errors `CRYPT_E_NO_REVOCATION_CHECK (0x80092012)` and `CRYPT_E_REVOCATION_OFFLINE (0x80092013)` mean curl reached the server but your network blocks the certificate revocation lookup, which is common behind corporate firewalls. If the failing command is the `curl` that downloads `install.cmd`, rerun it from a Command Prompt with `--ssl-revoke-best-effort` added:6054. **On Windows, work around blocked revocation checks**. The errors `CRYPT_E_NO_REVOCATION_CHECK (0x80092012)` and `CRYPT_E_REVOCATION_OFFLINE (0x80092013)` mean curl reached the server but your network blocks the certificate revocation lookup, which is common behind corporate firewalls. If the failing command is the `curl` that downloads `install.cmd`, rerun it from a Command Prompt with `--ssl-revoke-best-effort` added:

602 ```batch theme={null}606 ```batch theme={null}

603 curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd607 curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

610 614

611### `Failed to fetch version from downloads.claude.ai`615### `Failed to fetch version from downloads.claude.ai`

612 616

613The installer couldn't reach the download server. This typically means `downloads.claude.ai` is blocked on your network. See [Check network connectivity](#check-network-connectivity).617The end of the message gives the reason. If it's a certificate error such as `unable to verify the first certificate`, see [TLS or SSL connection errors](#tls-or-ssl-connection-errors). For any other reason, see [Check network connectivity](#check-network-connectivity).

614 618

615### The connection dropped while downloading the update619### The connection dropped while downloading the update

616 620

web-quickstart.md +5 −3

Details

80* **Pro, Max, and Ultra**: you get an environment named **Default** automatically.80* **Pro, Max, and Ultra**: you get an environment named **Default** automatically.

81* **Team and Enterprise**: onboarding shows a **Create your first cloud environment** form. Leave the prefilled name and network access unchanged and click **Create & finish** to create the **Default** environment. If an Owner has turned on [Quick setup](https://code.claude.com/docs/en/claude-code-on-the-web.md#quick-setup-for-team-and-enterprise), onboarding creates **Default** for you instead.81* **Team and Enterprise**: onboarding shows a **Create your first cloud environment** form. Leave the prefilled name and network access unchanged and click **Create & finish** to create the **Default** environment. If an Owner has turned on [Quick setup](https://code.claude.com/docs/en/claude-code-on-the-web.md#quick-setup-for-team-and-enterprise), onboarding creates **Default** for you instead.

82 82

83**Default** uses [`Trusted` network access](https://code.claude.com/docs/en/cloud-environments#access-levels): sessions reach [common package registries](https://code.claude.com/docs/en/cloud-environments.md#default-allowed-domains) and other allowlisted domains, and nothing else through the session's network. See [Installed tools](https://code.claude.com/docs/en/cloud-environments.md#installed-tools) for what's available without any configuration.83**Default** uses [**Limited** network access](https://code.claude.com/docs/en/cloud-environments.md#access-levels): sessions reach [common package registries](https://code.claude.com/docs/en/cloud-environments.md#default-allowed-domains) and other allowlisted domains. See [Installed tools](https://code.claude.com/docs/en/cloud-environments.md#installed-tools) for what's available without any configuration.

84 84

85For a first project, the **Default** environment works as is. To change its network access, add environment variables, or run a [setup script](https://code.claude.com/docs/en/cloud-environments.md#setup-scripts) before sessions start, [edit it or create additional environments](https://code.claude.com/docs/en/cloud-environments.md#configure-your-environment).85For a first project, the **Default** environment works as is. To change its network access, add environment variables, or run a [setup script](https://code.claude.com/docs/en/cloud-environments.md#setup-scripts) before sessions start, [edit it or create additional environments](https://code.claude.com/docs/en/cloud-environments.md#configure-your-environment).

86 86

116/web-setup116/web-setup

117```117```

118 118

119Confirm the prompt to send your `gh` token to your Claude account. On success, Claude Code prints `Connected as <your-github-username>` and opens [claude.ai/code](https://claude.ai/code) in your browser. If you don't have a cloud environment yet, `/web-setup` creates one with Trusted network access and no setup script. You can [edit the environment or add variables](https://code.claude.com/docs/en/cloud-environments.md#configure-your-environment) afterward. Once `/web-setup` completes, you can start cloud sessions from your terminal with [`--cloud`](https://code.claude.com/docs/en/claude-code-on-the-web#from-terminal-to-cloud) or set up recurring tasks with [`/schedule`](https://code.claude.com/docs/en/routines).119Confirm the prompt to send your `gh` token to your Claude account. On success, Claude Code prints `Connected as <your-github-username>` and opens [claude.ai/code](https://claude.ai/code) in your browser.

120

121If you don't have a cloud environment yet, `/web-setup` creates one with the default **Limited** network access and no setup script. You can [edit the environment or add variables](https://code.claude.com/docs/en/cloud-environments.md#configure-your-environment) afterward. Once `/web-setup` completes, you can start cloud sessions from your terminal with [`--cloud`](https://code.claude.com/docs/en/claude-code-on-the-web#from-terminal-to-cloud) or set up recurring tasks with [`/schedule`](https://code.claude.com/docs/en/routines).

120 122

121#### Remove the `/web-setup` token123#### Remove the `/web-setup` token

122 124

246 248

247Common causes:249Common causes:

248 250

249* A package install failed because the registry isn't in your [network access level](https://code.claude.com/docs/en/cloud-environments.md#access-levels). `Trusted` covers most package managers; `None` blocks them all.251* A package install failed because the registry isn't in your [network access level](https://code.claude.com/docs/en/cloud-environments.md#access-levels). **Limited** with **Allow package managers** checked covers most package managers; **None** blocks them all.

250* The script references a file or path that doesn't exist in a fresh clone.252* The script references a file or path that doesn't exist in a fresh clone.

251* A command that works locally needs a different invocation on Ubuntu.253* A command that works locally needs a different invocation on Ubuntu.

252 254

whats-new.md +0 −249 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# What's new~~

~~7> A weekly digest of notable Claude Code features, with code snippets, demos, and context on why they matter.~~

9The weekly dev digest highlights the features most likely to change how you work. Each entry includes runnable code, a short demo, and a link to the full docs. For every bug fix and minor improvement, see the [changelog](https://code.claude.com/docs/en/changelog.md).

~~11**Week 37**~~

~~13September 7–11, 2026~~

~~15**`claude plugin eval`**: run your plugin against a suite of test cases, score the results, and compare against a no-plugin baseline. `claude plugin eval init` drafts the cases and graders for you.~~

17Also this week: pop any **Claude Code Desktop pane** out into its own window and dock it back later; the **`maxEffortLevel`** setting caps the effort level on every provider; and a page that **WebFetch** hasn't finished downloading within five minutes fails instead of hanging.

~~19[Read the Week 37 digest →](https://code.claude.com/docs/en/whats-new/2026-w37.md)~~

~~21**Week 36**~~

~~23August 31 – September 4, 2026~~

~~25**Claude Fable 5.1**: available in Claude Code with a 1M-token context window.~~

27Also this week: on Pro and Max plans, **computer use in the Desktop app** works in the background on macOS while you keep working; in fullscreen rendering, **`/diff`** opens a live panel beside the conversation that refreshes as Claude edits; and **`/skill-doctor`** shows what each of your skills costs in context and how often it gets used.

~~29[Read the Week 36 digest →](https://code.claude.com/docs/en/whats-new/2026-w36.md)~~

~~31**Week 35**~~

~~33August 24–28, 2026~~

~~35**Resume terminal sessions in the Desktop app**: type `/resume` in the Claude Code Desktop prompt box to pick up any session you started from the CLI, with the full conversation and context intact.~~

37Also this week: **Claude-drafted feedback** has Claude write up a feedback report when something goes wrong in a session, which you review and send from `/feedback`; **`--restricted`** starts a session without the command-running tools or your user and project settings, for evaluation harnesses on shared machines; and the **`modelPicker`** setting controls which models the `/model` picker lists.

~~39[Read the Week 35 digest →](https://code.claude.com/docs/en/whats-new/2026-w35.md)~~

~~41**Week 34**~~

~~43August 17–21, 2026~~

45**`/design`**: a research preview that brings Claude Design's artboard workflow into the CLI and Claude Code Desktop, built on artifacts, so Claude drafts editable artboards for your UI and implements the one you pick.

47Also this week: the built-in **Concise output style** makes Claude lead with the result and skip preamble; any machine running `claude remote-control` shows up as a **device card** on your phone so you can start a session on it from the Code tab; and **`ANTHROPIC_DEFAULT_MODEL`** sets the model new sessions start on.

~~49[Read the Week 34 digest →](https://code.claude.com/docs/en/whats-new/2026-w34.md)~~

~~51**Week 33**~~

~~53August 10–14, 2026~~

55**Auto-continue after a usage limit on Desktop**: when you hit your session limit in Claude Code Desktop, check **Auto-continue when limits reset** on the limit card and the app retries the interrupted turn once the limit resets.

57Also this week: **fork mode** is on by default in interactive sessions, so Claude can delegate a side task to a subagent that inherits the full conversation; **GitLab** merge request URLs work with `--worktree` and the `claude agents` view, and marketplaces clone bare `gitlab.com` URLs; and typing **`@`** in the prompt mentions another Claude session by name.

~~59[Read the Week 33 digest →](https://code.claude.com/docs/en/whats-new/2026-w33.md)~~

~~61**Week 32**~~

~~63August 3–7, 2026~~

65**Cross-session messaging**: on macOS and Linux, your Claude Code sessions can now message each other, so Claude passes a finding or a decision from one session to another instead of you re-explaining it.

67Also this week: **self-hosted environments** run Claude Code cloud sessions on infrastructure your organization operates, in public beta on Team and Enterprise plans; **auto mode** becomes the default permission mode for new sessions on Pro, Max, and Team plans starting August 14; and the **VS Code extension** gets Focus view.

~~69[Read the Week 32 digest →](https://code.claude.com/docs/en/whats-new/2026-w32.md)~~

~~71**Week 30**~~

~~73July 20–24, 2026~~

~~75**Claude Opus 5**: the new default Opus model in Claude Code, with a 1M-token context window and fast mode at \$10/\$50 per MTok.~~

77Also this week: **Claude Code Desktop** opens an iOS Simulator pane in public beta so Claude can run your app and tap through it while you watch; the **Claude Security plugin** runs a multi-agent vulnerability scan of your codebase and turns the findings you pick into patches you apply yourself; and **`/code-review`** runs as a background subagent.

~~79[Read the Week 30 digest →](https://code.claude.com/docs/en/whats-new/2026-w30.md)~~

~~81**Week 29**~~

~~83July 13–17, 2026~~

85**Artifacts call your MCP connectors**: a published artifact can pull live data and take actions through each viewer's own MCP connectors when they open the page, and this week also adds public sharing links, editor roles on Team and Enterprise, and artifacts created from Claude Tag sessions.

87Also this week: **screen reader mode** replaces the visual terminal interface with plain, linear text for screen readers such as VoiceOver and NVDA; **`/fork`** copies your conversation into a new background session while you keep working; and **auto mode** no longer needs an opt-in variable on Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry.

~~89[Read the Week 29 digest →](https://code.claude.com/docs/en/whats-new/2026-w29.md)~~

~~91**Week 28**~~

~~93July 6–10, 2026~~

95**In-app browser on Desktop**: Claude Code on desktop gets a built-in browser, so Claude can pull up docs, designs, or any other site and interact with pages the same way it does with your local dev server previews.

97Also this week: **`/doctor`** is a full setup checkup that diagnoses issues and can fix them, with `/checkup` as its alias; **auto mode** blocks transcript tampering and asks before `rm -rf` on unresolved variables; and **agent view rows** show a colored state word and a classifier-written headline.

~~99[Read the Week 28 digest →](https://code.claude.com/docs/en/whats-new/2026-w28.md)~~

~~100~~

101**Week 27**

~~102~~

103June 29 – July 3, 2026

~~104~~

105**Claude Sonnet 5**: the new default model for Pro, Team Standard, and Enterprise subscription seats, with top-tier coding and tool use at Sonnet pricing, a native 1M-token context window, and adaptive thinking on by default.

~~106~~

107Also this week: **Claude in Chrome** is generally available on all direct Anthropic plans; **subagents run in the background by default** so Claude keeps working while they run; **Claude Desktop on Linux** lands in beta on Ubuntu and Debian; and **`/radio`** tunes into Claude FM lo-fi radio.

~~108~~

109[Read the Week 27 digest →](https://code.claude.com/docs/en/whats-new/2026-w27.md)

~~110~~

111**Week 26**

~~112~~

113June 22–26, 2026

~~114~~

115**`claude mcp login`**: authenticate a configured MCP server from your shell instead of the interactive `/mcp` menu, and clear its stored credentials later with `claude mcp logout`.

~~116~~

117Also this week: **shell mode responds to command output** (`! npm test` gets an explanation without a second prompt); **`/rewind`** can resume a conversation from before `/clear` was run; and **background subagents** now surface permission prompts in the main session instead of auto-denying.

~~118~~

119[Read the Week 26 digest →](https://code.claude.com/docs/en/whats-new/2026-w26.md)

~~120~~

121**Week 25**

~~122~~

123June 15–19, 2026

~~124~~

125**Artifacts**: turn a session's output into a live, shareable page on claude.ai that updates in place as the session works, now in beta on Team and Enterprise plans.

~~126~~

127Also this week: **deny and ask rules match tool parameters** with `Tool(param:value)`, for example `Agent(model:opus)`; **`/config key=value`** sets any setting from the prompt, in `-p` mode, and from Remote Control; and **auto mode blocks destructive git commands** when you didn't ask to discard local work.

~~128~~

129[Read the Week 25 digest →](https://code.claude.com/docs/en/whats-new/2026-w25.md)

~~130~~

131**Week 24**

~~132~~

133June 8–12, 2026

~~134~~

135**`/cd`**: move the current session to a new working directory mid-conversation without rebuilding the prompt cache.

~~136~~

137Also this week: **sub-agents can spawn their own sub-agents** (background chains are capped at five levels deep); **`--safe-mode`** starts Claude Code with all customizations disabled for troubleshooting; and **`fallbackModel`** configures up to three fallback models tried in order.

~~138~~

139[Read the Week 24 digest →](https://code.claude.com/docs/en/whats-new/2026-w24.md)

~~140~~

141**Week 23**

~~142~~

143June 1–5, 2026

~~144~~

145**Auto mode on Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry**: auto mode is now available on third-party providers for Opus 4.7 and Opus 4.8, replacing permission prompts with background safety checks.

~~146~~

147Also this week: **safer automatic edits** prompt before writing files that can run code in `acceptEdits` mode; **`/plugin list`** prints your installed plugins inline; and **version requirements** let managed deployments require an approved Claude Code version range.

~~148~~

149[Read the Week 23 digest →](https://code.claude.com/docs/en/whats-new/2026-w23.md)

~~150~~

151**Week 22**

~~152~~

153May 25–29, 2026

~~154~~

155**Claude Opus 4.8**: the new default model for Max, Team Premium, Enterprise pay-as-you-go, and Anthropic API accounts, with high effort by default and `/effort xhigh` for the hardest tasks.

~~156~~

157Also this week: **dynamic workflows** orchestrate dozens to hundreds of subagents from a script Claude writes; the **security-guidance plugin** reviews Claude's changes for vulnerabilities as it works; and **fast mode** runs on Opus 4.8 at \$10/\$50 per MTok.

~~158~~

159[Read the Week 22 digest →](https://code.claude.com/docs/en/whats-new/2026-w22.md)

~~160~~

161**Week 21**

~~162~~

163May 18–22, 2026

~~164~~

165**Auto mode on the Pro plan**: auto mode now runs on Pro accounts and supports Sonnet 4.6 alongside Opus, replacing permission prompts with background safety checks.

~~166~~

167Also this week: **`/usage`** breaks down what drives your plan limits by skill, subagent, plugin, and MCP server; the new **`/code-review`** command reports correctness bugs; and **background sessions** appear in `/resume` and stay alive when pinned.

~~168~~

169[Read the Week 21 digest →](https://code.claude.com/docs/en/whats-new/2026-w21.md)

~~170~~

171**Week 20**

~~172~~

173May 11–15, 2026

~~174~~

175**Agent view**: `claude agents` opens one screen for every Claude Code session, showing what's running, what's blocked on you, and what's done.

~~176~~

177Also this week: **`/goal`** keeps Claude working across turns until a completion condition holds; **fast mode** now runs on Opus 4.7 by default; and the **Rewind menu** can compress earlier context with "Summarize up to here".

~~178~~

179[Read the Week 20 digest →](https://code.claude.com/docs/en/whats-new/2026-w20.md)

~~180~~

181**Week 19**

~~182~~

183May 4–8, 2026

~~184~~

185**Plugins load from `.zip` archives and URLs**: `--plugin-dir` now accepts `.zip` files, and `--plugin-url` fetches a plugin archive for the current session.

~~186~~

187Also this week: **`worktree.baseRef`** chooses whether new worktrees branch from the remote default or local `HEAD`; **auto mode hard deny rules** block actions unconditionally regardless of allow exceptions; and **hooks see the active effort level** via `effort.level` and `$CLAUDE_EFFORT`.

~~188~~

189[Read the Week 19 digest →](https://code.claude.com/docs/en/whats-new/2026-w19.md)

~~190~~

191**Week 18**

~~192~~

193April 27 – May 1, 2026

~~194~~

195**Windows without Git Bash**: Git for Windows is no longer required, and Claude Code uses PowerShell as the shell tool when Bash is absent.

~~196~~

197Also this week: **`claude ultrareview`** brings cloud code review to CI and scripts; **`claude project purge`** cleans up local state for a project; and pasting a **PR URL into `/resume`** finds the session that created it.

~~198~~

199[Read the Week 18 digest →](https://code.claude.com/docs/en/whats-new/2026-w18.md)

~~200~~

201**Week 17**

~~202~~

203April 20–24, 2026

~~204~~

205**`/ultrareview`** opens as a public research preview: a fleet of bug-hunting agents runs in the cloud and findings land back in your CLI or Desktop automatically.

~~206~~

207Also this week: **session recap** shows you what happened while a terminal was unfocused; **custom themes** let you build and ship color palettes from `/theme` or a plugin; and **Claude Code on the web** gets a redesign with a new sessions sidebar and drag-and-drop layout.

~~208~~

209[Read the Week 17 digest →](https://code.claude.com/docs/en/whats-new/2026-w17.md)

~~210~~

211**Week 16**

~~212~~

213April 13–17, 2026

~~214~~

215**Claude Opus 4.7** lands as the new default on Max and Team Premium, with a new `xhigh` effort level that's the recommended setting for most coding work and an interactive `/effort` slider to dial it in.

~~216~~

217Also this week: **Routines** on Claude Code on the web fire templated cloud agents from a schedule, GitHub event, or API call; **mobile push notifications** ping your phone when a long task finishes or Claude needs you; `/usage` shows what's driving your limits; and the CLI moves to native binaries.

~~218~~

219[Read the Week 16 digest →](https://code.claude.com/docs/en/whats-new/2026-w16.md)

~~220~~

221**Week 15**

~~222~~

223April 6–10, 2026

~~224~~

225**Ultraplan** enters early preview: draft a plan in the cloud from your CLI, review and comment on it in a web editor, then run it remotely or pull it back local. The first run now auto-creates a cloud environment for you.

~~226~~

227Also this week: the **Monitor** tool streams background events into the conversation so Claude can tail logs and react live, `/loop` self-paces when you omit the interval, `/team-onboarding` packages your setup into a replayable guide, and `/autofix-pr` turns on PR auto-fix from your terminal.

~~228~~

229[Read the Week 15 digest →](https://code.claude.com/docs/en/whats-new/2026-w15.md)

~~230~~

231**Week 14**

~~232~~

233March 30 – April 3, 2026

~~234~~

235**Computer use** comes to the CLI in research preview: Claude can open native apps, click through UI, and verify changes from your terminal. Best for closing the loop on things only a GUI can verify.

~~236~~

237Also this week: `/powerup` interactive lessons, flicker-free alt-screen rendering, a per-tool MCP result-size override up to 500K, and plugin executables on the Bash tool's `PATH`.

~~238~~

239[Read the Week 14 digest →](https://code.claude.com/docs/en/whats-new/2026-w14.md)

~~240~~

241**Week 13**

~~242~~

243March 23–27, 2026

~~244~~

245**Auto mode** lands in research preview: a classifier handles your permission prompts so safe actions run without interruption and risky ones get blocked. The middle ground between approving everything and `--dangerously-skip-permissions`.

~~246~~

247Also this week: computer use in the Desktop app, PR auto-fix on Web, transcript search with `/`, a native PowerShell tool for Windows, and conditional `if` hooks.

~~248~~

249[Read the Week 13 digest →](https://code.claude.com/docs/en/whats-new/2026-w13.md)

whats-new/2026-w13.md +0 −118 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 13 · March 23–27, 2026~~

~~7> Auto mode for hands-off permissions, computer use built in, PR auto-fix in the cloud, transcript search, and a PowerShell tool for Windows.~~

~~9Releases [v2.1.83 → v2.1.85](https://code.claude.com/docs/en/changelog.md#2-1-83)~~

~~106 features · March 23–27~~

~~12Auto mode~~

~~13research preview~~

15Auto mode hands your permission prompts to a classifier. Safe edits and commands run without interrupting you; anything destructive or suspicious gets blocked and surfaced. It's the middle ground between approving every file write and running with `--dangerously-skip-permissions`.

17![Claude Code prompt footer showing 'auto mode on (shift+tab to cycle)' indicator in yellow](https://mintcdn.com/claude-code/CfffsX01JHFnIKvD/images/whats-new/auto-mode.png?fit=max\&auto=format\&n=CfffsX01JHFnIKvD\&q=85\&s=367c9e9d4ba5bc57ec4b935154bf1fbb)

~~19Cycle to auto with Shift+Tab, or set it as your default:~~

~~21```json ~/.claude/settings.json {3} theme={null}~~

~~22{~~

~~23 "permissions": {~~

~~24 "defaultMode": "auto"~~

~~25 }~~

~~26}~~

~~27```~~

~~29[Permission modes guide](https://code.claude.com/docs/en/permission-modes.md)~~

~~31Computer use~~

~~32Desktop~~

34Claude can now control your actual desktop from the Claude Code Desktop app: open native apps, click through the iOS simulator, drive hardware control panels, and verify changes on screen. It's off by default and asks before each action. Best for the things nothing else can reach: apps without an API, proprietary tools, anything that only exists as a GUI.

36![Claude Desktop settings with the Computer use toggle enabled, showing the option to let Claude take screenshots and control your keyboard and mouse in apps you allow](https://mintcdn.com/claude-code/CfffsX01JHFnIKvD/images/whats-new/computer-use.png?fit=max\&auto=format\&n=CfffsX01JHFnIKvD\&q=85\&s=d631de2017edafff463505f8ddbc0f51)

~~38Enable it in Settings, grant the OS permissions, then ask Claude to verify a change end to end:~~

~~40```text title="Claude Code" wrap theme={null}~~

~~41Open the iOS simulator, tap through the onboarding flow, and screenshot each step~~

~~42```~~

~~44[Computer use guide](https://code.claude.com/docs/en/desktop.md#let-claude-use-your-computer)~~

~~46PR auto-fix~~

~~47Web~~

~~49Flip a switch when you open a PR and walk away. Claude watches CI, fixes the failures, handles the nits, and pushes until it's green. No more babysitting a PR through six rounds of lint errors.~~

51![Claude Code web CI panel showing the Auto fix toggle enabled, with description 'Proactively fix CI failures and review comments'](https://mintcdn.com/claude-code/CfffsX01JHFnIKvD/images/whats-new/auto-fix.png?fit=max\&auto=format\&n=CfffsX01JHFnIKvD\&q=85\&s=c62b181c6c5d96929f0b43525f9f3584)

~~53After creating a PR on Claude Code web, toggle Auto fix in the CI panel.~~

~~55[Auto-fix pull requests](https://code.claude.com/docs/en/claude-code-on-the-web.md#auto-fix-pull-requests)~~

~~57Transcript search~~

~~58v2.1.83~~

~~60Press `/` in transcript mode to search your conversation. `n` and `N` step through matches. Finally a way to find that one Bash command Claude ran 400 messages ago.~~

~~62Open transcript mode and search:~~

~~64```text Claude Code theme={null}~~

~~65Ctrl+O # open transcript~~

~~66/migrate # search for "migrate"~~

~~67n # next match~~

~~68N # previous match~~

~~69```~~

~~71[Fullscreen guide](https://code.claude.com/docs/en/fullscreen.md#search-and-review-the-conversation)~~

~~73PowerShell tool~~

~~74preview~~

~~75v2.1.84~~

~~77Windows gets a native PowerShell tool alongside Bash. Claude can run cmdlets, pipe objects, and work with Windows-native paths without translating everything through Git Bash.~~

~~79Opt in from settings:~~

~~81```json .claude/settings.json {3} theme={null}~~

~~82{~~

~~83 "env": {~~

~~84 "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1"~~

~~85 }~~

~~86}~~

~~87```~~

~~89[PowerShell tool docs](https://code.claude.com/docs/en/tools-reference.md#powershell-tool)~~

~~91Conditional hooks~~

~~92v2.1.85~~

94Hooks can now declare an `if` field using permission rule syntax. Your pre-commit check only spawns for `Bash(git commit *)` instead of every bash call, cutting the process overhead on busy sessions.

~~96Scope a hook to git commits only:~~

~~98```json .claude/settings.json {5} theme={null}~~

~~99{~~

100 "hooks": {

101 "PreToolUse": [{

102 "hooks": [{

103 "if": "Bash(git commit *)",

104 "type": "command",

105 "command": ".claude/hooks/lint-staged.sh"

106 }]

107 }]

108 }

109}

110```

~~111~~

112[Hooks reference](https://code.claude.com/docs/en/hooks.md)

~~113~~

114Other wins

~~115~~

116Plugin `userConfig` now public: prompt for settings at enable time, keychain-backed secretsPasted images insert `[Image #N]` chips you can reference positionally`managed-settings.d/` drop-in directory for layered policy fragments`CwdChanged` and `FileChanged` hook events for direnv-style setupsAgents can declare `initialPrompt` in frontmatter to auto-submit a first turn`Ctrl+X Ctrl+E` opens your external editor, matching readlineInterrupting before any response restores your input automatically`/status` now works while Claude is respondingDeep links open in your preferred terminal, not first-detectedIdle-return nudge to `/clear` after 75+ minutes awayVS Code: rate limit banner, Esc-twice rewind picker

~~117~~

118[Full changelog for v2.1.83–v2.1.85 →](https://code.claude.com/docs/en/changelog.md#2-1-83)

whats-new/2026-w14.md +0 −98 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 14 · March 30 – April 3, 2026~~

~~7> Computer use in the CLI, interactive in-product lessons, flicker-free rendering, per-tool MCP result-size overrides, and plugin executables on PATH.~~

~~9Releases [v2.1.86 → v2.1.91](https://code.claude.com/docs/en/changelog.md#2-1-86)~~

~~105 features · March 30 – April 3~~

~~12Computer use in the CLI~~

~~13research preview~~

15Last week computer use landed in the Desktop app. This week it's in the CLI: Claude can open native apps, click through UI, test its own changes, and fix what breaks, all from your terminal. Web apps already had verification loops; native iOS, macOS, and other GUI-only apps didn't. Now they do. Best for closing the loop on apps and tools where there's no API to call. Still early; expect rough edges.

17<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/CfffsX01JHFnIKvD/images/whats-new/cli-computer-use.mp4?fit=max&auto=format&n=CfffsX01JHFnIKvD&q=85&s=c17a337902308d7c9121013ded0494db" />

~~19Requires macOS and a Pro or Max plan; otherwise, `computer-use` won't appear in `/mcp`. Run `/mcp`, find `computer-use`, and toggle it on. Then ask Claude to verify a change end to end:~~

~~21```text title="Claude Code" wrap theme={null}~~

~~22Open the iOS simulator, tap through onboarding, and screenshot each step~~

~~23```~~

~~25[Computer use guide](https://code.claude.com/docs/en/computer-use.md)~~

~~27/powerup~~

~~28v2.1.90~~

30Interactive lessons that teach Claude Code features through animated demos, right inside your terminal. Claude Code releases frequently, and features that would have changed how you work last month can slip by. Run `/powerup` once and you'll know what's there.

32<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/CfffsX01JHFnIKvD/images/whats-new/powerup.mp4?fit=max&auto=format&n=CfffsX01JHFnIKvD&q=85&s=fb88beddc0ecc8029da5ab029e4b28f1" />

~~34Run it:~~

~~36```text title="Claude Code" wrap theme={null}~~

~~37/powerup~~

~~38```~~

~~40[Commands reference](https://code.claude.com/docs/en/commands.md)~~

~~42Flicker-free rendering~~

~~43v2.1.89~~

45Opt into a new alt-screen renderer with virtualized scrollback. The prompt input stays pinned to the bottom, mouse selection works across long conversations, and the flicker on redraw is gone. Unset `CLAUDE_CODE_NO_FLICKER` to roll back.

47<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/CfffsX01JHFnIKvD/images/whats-new/flicker-free.mp4?fit=max&auto=format&n=CfffsX01JHFnIKvD&q=85&s=7719e35e52a3f9734b0cf69edac333ad" />

~~49Set the env var and restart Claude Code:~~

~~51```bash theme={null}~~

~~52export CLAUDE_CODE_NO_FLICKER=1~~

~~53claude~~

~~54```~~

~~56[Fullscreen rendering](https://code.claude.com/docs/en/fullscreen.md)~~

~~58MCP result-size override~~

~~59v2.1.91~~

61MCP server authors can now raise the truncation cap on a specific tool by setting `anthropic/maxResultSizeChars` in the tool's `tools/list` entry, up to a hard ceiling of 500K characters. The cap used to be global, so tools that occasionally returned inherently large payloads like database schemas or full file trees hit the default limit and got persisted to disk with a file reference. Per-tool overrides keep those results inline when the tool really needs them.

~~63Annotate the tool in your server's `tools/list` response:~~

~~65```json highlight={5} theme={null}~~

~~66{~~

~~67 "name": "get_schema",~~

~~68 "description": "Returns the full database schema",~~

~~69 "_meta": {~~

~~70 "anthropic/maxResultSizeChars": 500000~~

~~71 }~~

~~72}~~

~~73```~~

~~75[MCP reference](https://code.claude.com/docs/en/mcp.md#raise-the-limit-for-a-specific-tool)~~

~~77Plugin executables on PATH~~

~~78v2.1.91~~

80Place an executable in a `bin/` directory at your plugin root and Claude Code adds that directory to the Bash tool's `PATH` while the plugin is enabled. Claude can then invoke the binary as a bare command from any Bash tool call, with no absolute path or wrapper script needed. Handy for packaging CLI helpers next to the commands, agents, and hooks that call them.

~~82Add a `bin/` directory at the plugin root:~~

~~84```text highlight={4, 5} theme={null}~~

~~85my-plugin/~~

~~86├── .claude-plugin/~~

~~87│ └── plugin.json~~

~~88└── bin/~~

~~89 └── my-tool~~

~~90```~~

~~92[Plugins reference](https://code.claude.com/docs/en/plugins/manifest-reference.md#standard-layout)~~

~~94Other wins~~

96Auto mode follow-ups: new `PermissionDenied` hook fires on classifier denials (return `retry: true` to let Claude try a different approach), and `/permissions` → Recently denied lets you retry manually with `r`New `defer` value for `permissionDecision` in `PreToolUse` hooks: `-p` sessions pause at a tool call and exit with a `deferred_tool_use` payload so an SDK app or custom UI can surface it, then resume with `--resume``/buddy`: hatch a small creature that watches you code. An April Fools' joke, no longer available`disableSkillShellExecution` setting blocks inline shell from skills, custom commands, and plugin commandsEdit tool now works on files viewed via `cat` or `sed -n` without a separate ReadHook output over 50K saved to disk with a path + preview instead of injected into contextThinking summaries off by default in interactive sessions (`showThinkingSummaries: true` to restore)Voice mode: push-to-talk modifier combos, Windows WebSocket, macOS Apple Silicon mic permission`claude-cli://` deep links accept multi-line prompts (encoded `%0A`)

~~98[Full changelog for v2.1.86–v2.1.91 →](https://code.claude.com/docs/en/changelog.md#2-1-86)~~

whats-new/2026-w15.md +0 −80 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 15 · April 6–10, 2026~~

~~7> Ultraplan cloud planning, the Monitor tool with self-pacing /loop, /team-onboarding for packaging your setup, and /autofix-pr from your terminal.~~

~~9Releases [v2.1.92 → v2.1.101](https://code.claude.com/docs/en/changelog.md#2-1-92)~~

~~104 features · April 6–10~~

~~12Ultraplan~~

~~13research preview~~

15Kick off plan mode in the cloud from your terminal, then review the result in your browser. Claude drafts the plan in a Claude Code on the web session while your terminal stays free; when it's ready you comment on individual sections, ask for revisions, and choose to execute remotely or send it back to your CLI. As of v2.1.101 the first run auto-creates a default cloud environment, so there's no web setup step before you can try it.

17<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/aFXPQxiBOW99MHS3/images/whats-new/ultraplan.mp4?fit=max&auto=format&n=aFXPQxiBOW99MHS3&q=85&s=e8f2f23730c6a5c289dbf3e7b13eadf6" />

~~19Run the command, or just include the keyword in any prompt:~~

~~21```text title="Claude Code" wrap theme={null}~~

~~22/ultraplan migrate the auth service from sessions to JWTs~~

~~23```~~

~~25[Ultraplan guide](https://code.claude.com/docs/en/ultraplan)~~

~~27Monitor tool~~

~~28v2.1.98~~

30A new built-in tool that spawns a background watcher and streams its events into the conversation: each event lands as a new transcript message that Claude reacts to immediately. Tail a training run, babysit a PR's CI, or auto-fix a dev server crash the moment it happens, all without a Bash sleep loop holding the turn open.

32<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/aFXPQxiBOW99MHS3/images/whats-new/monitor-tool.mp4?fit=max&auto=format&n=aFXPQxiBOW99MHS3&q=85&s=f4156c15a0999de5c5157f54a3117c89" />

~~34Ask Claude to watch something while you keep working:~~

~~36```text title="Claude Code" wrap theme={null}~~

~~37Tail server.log in the background and tell me the moment a 5xx shows up~~

~~38```~~

~~40This pairs with `/loop`, which now self-paces: omit the interval and Claude schedules the next tick based on the task, or reaches for the Monitor tool to skip polling altogether.~~

~~42```text title="Claude Code" wrap theme={null}~~

~~43/loop check CI on my PR~~

~~44```~~

~~46[Monitor tool reference](https://code.claude.com/docs/en/tools-reference.md#monitor-tool)~~

~~48/autofix-pr~~

~~49CLI~~

51PR auto-fix landed on the web in Week 13. Now you can turn it on without leaving your terminal: `/autofix-pr` infers the open PR for your current branch and enables auto-fix for it on Claude Code on the web in one step. Push your branch, run the command, walk away; Claude watches CI and review comments and pushes fixes until it's green.

53<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/aFXPQxiBOW99MHS3/images/whats-new/autofix-pr.mp4?fit=max&auto=format&n=aFXPQxiBOW99MHS3&q=85&s=95f191eb4711130a128aec3f6b720527" />

~~55Run it from the PR's branch:~~

~~57```text title="Claude Code" wrap theme={null}~~

~~58/autofix-pr~~

~~59```~~

~~61[Auto-fix pull requests](https://code.claude.com/docs/en/claude-code-on-the-web.md#auto-fix-pull-requests)~~

~~63/team-onboarding~~

~~64v2.1.101~~

66Generates a teammate ramp-up guide from your local Claude Code usage. Run it in a project you know well and hand the output to a new teammate so they can replay your setup instead of starting from defaults.

~~68Run it from a project you've spent real time in:~~

~~70```text title="Claude Code" wrap theme={null}~~

~~71/team-onboarding~~

~~72```~~

~~74[Commands reference](https://code.claude.com/docs/en/commands.md)~~

~~76Other wins~~

78Focus view: press `Ctrl+O` in flicker-free mode to collapse the view to your last prompt, a one-line tool summary with diffstats, and Claude's final responseGuided [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md) and [Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md) setup wizards on the login screen: pick "3rd-party platform" for step-by-step auth, region, credential check, and model pinning`/agents` gets a tabbed layout: a Running tab shows live subagents with a `● N running` count, plus Run agent and View running instance actions in the Library tabDefault effort level is now `high` for API-key, Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, Team, and Enterprise users (control with `/effort`)`/cost` shows a per-model and cache-hit breakdown for subscription users`/release-notes` is now an interactive version pickerStatus line: new `refreshInterval` setting re-runs the command every N seconds, and `workspace.git_worktree` in the JSON input`CLAUDE_CODE_PERFORCE_MODE`: Edit/Write fail on read-only files with a `p4 edit` hint instead of silently overwritingOS CA certificate store is now trusted by default, so enterprise TLS proxies work without extra setup (`CLAUDE_CODE_CERT_STORE=bundled` to opt out)Amazon Bedrock powered by Mantle: set `CLAUDE_CODE_USE_MANTLE=1`Hardened Bash tool permissions: backslash-escaped flags, env-var prefixes, `/dev/tcp` redirects, and compound commands now prompt correctly`UserPromptSubmit` hooks can set the session title via `hookSpecificOutput.sessionTitle`

~~80[Full changelog for v2.1.92–v2.1.101 →](https://code.claude.com/docs/en/changelog.md#2-1-92)~~

whats-new/2026-w16.md +0 −89 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 16 · April 13–17, 2026~~

7> Claude Opus 4.7 with the new xhigh effort level, Routines on Claude Code on the web, mobile push notifications that ping your phone when Claude needs you, a /usage breakdown that shows what's driving your limits, and native binaries replacing the bundled JavaScript.

~~9Releases [v2.1.105 → v2.1.113](https://code.claude.com/docs/en/changelog.md#2-1-105)~~

~~105 features · April 13–17~~

~~12Claude Opus 4.7~~

~~13new model~~

15Anthropic's strongest coding model yet is now the default on Max and Team Premium, and available everywhere else from `/model`. It adds a new `xhigh` effort level that sits between `high` and `max`: best results for most coding and agentic tasks, applied as the default the first time you switch to 4.7. `/effort` now opens an interactive arrow-key slider when you call it without arguments, so you can dial intelligence against speed without remembering the level names.

~~17Switch model and effort in one go:~~

~~19```text Claude Code theme={null}~~

~~20> /model opus~~

~~21> /effort xhigh~~

~~22```~~

~~24[Model config: effort levels](https://code.claude.com/docs/en/model-config.md#adjust-effort-level)~~

~~26Routines~~

~~27web~~

29Templated cloud agents that fire on a schedule, a GitHub event, or an API call. Define a routine once on Claude Code on the web with a prompt, the repos it can touch, and the connectors it needs, then let PR-opened, release-published, or your own webhook trigger it without your machine running. The trigger picker now covers GitHub events with optional filters and gives every routine a tokened `/fire` endpoint for external systems.

31![Creating a routine on Claude Code on the web with schedule, GitHub event, and API triggers](https://mintcdn.com/claude-code/FTi4SBJ9YRs7d-5X/images/whats-new/routines.png?fit=max\&auto=format\&n=FTi4SBJ9YRs7d-5X\&q=85\&s=2ba818ea9280c549511cb48b9b4d1dc5)

~~33Create one from the web UI, or scaffold from your terminal:~~

~~35```text Claude Code theme={null}~~

~~36> /schedule daily PR review at 9am~~

~~37```~~

~~39[Routines guide](https://code.claude.com/docs/en/routines.md)~~

~~41/usage breakdown~~

~~42CLI~~

44More visibility into where your Claude Code usage goes. `/usage` now shows what's driving your limits: parallel sessions, subagents, cache misses, and long context, each with a percentage of your last 24 hours and a tip to optimize it. Press `d` or `w` to switch between day and week views.

46![The /usage command showing a breakdown of what's contributing to limits usage](https://mintcdn.com/claude-code/FTi4SBJ9YRs7d-5X/images/whats-new/usage.png?fit=max\&auto=format\&n=FTi4SBJ9YRs7d-5X\&q=85\&s=792a4b43cbef4e2931974831f076bca6)

~~48Run it any time:~~

~~50```text Claude Code theme={null}~~

~~51> /usage~~

~~52```~~

~~54[Commands reference](https://code.claude.com/docs/en/commands.md)~~

~~56Mobile push notifications~~

~~57mobile~~

59With [Remote Control](https://code.claude.com/docs/en/remote-control.md) connected, Claude can send a push notification to your phone when a long task finishes or it needs a decision to keep going. Turn it on with "Push when Claude decides" in `/config`, or ask for one in your prompt. Useful when you kick off a long agent run and want to step away from the terminal.

61<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/uII1TETOZxBUZ3lB/images/whats-new/push-notifications.mp4?fit=max&auto=format&n=uII1TETOZxBUZ3lB&q=85&s=c91a967139596500cbdb581a53822ac1" />

~~63Ask Claude to ping you when it's done:~~

~~65```text Claude Code theme={null}~~

~~66> notify me when the tests pass~~

~~67```~~

~~69[Remote Control: mobile push notifications](https://code.claude.com/docs/en/remote-control.md#mobile-push-notifications)~~

~~71Native binaries~~

~~72v2.1.113~~

74The `claude` CLI now spawns a native per-platform binary instead of bundled JavaScript, so the installed `claude` command no longer invokes Node. The npm package pulls the right binary in through an optional dependency such as `@anthropic-ai/claude-code-darwin-arm64`, so your install command doesn't change. The standalone installer already shipped this binary; npm now matches it.

~~76Upgrade and check what you're running:~~

~~78```bash theme={null}~~

~~79claude update~~

~~80claude --version~~

~~81```~~

~~83[Setup guide](https://code.claude.com/docs/en/setup.md)~~

~~85Other wins~~

87New [`/ultrareview`](https://code.claude.com/docs/en/ultrareview): comprehensive code review in the cloud using parallel multi-agent analysis and an adversarial critique pass. Run it bare to review your current branch, or `/ultrareview <PR#>` for a specific PR[Auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) is now available for Max subscribers on Opus 4.7, and the `--enable-auto-mode` flag is no longer required[Session recap](https://code.claude.com/docs/en/interactive-mode.md#session-recap) shows a one-line summary of what happened while you were away; run `/recap` on demand or turn it off from `/config`New `/tui` command and `tui` setting switch between classic and flicker-free rendering mid-conversation; focus view moved from `Ctrl+O` to its own `/focus` commandPlugins can ship background watchers via a top-level `monitors` manifest key that auto-arms at session start or on skill invoke"Auto (match terminal)" option in `/theme` follows your terminal's dark/light mode`/fewer-permission-prompts` scans your transcripts for common read-only Bash and MCP calls and proposes an allowlist for `.claude/settings.json`Claude can now discover and run built-in commands like `/init`, `/review`, and `/security-review` via the Skill tool`PreCompact` hooks can block compaction by exiting with code 2 or returning `{"decision":"block"}``ENABLE_PROMPT_CACHING_1H` opts API key, Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry users into 1-hour prompt cache TTL`sandbox.network.deniedDomains` setting carves specific domains out of a broader `allowedDomains` wildcard`/undo` is now an alias for `/rewind`, and `/proactive` is an alias for `/loop`Hardened Bash permissions: deny rules now match through `env`/`sudo`/`watch` wrappers, and `Bash(find:*)` allow rules no longer auto-approve `-exec` or `-delete`

~~89[Full changelog for v2.1.105–v2.1.113 →](https://code.claude.com/docs/en/changelog.md#2-1-105)~~

whats-new/2026-w17.md +0 −74 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 17 · April 20–24, 2026~~

~~7> /ultrareview opens as a research preview, automatic session recaps when you return to a terminal, custom color themes you can build and ship in plugins, and a redesigned Claude Code on the web.~~

~~9Releases [v2.1.114 → v2.1.119](https://code.claude.com/docs/en/changelog.md#2-1-114)~~

~~104 features · April 20–24~~

~~12/ultrareview~~

~~13research preview~~

15Now in public research preview. Ultrareview runs a fleet of bug-hunting agents in the cloud against your branch or a PR, and findings land back in the CLI or Desktop automatically. Run it before merging critical changes such as auth or data migrations.

17<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/FTi4SBJ9YRs7d-5X/images/whats-new/ultrareview.mp4?fit=max&auto=format&n=FTi4SBJ9YRs7d-5X&q=85&s=0fb1271365d38f414ad155aeb8edb08e" />

~~19Review the branch you're on:~~

~~21```text Claude Code theme={null}~~

~~22> /ultrareview~~

~~23```~~

~~25Or point it at a PR:~~

~~27```text Claude Code theme={null}~~

~~28> /ultrareview 1234~~

~~29```~~

~~31[Ultrareview guide](https://code.claude.com/docs/en/ultrareview.md)~~

~~33Session recap~~

~~34CLI~~

~~36Switch focus away from a session and come back to a one-line recap of what happened while you were gone. Helpful for staying in flow while running several Claude sessions at once.~~

38<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/FTi4SBJ9YRs7d-5X/images/whats-new/session-recap.mp4?fit=max&auto=format&n=FTi4SBJ9YRs7d-5X&q=85&s=0a8db1470bd0161a47efeb2f322af76f" />

~~40Generate a recap on demand, or turn the automatic one off from `/config`:~~

~~42```text Claude Code theme={null}~~

~~43> /recap~~

~~44```~~

~~46[Interactive mode: session recap](https://code.claude.com/docs/en/interactive-mode.md#session-recap)~~

~~48Custom themes~~

~~49v2.1.118~~

51Build and switch between named color themes from `/theme`, or hand-edit JSON files in `~/.claude/themes/`. Each theme picks a base preset and overrides only the tokens you care about. Plugins can ship themes too.

~~53Open the theme picker and create a new one:~~

~~55```text Claude Code theme={null}~~

~~56> /theme~~

~~57```~~

~~59[Terminal config: create a custom theme](https://code.claude.com/docs/en/terminal-config.md#create-a-custom-theme)~~

~~61Claude Code on the web~~

~~62web~~

64A new look for [claude.ai/code](https://claude.ai/code) that matches the redesigned desktop app: sessions sidebar, drag-and-drop layout, and a refreshed routines view. Key parts were rebuilt for quicker responses and a more reliable experience.

66![Claude Code on the web redesign overview: new UI, speed and reliability, work across web, mobile, and CLI](https://mintcdn.com/claude-code/FTi4SBJ9YRs7d-5X/images/whats-new/web-redesign.jpeg?fit=max\&auto=format\&n=FTi4SBJ9YRs7d-5X\&q=85\&s=a2aca1b49e295b7337f5779038db8e2c)

~~68[Claude Code on the web](https://code.claude.com/docs/en/claude-code-on-the-web.md)~~

~~70Other wins~~

72[Vim visual mode](https://code.claude.com/docs/en/interactive-mode.md#vim-editor-mode): press `v` for character selection or `V` for line selection in the prompt input, with operators and visual feedbackHooks can now call MCP tools directly via [`type: "mcp_tool"`](https://code.claude.com/docs/en/hooks#mcp-tool-hook-fields), so a hook can hit an already-connected server without spawning a process`/cost` and `/stats` are merged into [`/usage`](https://code.claude.com/docs/en/commands); the old names still work as typing shortcuts that open the relevant tab`/config` changes (theme, editor mode, verbose, and similar) now persist to `~/.claude/settings.json` and follow the same project/local/policy precedence as other [settings](https://code.claude.com/docs/en/settings.md)[Forked subagents](https://code.claude.com/docs/en/sub-agents.md#fork-the-current-conversation) can be enabled on external builds with `CLAUDE_CODE_FORK_SUBAGENT=1`: a fork inherits your full conversation context instead of starting freshDefault [effort level](https://code.claude.com/docs/en/model-config.md#adjust-effort-level) for Pro and Max subscribers on Opus 4.6 and Sonnet 4.6 is now `high` (was `medium`)Native macOS and Linux builds replace the `Glob` and `Grep` tools with embedded `bfs` and `ugrep` available through Bash, for faster searches without a separate tool round-trip`--from-pr` now accepts GitLab merge request, Bitbucket pull request, and GitHub Enterprise PR URLs in addition to github.comAuto mode: include `"$defaults"` in [`autoMode.allow`, `soft_deny`, or `environment`](https://code.claude.com/docs/en/auto-mode-config) to add custom rules alongside the built-in list instead of replacing itNew [`claude plugin tag`](https://code.claude.com/docs/en/plugins/dependencies#tag-plugin-releases-for-version-resolution) command creates release git tags for plugins with version validationOpus 4.7 sessions now compute against the model's native 1M context window, fixing inflated `/context` percentages and premature autocompaction`/resume` on large sessions is up to 67% faster and now offers to summarize stale, large sessions before re-reading them

~~74[Full changelog for v2.1.114–v2.1.119 →](https://code.claude.com/docs/en/changelog.md#2-1-114)~~

whats-new/2026-w18.md +0 −80 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 18 · April 27 – May 1, 2026~~

7> Claude Code on Windows runs without Git Bash, claude auth login accepts a pasted OAuth code when the browser callback can't reach localhost, claude project purge cleans up local state per project, and pasting a PR URL into /resume finds the session that created it.

~~9Releases [v2.1.120 → v2.1.126](https://code.claude.com/docs/en/changelog.md#2-1-120)~~

~~104 features · April 27 – May 1~~

~~12Sign in without a browser callback~~

~~13v2.1.126~~

15`claude auth login` now accepts the OAuth code pasted directly into the terminal when the browser callback can't reach localhost. That covers WSL2, SSH sessions, and containers, where the redirect to a local port doesn't work. The same release also fixes login timeouts on slow or proxied connections and in IPv6-only devcontainers.

~~17Sign in, then paste the code from the browser:~~

~~19```bash theme={null}~~

~~20claude auth login~~

~~21```~~

~~23[CLI reference](https://code.claude.com/docs/en/cli-reference.md#cli-commands)~~

~~25claude project purge~~

~~26v2.1.124~~

28Delete all Claude Code state for a project: transcripts, tasks, file history, and the project's config entry. Supports `--dry-run` to preview, `-y`/`--yes` to skip confirmation, `-i`/`--interactive` to choose, and `--all` to clear every project.

~~30Preview what would be removed:~~

~~32```bash theme={null}~~

~~33claude project purge --dry-run~~

~~34```~~

~~36Then run it for real:~~

~~38```bash theme={null}~~

~~39claude project purge~~

~~40```~~

~~42[CLI reference](https://code.claude.com/docs/en/cli-reference.md)~~

~~44Resume by PR URL~~

~~45v2.1.122~~

~~47When you create a pull request with `gh pr create`, Claude Code links it to the session that produced it. Now you can get back to that session from the PR URL alone, without remembering its name.~~

~~49Open the session picker:~~

~~51```text Claude Code theme={null}~~

~~52> /resume~~

~~53```~~

55Paste the PR URL into the picker. The first character of the paste drops you into search mode, and the list filters to the session that created that PR. Press Enter to resume it. GitHub, GitHub Enterprise, GitLab, and Bitbucket pull and merge request URLs all work.

~~57```text Claude Code theme={null}~~

~~58https://github.com/your-org/your-repo/pull/1234~~

~~59```~~

~~61To open the picker already filtered to the PR, pass the PR number on the command line:~~

~~63```bash theme={null}~~

~~64claude --from-pr 1234~~

~~65```~~

~~67[Sessions: use the session picker](https://code.claude.com/docs/en/sessions.md#use-the-session-picker)~~

~~69Windows without Git Bash~~

~~70Windows~~

72Git for Windows is no longer required. When Bash is absent, Claude Code uses PowerShell as the shell tool, and when the PowerShell tool is enabled it is treated as the primary shell. PowerShell 7 installed via the Microsoft Store, MSI without PATH, or a `.NET` global tool is now detected automatically.

~~74[Setup guide](https://code.claude.com/docs/en/setup.md)~~

~~76Other wins~~

78MCP servers can opt out of tool-search deferral with `alwaysLoad: true` in their config so all of that server's tools are always availableNew `claude plugin prune` removes orphaned auto-installed plugin dependencies, and `plugin uninstall --prune` cascades`/skills` now has a type-to-filter search box so you can find a skill in a long list without scrolling`PostToolUse` hooks can replace tool output for any tool via `hookSpecificOutput.updatedToolOutput`, not only MCP toolsNew [`claude ultrareview`](https://code.claude.com/docs/en/ultrareview) subcommand runs `/ultrareview` non-interactively from CI or scripts: prints findings to stdout (`--json` for raw output) and exits 0 on completion or 1 on failure`--dangerously-skip-permissions` now bypasses prompts for writes to `.claude/`, `.git/`, `.vscode/`, shell config files, and other previously protected paths, while catastrophic removal commands still prompt as a safety netThe `/model` picker can list models from your gateway's `/v1/models` endpoint when `ANTHROPIC_BASE_URL` points at an Anthropic-compatible gateway; opt in with `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` since v2.1.129MCP servers that hit a transient error during startup now auto-retry up to 3 times instead of staying disconnected`ANTHROPIC_BEDROCK_SERVICE_TIER` selects an Amazon Bedrock service tier: `default`, `flex`, or `priority``/terminal-setup` enables iTerm2's clipboard access setting so `/copy` works, including from tmuxGoogle Cloud's Agent Platform now supports X.509 certificate-based Workload Identity Federation (mTLS ADC)Significant memory leak fixes: image-heavy sessions, `/usage` on large transcript histories, and long-running tools without progress events

~~80[Full changelog for v2.1.120–v2.1.126 →](https://code.claude.com/docs/en/changelog.md#2-1-120)~~

whats-new/2026-w19.md +0 −35 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 19 · May 4–8, 2026~~

7> Load plugins from .zip archives and URLs, search command history across every project with Ctrl+R, branch new worktrees from local HEAD or the remote default, and block actions unconditionally with auto mode hard deny rules.

~~9Releases [v2.1.128 → v2.1.136](https://code.claude.com/docs/en/changelog.md#2-1-128)~~

~~102 features · May 4–8~~

~~12Plugins from .zip archives and URLs~~

14`--plugin-dir` now accepts a `.zip` plugin archive in addition to a directory, and the new `--plugin-url` flag fetches a plugin archive from a URL for the current session. Useful for trying a plugin before adding it to a marketplace, or for shipping internal plugins from an artifact store.

~~16Load a plugin straight from a URL:~~

~~18```bash terminal theme={null}~~

~~19claude --plugin-url https://example.com/my-plugin.zip~~

~~20```~~

~~22[Plugins guide](https://code.claude.com/docs/en/plugins/overview.md)~~

~~24History search across all your projects~~

~~25v2.1.129~~

27`Ctrl+R` reverse-search now defaults to all prompts across every project, restoring the behavior from before v2.1.124. Press `Ctrl+S` while searching to narrow back to the current project or session. Handy when you remember a command you ran in another repo last week and don't want to go digging for it.

~~29[Interactive mode: command history](https://code.claude.com/docs/en/interactive-mode.md#command-history)~~

~~31Other wins~~

33New `worktree.baseRef` setting (`fresh` | `head`) controls whether `--worktree`, the `EnterWorktree` tool, and agent-isolation worktrees branch from the remote default branch or local `HEAD`; the default `fresh` keeps unpushed commits out of new worktreesNew `settings.autoMode.hard_deny` rules block matching actions unconditionally in auto mode, regardless of allow exceptions, for actions that should never run automatically even when broader allow rules applyHooks now receive the active effort level via the `effort.level` JSON input field and the `$CLAUDE_EFFORT` environment variable, and Bash tool commands can read `$CLAUDE_EFFORT``CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1` opts out of the fullscreen alternate-screen renderer and keeps the conversation in the terminal's native scrollback`CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` lets Homebrew or WinGet installations run the upgrade in the background and prompt to restart`CLAUDE_CODE_SESSION_ID` is now in the Bash tool subprocess environment, matching the `session_id` passed to hooks`/mcp` now shows the tool count for connected servers and flags servers that connected with 0 tools`--channels` now works with console (API key) authenticationSubprocesses such as Bash, hooks, MCP, and LSP no longer inherit `OTEL_*` environment variables, so OTEL-instrumented apps run via the Bash tool no longer pick up the CLI's own OTLP endpointSub-agent progress summaries now hit the prompt cache, cutting `cache_creation` token cost by roughly 3xSeveral OAuth and credential reliability fixes: parallel sessions no longer dead-end at 401 after a refresh-token race, MCP OAuth refresh tokens are no longer lost when multiple servers refresh concurrently, and a rare login loop from a concurrent credential write is fixedNew `parentSettingsBehavior` admin key lets admins opt SDK `managedSettings` into the policy merge

~~35[Full changelog for v2.1.128–v2.1.136 →](https://code.claude.com/docs/en/changelog.md#2-1-128)~~

whats-new/2026-w20.md +0 −61 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 20 · May 11–15, 2026~~

~~7> Manage every Claude Code session from one screen with agent view, keep Claude working toward a goal until a condition holds, and run fast mode on Opus 4.7 by default.~~

~~9Releases [v2.1.139 → v2.1.142](https://code.claude.com/docs/en/changelog.md#2-1-139)~~

~~103 features · May 11–15~~

~~12Agent view~~

~~13research preview~~

15`claude agents` opens one screen for every Claude Code session: what's running, what's blocked on your input, and what's done. Dispatch a bug fix, a pull request review, and a flaky-test investigation as three rows, keep working in another window, and step in only when a row needs you. Attach to any row to drop into its full conversation, then press `←` to return to the list. Each background session keeps running without a terminal attached.

17<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/ITvjicPxe1SM3GX7/images/whats-new/agent-view.mp4?fit=max&auto=format&n=ITvjicPxe1SM3GX7&q=85&s=0eefe6cbe75464c8f7902bba630ab7a4" />

~~19Open the dashboard from your shell:~~

~~21```bash terminal theme={null}~~

~~22claude agents~~

~~23```~~

~~25[Agent view](https://code.claude.com/docs/en/agent-view.md)~~

~~27/goal~~

~~28v2.1.139~~

30Set a completion condition and Claude keeps working toward it across turns without you prompting each step. After every turn, a fast model checks whether the condition holds; if not, Claude starts another turn instead of handing control back. Useful for substantial work with a verifiable end state, like migrating a module until every call site compiles and tests pass. The goal clears once the condition is met, and works in interactive, `-p`, and Remote Control.

32<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/ITvjicPxe1SM3GX7/images/whats-new/goal.mp4?fit=max&auto=format&n=ITvjicPxe1SM3GX7&q=85&s=6806df3780c548b93a02d6fa71da276b" />

~~34Set a goal and let Claude run until it holds:~~

~~36```text Claude Code theme={null}~~

~~37> /goal all tests in test/auth pass and the lint step is clean~~

~~38```~~

~~40[Goals](https://code.claude.com/docs/en/goal.md)~~

~~42Fast mode on Opus 4.7~~

~~43research preview~~

45`/fast` now runs on Opus 4.7 by default instead of Opus 4.6. Fast mode is a high-speed Opus configuration: the same model quality at about 2.5x the speed for a higher per-token cost, useful for rapid iteration and live debugging. Pricing is unchanged at \$30/\$150 per MTok, the same as Opus 4.6 fast mode. To pin fast mode to Opus 4.6, set `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1`.

47![The Claude Code model picker showing Opus 4.7 Fast 1M as the default with the Fast toggle on](https://mintcdn.com/claude-code/ITvjicPxe1SM3GX7/images/whats-new/fast-mode-opus-47.png?fit=max\&auto=format\&n=ITvjicPxe1SM3GX7\&q=85\&s=6b6d92f7748ce5328a1ee9a269fb1a87)

~~49Toggle fast mode, now running on Opus 4.7:~~

~~51```text Claude Code theme={null}~~

~~52> /fast~~

~~53```~~

~~55[Fast mode on Opus 4.7](https://code.claude.com/docs/en/fast-mode.md#understand-the-cost-tradeoff)~~

~~57Other wins~~

59`claude agents` gained dispatch flags (`--add-dir`, `--settings`, `--mcp-config`, `--plugin-dir`, `--permission-mode`, `--model`, `--effort`, `--dangerously-skip-permissions`) to configure background sessions, and `claude agents --cwd <path>` scopes the session list to a directoryNew hook `args: string[]` exec form spawns the command directly without a shell, so path placeholders never need quotingNew `continueOnBlock` config option for `PostToolUse` hooks feeds the hook's rejection reason back to Claude and continues the turn instead of ending itNew `terminalSequence` field in hook JSON output lets hooks emit desktop notifications, window titles, and bells without a controlling terminalThe Rewind menu added "Summarize up to here" to compress earlier context while keeping recent turns intactRemote Control, `/schedule`, claude.ai MCP connectors, and notification preferences are now disabled when `ANTHROPIC_API_KEY`, `apiKeyHelper`, or `ANTHROPIC_AUTH_TOKEN` is set, even alongside a claude.ai login; unset the API key to use these featuresMCP stdio servers now receive `CLAUDE_PROJECT_DIR` in their environment, matching hooks, and plugin configs can reference `${CLAUDE_PROJECT_DIR}` in commands`claude plugin details <name>` shows a plugin's component inventory and projected per-session token cost, and the `/plugin` details pane now also lists the LSP servers a plugin providesPlugins with a root-level `SKILL.md` and no `skills/` subdirectory are now surfaced as a skill`/feedback` can now include recent sessions from the last 24 hours or 7 days for issues spanning more than the current sessionAgent tool `subagent_type` now matches case- and separator-insensitively, so `"Code Reviewer"` resolves to `code-reviewer`

~~61[Full changelog for v2.1.139–v2.1.142 →](https://code.claude.com/docs/en/changelog.md#2-1-139)~~

whats-new/2026-w21.md +0 −31 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 21 · May 18–22, 2026~~

~~7> Use auto mode on the Pro plan and with Sonnet 4.6, see which skills, subagents, and MCP servers drive your plan limits in /usage, and review diffs with the new /code-review command.~~

~~9Releases [v2.1.143 → v2.1.149](https://code.claude.com/docs/en/changelog.md#2-1-143)~~

~~101 feature · May 18–22~~

~~12Auto mode on the Pro plan~~

~~13CLI~~

15Auto mode is now available on the Pro plan and supports Sonnet 4.6 alongside Opus. It replaces permission prompts with background safety checks: routine actions run without interrupting you, and destructive or suspicious ones are blocked and surfaced.

~~17Update Claude Code, then cycle modes with Shift+Tab; auto mode appears in the cycle once your account meets the requirements:~~

~~19```bash terminal theme={null}~~

~~20claude update~~

~~21```~~

~~23The command prints `Successfully updated` with the new version number, or `Claude Code is up to date` if no update is needed. Once auto mode is active, the prompt footer shows `auto mode on`.~~

~~25[Auto mode requirements](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode)~~

~~27Other wins~~

29[`/usage`](https://code.claude.com/docs/en/costs#track-your-costs) now shows a per-category breakdown of what's driving your plan limits, attributing recent usage to skills, subagents, plugins, and individual MCP servers"Extra usage" is renamed to "usage credits" across the CLI, and `/extra-usage` is now `/usage-credits`. The old name still works. The command requires signing in with your claude.ai subscription through `/login` and isn't available with API key authentication.New [`/code-review`](https://code.claude.com/docs/en/code-review) command reports correctness bugs at a chosen effort level such as `/code-review high`, and `--comment` posts findings as inline GitHub PR comments. `/simplify` remains as a separate cleanup-only review\.Background sessions now appear in `/resume` alongside interactive ones, marked with `bg`, and sessions pinned with `Ctrl+T` in `claude agents` stay alive when idle`claude agents --json` lists live sessions as JSON for scripting, such as status bars and session pickersThe PowerShell tool is now enabled by default on Windows for Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry users; opt out with `CLAUDE_CODE_USE_POWERSHELL_TOOL=0``claude plugin disable` now refuses when another enabled plugin depends on the target, and `claude plugin enable` force-enables transitive dependenciesThe `/plugin` marketplace browse pane shows projected context cost, and the Discover and Browse screens list a plugin's commands, agents, skills, hooks, and MCP/LSP servers before installationNew `worktree.bgIsolation: "none"` setting lets background sessions edit the working copy directly without `EnterWorktree`, for repos where worktrees are impracticalMarkdown output renders GFM task list checkboxes, and the `/diff` detail view scrolls with the keyboardStatus line JSON input now includes GitHub repo and PR information when detectedEnterprise: the `allowAllClaudeAiMcps` managed setting loads claude.ai cloud MCP connectors alongside `managed-mcp.json`

~~31[Full changelog for v2.1.143–v2.1.149 →](https://code.claude.com/docs/en/changelog.md#2-1-143)~~

whats-new/2026-w22.md +0 −80 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 22 · May 25–29, 2026~~

~~7> Run Claude Code on Claude Opus 4.8, orchestrate large tasks with dynamic workflows, catch security issues with the security-guidance plugin, and use fast mode on Opus 4.8 at a lower price.~~

~~9Releases [v2.1.150 → v2.1.157](https://code.claude.com/docs/en/changelog.md#2-1-150)~~

~~104 features · May 25–29~~

~~12Claude Opus 4.8~~

~~13new model~~

~~15Opus 4.8 is now the default on Max, Team Premium, Enterprise pay-as-you-go, and the Anthropic API. It defaults to high effort; use `/effort xhigh` for harder tasks. Requires v2.1.154 or later.~~

17<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/QsIrGXGFg6xd7joy/images/whats-new/opus-4-8.mp4?fit=max&auto=format&n=QsIrGXGFg6xd7joy&q=85&s=6ebcf5fe136467da2b254de1fe749ea7" />

~~19Switch to Opus 4.8 by name, or pick it from the model picker:~~

~~21```text title="Claude Code" wrap theme={null}~~

~~22/model claude-opus-4-8~~

~~23```~~

~~25[Model configuration](https://code.claude.com/docs/en/model-config.md#available-models)~~

~~27Dynamic workflows~~

~~28research preview~~

30A workflow is an orchestration script Claude writes for your task and runs across many subagents in the background. Use one when a task is too large for one conversation to coordinate: a codebase-wide audit, a large migration, a research question that needs cross-checking. Manage runs with `/workflows`.

32![Claude Code on Opus 4.8 showing a Dynamic workflow requested indicator for a prompt that asks for a workflow to migrate every internal fetch() call](https://mintcdn.com/claude-code/QsIrGXGFg6xd7joy/images/whats-new/dynamic-workflows.png?fit=max\&auto=format\&n=QsIrGXGFg6xd7joy\&q=85\&s=26671fa8607cec3453ed9753f821bd4f)

~~34Describe the task and ask for a workflow:~~

~~36```text title="Claude Code" wrap theme={null}~~

~~37create a workflow that migrates every internal fetch() call to the new HttpClient wrapper~~

~~38```~~

~~40[Dynamic workflows](https://code.claude.com/docs/en/workflows.md)~~

~~42Security guidance plugin~~

~~43plugin~~

45The security-guidance plugin reviews Claude's code changes for vulnerabilities and fixes them in the same session. It runs a fast pattern check on each edit, a model review at the end of each turn, and a deeper agentic review on commit or push. Add project rules in `.claude/claude-security-guidance.md`.

47<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/QsIrGXGFg6xd7joy/images/whats-new/security-guidance.mp4?fit=max&auto=format&n=QsIrGXGFg6xd7joy&q=85&s=c91d865936411586f42b24c558bcdd1d" />

~~49Install it from the official Anthropic marketplace:~~

~~51```text title="Claude Code" wrap theme={null}~~

~~52/plugin install security-guidance@claude-plugins-official~~

~~53```~~

~~55Then activate it in the current session:~~

~~57```text title="Claude Code" wrap theme={null}~~

~~58/reload-plugins~~

~~59```~~

~~61[Security guidance plugin](https://code.claude.com/docs/en/security-guidance.md)~~

~~63Fast mode on Opus 4.8~~

~~64research preview~~

~~66Fast mode now defaults to Opus 4.8 at \$10/\$50 per MTok: 2x the standard rate for about 2.5x the speed. Opus 4.7 and 4.6 stay at \$30/\$150. Opus 4.6 fast mode is deprecated.~~

~~68Toggle fast mode, now on Opus 4.8:~~

~~70```text title="Claude Code" wrap theme={null}~~

~~71/fast~~

~~72```~~

~~74[Fast mode pricing](https://code.claude.com/docs/en/fast-mode.md#understand-the-cost-tradeoff)~~

~~76Other wins~~

78In `claude agents`, prefix a shell command with `!` to run it as a background job you can attach to and detach from; also available as `claude --bg --exec 'pytest -x'`Plugins in `.claude/skills` directories are now loaded automatically, no marketplace required, and `claude plugin init <name>` scaffolds a new pluginNew `/reload-skills` command re-scans skill directories without restarting, and `SessionStart` hooks can return `reloadSkills: true` to make skills they install available in the same sessionSkills and commands can set `disallowed-tools` in frontmatter to remove tools from the model while the skill is activeNew `MessageDisplay` hook event lets hooks transform or hide assistant message text as it is displayedClaude Code now switches to your configured `--fallback-model` for the rest of the session when the primary model is not found, instead of failing every requestPlugins can declare `defaultEnabled: false` in `plugin.json` or a marketplace entry, so they install without turning on until you enable themVim mode: `/` in NORMAL mode opens reverse history search, matching Bash and Zsh vi-modeStreaming tool execution is now always enabled, including with telemetry disabled and on Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry`←←` to open the agents view now works on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, and with telemetry disabledClaude in Chrome: pick which connected browser to use via `/chrome` → "Select browser…", or in-chat when a browser action runs with multiple connected`claude mcp list` and `claude mcp get` now show unapproved `.mcp.json` servers as pending approval instead of auto-approving and connecting when output is piped

~~80[Full changelog for v2.1.150–v2.1.157 →](https://code.claude.com/docs/en/changelog.md#2-1-150)~~

whats-new/2026-w23.md +0 −70 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 23 · June 1–5, 2026~~

7> Run auto mode on Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry, prompt before writing files that can run code in acceptEdits mode, list installed plugins with /plugin list, and require an approved version range for managed deployments.

~~9Releases [v2.1.158 → v2.1.165](https://code.claude.com/docs/en/changelog.md#2-1-158)~~

~~104 features · June 1–5~~

~~12Auto mode on Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry~~

~~13v2.1.158~~

15Auto mode is now available on Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry for Opus 4.7 and Opus 4.8, replacing permission prompts with background safety checks on third-party providers. Opt in by setting `CLAUDE_CODE_ENABLE_AUTO_MODE=1`.

~~17Opt in on a third-party provider, then cycle to auto mode with Shift+Tab:~~

~~19```bash terminal theme={null}~~

~~20export CLAUDE_CODE_ENABLE_AUTO_MODE=1~~

~~21```~~

~~23[Auto mode on third-party providers](https://code.claude.com/docs/en/permission-modes.md#enable-auto-mode-on-bedrock-agent-platform-or-foundry)~~

~~25Safer automatic edits~~

~~26v2.1.160~~

28Claude Code now prompts before writing files that can run code, even in `acceptEdits` mode. The protected set covers shell startup files such as `.zshenv` and `.bash_login`, git config under `~/.config/git/`, and build-tool configs such as `.npmrc`, `.bazelrc`, and `.pre-commit-config.yaml`. These writes are never auto-approved in any mode except `bypassPermissions`.

~~30Work in acceptEdits mode; Claude now pauses before writing these files:~~

~~32```bash terminal theme={null}~~

~~33claude --permission-mode acceptEdits~~

~~34```~~

~~36[Protected paths](https://code.claude.com/docs/en/permission-modes.md#protected-paths)~~

~~38List installed plugins with /plugin list~~

~~39v2.1.163~~

41The new `/plugin list` command prints your installed plugins inline, without opening the `/plugin` menu, and is also available as `claude plugin list` from the shell. In the interactive form, add `--enabled` or `--disabled` to show only plugins in that state.

~~43List the plugins that are currently turned on:~~

~~45```text Claude Code theme={null}~~

~~46> /plugin list --enabled~~

~~47```~~

~~49[Plugin commands](https://code.claude.com/docs/en/plugins/cli-reference.md#plugin-list)~~

~~51Version requirements for managed deployments~~

~~52v2.1.163~~

54Two managed settings, `requiredMinimumVersion` and `requiredMaximumVersion`, let your organization require an approved Claude Code version range. A client outside the range exits at startup and tells the user to update through the organization's method. `claude update`, `claude install`, and `claude doctor` keep working so users can still recover.

~~56Add a floor to your managed settings so older clients refuse to start:~~

~~58```json managed-settings.json theme={null}~~

~~59{~~

~~60 "requiredMinimumVersion": "2.1.163"~~

~~61}~~

~~62```~~

~~64[Decide what to enforce](https://code.claude.com/docs/en/admin-setup.md#decide-what-to-enforce)~~

~~66Other wins~~

68The trigger keyword for [dynamic workflows](https://code.claude.com/docs/en/workflows.md) changed from `workflow` to `ultracode`; asking for a workflow in your own words still works, and the keyword is highlighted in violet in the prompt[Stop and SubagentStop hooks](https://code.claude.com/docs/en/hooks.md) can return `hookSpecificOutput.additionalContext` to give Claude feedback and keep the turn going instead of being treated as an error`claude mcp` list, get, and add no longer print secrets: environment-variable references are not expanded, and credential headers and URL secrets are redactedA failed Bash command in a parallel tool batch no longer cancels the others; each tool returns its own result independentlyEditing a file no longer needs a separate Read first when you viewed it with a single-file `grep`, `egrep`, or `fgrep`Clicking a command in the autocomplete menu now fills it into your prompt instead of running it immediately; press Enter to runListing `Grep` or `Glob` in `--tools` now provides the dedicated search tools on native builds with embedded search, instead of silently ignoring those names`/effort` now confirms when your chosen level will persist as the default for new sessions`OTEL_RESOURCE_ATTRIBUTES` values are now attached as labels on metric datapoints, so you can slice usage metrics by custom dimensions like team or repoWindsurf is renamed to Devin Desktop in `/ide`, `/terminal-setup`, and `/scroll-speed`, following the editor's rebrand`/btw` gains a `c to copy` shortcut that copies the raw markdown answer to the clipboard

~~70[Full changelog for v2.1.158–v2.1.165 →](https://code.claude.com/docs/en/changelog.md#2-1-158)~~

whats-new/2026-w24.md +0 −55 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 24 · June 8–12, 2026~~

~~7> Move a session to a new directory with /cd, let subagents spawn their own subagents, and troubleshoot a broken configuration with safe mode.~~

~~9Releases [v2.1.166 → v2.1.176](https://code.claude.com/docs/en/changelog.md#2-1-166)~~

~~103 features · June 8–12~~

~~12Move a session with /cd~~

~~13v2.1.169~~

15The new `/cd` command moves the current session to a different working directory without rebuilding the prompt cache: the new directory's `CLAUDE.md` is appended as a message instead of replacing the system prompt. The session relocates to the new directory's project storage, so `--resume` and `--continue` find it there. Claude prompts you to trust the directory if you haven't worked in it before.

~~17Move the session into another project without restarting:~~

~~19```text Claude Code theme={null}~~

~~20> /cd ../other-project~~

~~21```~~

~~23[Commands reference](https://code.claude.com/docs/en/commands.md#all-commands)~~

~~25Subagents can spawn subagents~~

~~26v2.1.172~~

28Subagents can now spawn their own subagents. The subagent panel below the prompt shows the full tree: each row carries a count of its descendants and a path back to `main`. Subagent chains are capped at five levels deep to prevent runaway concurrent trees.

~~30Open the agents view to watch the nested tree as work fans out:~~

~~32```text Claude Code theme={null}~~

~~33> /agents~~

~~34```~~

~~36[Spawn nested subagents](https://code.claude.com/docs/en/sub-agents.md#let-subagents-spawn-their-own-subagents)~~

~~38Troubleshoot with safe mode~~

~~39v2.1.169~~

41Start Claude Code with `--safe-mode`, or set `CLAUDE_CODE_SAFE_MODE`, to launch with all customizations disabled: `CLAUDE.md`, skills, plugins, hooks, MCP servers, and custom commands and agents do not load. Authentication, model selection, built-in tools, and permissions still work. If a problem disappears in safe mode, one of those surfaces is the cause.

~~43Launch a clean session to isolate a broken configuration:~~

~~45```bash terminal theme={null}~~

~~46claude --safe-mode~~

~~47```~~

~~49[Test against a clean configuration](https://code.claude.com/docs/en/debug-your-config.md#test-against-a-clean-configuration)~~

~~51Other wins~~

53[`fallbackModel`](https://code.claude.com/docs/en/model-config#fallback-model-chains) configures up to three fallback models tried in order when the primary is overloaded or unavailable, and `--fallback-model` now applies to interactive sessions tooSession titles are now generated in the language of your conversation; pin a specific one with the `language` setting`claude agents --json` adds `--all` to include completed sessions plus new `id` and `state` fields, and no longer omits blocked or newly dispatched sessionsBrowsing a marketplace's plugins in `/plugin` now has a search barNew `disableBundledSkills` setting and `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` hide bundled skills, workflows, and built-in commands from the modelDeny rules accept a glob in the tool-name position, so `"*"` denies all tools, and unknown tool names in deny rules now warn at startupAgent messaging is hardened: messages relayed via `SendMessage` from other agents no longer carry user authority, and auto mode blocks themAmazon Bedrock reads the AWS region from `~/.aws` config files when `AWS_REGION` is unset, and `/status` shows where the region came fromNew `enforceAvailableModels` managed setting makes the `availableModels` allowlist also constrain the Default modelClaude in Chrome browser tools now load in a single batched call instead of one per tool`claude update` announces the target version before downloading instead of going silentNew `footerLinksRegexes` setting adds regex-matched link badges to the footer row

~~55[Full changelog for v2.1.166–v2.1.176 →](https://code.claude.com/docs/en/changelog.md#2-1-166)~~

whats-new/2026-w25.md +0 −60 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 25 · June 15–19, 2026~~

~~7> Publish a live, shareable page from your session with Artifacts, match tool parameters in deny and ask rules, and set any setting from the prompt with /config.~~

~~9Releases [v2.1.178 → v2.1.183](https://code.claude.com/docs/en/changelog.md#2-1-178)~~

~~103 features · June 15–19~~

~~12Artifacts~~

14An artifact is a live, interactive page that Claude Code publishes from your session to a private URL on claude.ai, and it updates in place as the session keeps working. Ask for one when terminal text is the wrong medium, such as a PR walkthrough with the diff annotated inline or a dashboard built from session data. Artifacts are in beta on Team and Enterprise plans.

16<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/1ylKDoQynT1UgfEK/images/whats-new/artifacts.mp4?fit=max&auto=format&n=1ylKDoQynT1UgfEK&q=85&s=7f5391559d2bc69989621b36322fcff1" />

~~18Ask Claude for a page, then approve the publish prompt:~~

~~20```text title="Claude Code" wrap theme={null}~~

~~21Make an artifact that walks through this PR with the diff annotated inline.~~

~~22```~~

~~24[Create an artifact](https://code.claude.com/docs/en/artifacts.md#create-an-artifact)~~

~~26Match by input parameter~~

~~27v2.1.178~~

29Deny and ask permission rules can now match a tool's input parameters with the `Tool(param:value)` syntax. For example, `Agent(model:opus)` matches subagent spawns that request the Opus model tier. The value accepts `*` as a wildcard, so `Agent(isolation:*)` matches any explicit isolation value.

~~31Add a parameter rule to the deny list in `settings.json`:~~

~~33```json .claude/settings.json {3} theme={null}~~

~~34{~~

~~35 "permissions": {~~

~~36 "deny": ["Agent(model:opus)"]~~

~~37 }~~

~~38}~~

~~39```~~

~~41[Match by input parameter](https://code.claude.com/docs/en/permissions.md#match-by-input-parameter)~~

~~43Set any setting from the prompt~~

~~44v2.1.181~~

~~46Pass `key=value` to `/config` to change a setting directly without opening the Settings interface. The syntax also works in non-interactive mode with the `-p` flag and from Remote Control.~~

~~48Set the `thinking` setting from the prompt:~~

~~50```text title="Claude Code" wrap theme={null}~~

~~51/config thinking=false~~

~~52```~~

~~54[Commands reference](https://code.claude.com/docs/en/commands.md#all-commands)~~

~~56Other wins~~

58Auto mode now blocks destructive git commands (`git reset --hard`, `git clean -fd`, `git stash drop`) when you didn't ask to discard local work, and blocks `terraform destroy` unless you asked for the specific stackSet the new `attribution.sessionUrl` setting to `false` to omit the claude.ai session link from commits and PRs in web and Remote Control sessionsIn the `/config` interface, Enter and Space both change the selected setting, and Esc now saves and closes instead of revertingNew `sandbox.allowAppleEvents` opt-in setting lets sandboxed commands send Apple Events on macOSPoint `CLAUDE_CLIENT_PRESENCE_FILE` at a marker file to suppress mobile push notifications while you're at the machineLong paragraphs now stream line by line instead of waiting for the first line breakAPI connection drops mid-thinking now retry automatically instead of showing "Connection closed while thinking"With `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` set, every session has one implicit team, so you spawn teammates directly with the Agent tool's `name` parameterSkills in nested `.claude/skills` directories load when working on files there; on a name clash the nested skill appears as `<dir>:<name>` so both stay availableFixed prompt caching not reading on a custom `ANTHROPIC_BASE_URL` and on Microsoft FoundryFixed Write and Edit producing zero-byte or truncated files on network drives and cloud-synced folders

~~60[Full changelog for v2.1.178–v2.1.183 →](https://code.claude.com/docs/en/changelog.md#2-1-178)~~

whats-new/2026-w26.md +0 −42 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 26 · June 22–26, 2026~~

~~7> Authenticate MCP servers from your shell with claude mcp login, get a response to shell mode command output with the ! prefix, and resume a conversation from before /clear with /rewind.~~

~~9Releases [v2.1.185 → v2.1.193](https://code.claude.com/docs/en/changelog.md#2-1-185)~~

~~102 features · June 22–26~~

~~12Authenticate MCP servers from the CLI~~

~~13v2.1.186~~

15New `claude mcp login <name>` and `claude mcp logout <name>` commands authenticate a configured MCP server from your shell instead of the interactive `/mcp` menu. `claude mcp login` runs the server's OAuth flow directly, and `claude mcp logout` clears the stored credentials.

~~17Run the OAuth flow for a configured server without opening a session:~~

~~19```bash terminal theme={null}~~

~~20claude mcp login sentry~~

~~21```~~

~~23[Authenticate from the command line](https://code.claude.com/docs/en/mcp.md#authenticate-from-the-command-line)~~

~~25Shell mode responds to command output~~

~~26v2.1.186~~

28Commands you run with the `!` prefix now get a response from Claude once the output lands in the transcript, so you can run `! npm test` and get an explanation of the failures without a second prompt. The response costs the same as sending a normal prompt. To keep the earlier behavior, where the output is added to context without a response, set `respondToBashCommands` to `false` in `settings.json`.

~~30Run a command and get a response to its output:~~

~~32```text Claude Code theme={null}~~

~~33> ! npm test~~

~~34```~~

~~36[Shell mode with the ! prefix](https://code.claude.com/docs/en/interactive-mode.md#shell-mode-with-prefix)~~

~~38Other wins~~

40`/rewind` can now resume a conversation from before `/clear` was runNew `sandbox.credentials` setting blocks sandboxed commands from reading credential files and secret environment variablesOrg-configured model restrictions now apply to the model picker, `--model`, `/model`, and `ANTHROPIC_MODEL`, with a "restricted by your organization's settings" message when a restricted model is selectedNew `autoMode.classifyAllShell` setting routes all Bash and PowerShell commands through the auto-mode classifier, and denial reasons now show in the transcript, the denial toast, and `/permissions`New `claude_code.assistant_response` OpenTelemetry log event carries the model's response text; deployments that already log prompt content start receiving it on upgrade, so set `OTEL_LOG_ASSISTANT_RESPONSES=0` to keep prompts onlyBackground subagents now surface permission prompts in the main session instead of auto-denying; the dialog shows which agent is asking, and Esc denies only that tool`/install-github-app` can now install only the GitHub App and skip the Actions workflow and secret stepsHosts you allow in the sandbox network permission dialog are remembered for the rest of the session instead of re-prompting on every connectionStreaming responses use about 37% less CPU, and long-session memory growth from the terminal output cache is reduced`/review <pr>` now uses the same review engine as `/code-review medium`Bash mode `!` commands get live file path autocomplete

~~42[Full changelog for v2.1.185–v2.1.193 →](https://code.claude.com/docs/en/changelog.md#2-1-185)~~

whats-new/2026-w27.md +0 −65 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 27 · June 29 – July 3, 2026~~

7> Claude Sonnet 5 becomes the default model, Claude in Chrome reaches general availability, subagents run in the background by default, Claude Desktop arrives on Linux in beta, and /radio tunes into Claude FM.

~~9Releases [v2.1.195 → v2.1.201](https://code.claude.com/docs/en/changelog.md#2-1-195)~~

~~105 features · June 29 – July 3~~

~~12Claude Sonnet 5~~

~~13new model~~

15Sonnet 5 is the new default model for Pro, Team Standard, and Enterprise subscription seats: top-tier coding and tool use at Sonnet pricing, with a native 1M-token context window and adaptive thinking on by default. API pricing is promotional at \$2/\$10 per MTok through August 31. Requires v2.1.197 or later.

~~17Switch to Sonnet 5 by name, or pick it from the model picker:~~

~~19```text Claude Code theme={null}~~

~~20> /model claude-sonnet-5~~

~~21```~~

~~23[Model configuration](https://code.claude.com/docs/en/model-config.md#available-models)~~

~~25Claude in Chrome is generally available~~

~~26v2.1.198~~

28The Chrome integration is out of preview for everyone on a direct Anthropic plan. Claude Code drives your browser through the Claude in Chrome extension: it opens tabs, clicks through pages, fills forms, reads console logs, and shares your login state, so it can test the app it builds without you switching contexts.

~~30[Use Claude Code with Chrome](https://code.claude.com/docs/en/chrome.md)~~

~~32Subagents run in the background by default~~

~~33v2.1.198~~

35Claude now keeps working while subagents run and picks up their results when they finish, instead of pausing the conversation to wait. Claude still runs a subagent in the foreground when it needs the result before continuing, and background subagents surface every permission prompt in your main session. Pin a subagent's behavior with the `background` frontmatter field.

~~37[Run subagents in foreground or background](https://code.claude.com/docs/en/sub-agents.md#run-subagents-in-foreground-or-background)~~

~~39Claude Desktop on Linux~~

~~40Desktop~~

42The Claude desktop app is now available on Ubuntu 22.04+ and Debian 12+ in beta, on x86\_64 and arm64. You get the same Chat, Cowork, and Claude Code experience as macOS and Windows: parallel sessions, visual diff review, an integrated terminal and editor, and live app preview. Installs from Anthropic's apt repository, so updates arrive through regular package updates.

~~44[Claude Desktop on Linux](https://code.claude.com/docs/en/desktop-linux.md)~~

~~46/radio~~

~~47CLI~~

49Claude FM is on the air. `/radio` opens the lo-fi radio stream in your browser for something to code to, and prints the stream URL when no browser is available. Not available on Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry.

51<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/x358isu_VzLnyTEN/images/whats-new/radio.mp4?fit=max&auto=format&n=x358isu_VzLnyTEN&q=85&s=36a0c33859cef119c7192dceea8bcbd3" />

~~53Tune in from any session:~~

~~55```text Claude Code theme={null}~~

~~56> /radio~~

~~57```~~

~~59[All commands](https://code.claude.com/docs/en/commands.md#all-commands)~~

~~61Other wins~~

63[Artifacts](https://code.claude.com/docs/en/artifacts.md) are now generally available and included on Pro and Max plans, joining Team and EnterpriseAdmins can set an [organization default model](https://code.claude.com/docs/en/model-config.md#organization-default-model) in the org console; it shows as "Org default" in `/model` when you haven't picked a model yourselfStacked skill invocations like `/skill-a /skill-b do XYZ` now load all leading skills (up to 5), not only the first`AskUserQuestion` dialogs no longer auto-continue by default; opt into an idle timeout via `/config`The "default" permission mode is now named "Manual" across the CLI, `--help`, VS Code, and JetBrains; `--permission-mode manual` is accepted alongside `default`New `/dataviz` skill gives chart and dashboard design guidance, with a runnable color-palette validatorThe built-in Explore agent now inherits the main session's model (capped at Opus) instead of running on HaikuBackground agents launched from `claude agents` now commit, push, and open a draft PR when they finish code work in a worktree, instead of stopping to askHook matchers with hyphenated identifiers like `code-reviewer` now exact-match instead of substring-matching; use `mcp__brave-search__.*` to match all tools from a hyphenated MCP serverTransient server rate-limit errors unrelated to your usage limit are now retried automatically with backoff for subscribers instead of failing the turnThe streaming idle watchdog is now on by default for all providers: it aborts and retries when a response stream produces no events for 5 minutes (`CLAUDE_ENABLE_STREAM_WATCHDOG=0` to disable)

~~65[Full changelog for v2.1.195–v2.1.201 →](https://code.claude.com/docs/en/changelog.md#2-1-195)~~

whats-new/2026-w28.md +0 −38 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 28 · July 6–10, 2026~~

~~7> Browse external sites from the Desktop app's built-in browser, run a full setup checkup with /doctor, and pick up auto mode transcript protections and agent view upgrades.~~

~~9Releases [v2.1.202 → v2.1.206](https://code.claude.com/docs/en/changelog.md#2-1-202)~~

~~102 features · July 6–10~~

~~12In-app browser on Desktop~~

~~13Desktop~~

15Claude Code on desktop now has a built-in browser. Claude can pull up docs, designs, or any other site, and read, click through, and interact with pages the same way it does with your local dev server previews. The browser is sandboxed and configurable: you choose whether browsing sessions persist, and safety classifiers review actions on external sites.

17<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/x358isu_VzLnyTEN/images/whats-new/desktop-browser.mp4?fit=max&auto=format&n=x358isu_VzLnyTEN&q=85&s=8033e85a1cb0a37870a79e702c18f4e4" />

~~19[Browse external sites](https://code.claude.com/docs/en/desktop.md#browse-external-sites)~~

~~21/doctor is a full setup checkup~~

~~22v2.1.205~~

24`/doctor` now diagnoses issues and can fix them, instead of printing a read-only report. It checks installation health, finds unused skills, MCP servers, and plugins versus their context cost, deduplicates local `CLAUDE.md` files against checked-in ones, proposes trimming `CLAUDE.md` content Claude could derive from the codebase, and flags slow hooks. It reports findings first and asks for confirmation before changing anything. `/checkup` is its alias.

~~26Run a checkup from any session:~~

~~28```text Claude Code theme={null}~~

~~29> /doctor~~

~~30```~~

~~32[All commands](https://code.claude.com/docs/en/commands.md#all-commands)~~

~~34Other wins~~

36Auto mode now blocks tampering with session transcript files, and asks before running `rm -rf` on a variable it can't resolve from context`/cd` now suggests directory paths as you type, matching `/add-dir``/commit-push-pr` auto-allows `git push` to the repo's configured push remote in addition to `origin`Gateway: `/login` now supports Anthropic-operated public gateway endpoints`EnterWorktree` asks for confirmation before entering a git worktree outside the project's `.claude/worktrees/` directoryBackground agents upgrade to a new version in the background right after a Claude Code update, instead of paying a slow stale-session upgrade when you attachAgent view rows now show a colored state word and a classifier-written headline instead of raw tool call text, and sessions that edit, merge, comment on, or push to an existing PR link it in `claude agents`Auto-update binary downloads now stream to disk instead of buffering in memory, cutting the updater's peak memory usage by roughly 400 MBBackground task notifications now explicitly state that no human input has occurred, preventing fabricated in-transcript approvals from being acted onImproved `/code-review` findings quality on Opus 4.8 across all effort levels

~~38[Full changelog for v2.1.202–v2.1.206 →](https://code.claude.com/docs/en/changelog.md#2-1-202)~~

whats-new/2026-w29.md +0 −44 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 29 · July 13–17, 2026~~

~~7> Pull live data into published artifacts through MCP connectors, and use Claude Code with a screen reader in the new screen reader mode.~~

~~9Releases [v2.1.207 → v2.1.212](https://code.claude.com/docs/en/changelog.md#2-1-207)~~

~~102 features · July 13–17~~

~~12Artifacts call your MCP connectors~~

~~13web~~

15A published artifact can now call MCP connectors each time someone views it, so a dashboard shows live data and can take actions on demand rather than a snapshot from the session that built it. Each call runs through the viewing account's own connections, and viewers approve access before the page's first connector call. This week also adds public sharing links, editor roles for shared editing on Team and Enterprise plans, and artifacts created from Claude Tag sessions.

17<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/ItzF3QVI6L0QypjJ/images/whats-new/artifacts-mcp.mp4?fit=max&auto=format&n=ItzF3QVI6L0QypjJ&q=85&s=ff8b81ed52b26c773899dc28cec959e6" />

~~19Name the connector and the data you want in your prompt:~~

~~21```text title="Claude Code" wrap theme={null}~~

~~22Build a dashboard artifact of open pull requests that pulls the live list through my GitHub connector when the page loads.~~

~~23```~~

~~25[Pull live data with MCP connectors](https://code.claude.com/docs/en/artifacts.md#pull-live-data-with-mcp-connectors)~~

~~27Screen reader mode~~

~~28CLI~~

30Screen reader mode replaces the visual terminal interface with plain, linear text: instead of boxes, spinners, and in-place redraws, Claude Code prints labeled lines that a screen reader such as VoiceOver or NVDA reads in order, so you can approve permissions and review output end to end. Turn it on per session with a flag, per shell with the `CLAUDE_AX_SCREEN_READER` environment variable, or everywhere with the `axScreenReader` setting.

~~32Start a session in screen reader mode:~~

~~34```bash terminal theme={null}~~

~~35claude --ax-screen-reader~~

~~36```~~

~~38[Turn on screen reader mode](https://code.claude.com/docs/en/accessibility.md#turn-on-screen-reader-mode)~~

~~40Other wins~~

42`/fork` now copies your conversation into a new background session with its own row in `claude agents` while you keep working; the in-session forked subagent it used to launch is now `/subtask`[Auto mode](https://code.claude.com/docs/en/permission-modes.md#enable-auto-mode-on-bedrock-agent-platform-or-foundry) no longer needs the `CLAUDE_CODE_ENABLE_AUTO_MODE` opt-in on Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry; administrators can turn it off with `disableAutoMode`MCP tool calls that run longer than two minutes now move to the background automatically so the session stays usable; tune or disable the threshold with `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`New `claude auto-mode reset` restores the default auto-mode configuration, and `--yes` skips the confirmation promptNew [corporate launcher](https://code.claude.com/docs/en/corporate-launcher.md) support: `CLAUDE_CODE_PROCESS_WRAPPER` or the `processWrapper` setting runs the processes Claude Code starts from its own binary, such as the background service and agent view sessions, through a required wrapper executable`vimInsertModeRemaps` setting maps two-key insert-mode sequences such as `jj` to Escape in vim mode`--forward-subagent-text` and `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` include subagent text and thinking blocks in [stream-json output](https://code.claude.com/docs/en/headless.md)Session-wide caps stop runaway loops: WebSearch calls and subagent spawns each default to 200, tunable with `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` and `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION`"Always allow" permission rules save at the repository root, so approvals granted in a git worktree persist across sessions and worktreesAmazon Bedrock, Google Cloud's Agent Platform, and Claude Platform on AWS now default to Claude Opus 4.8The collapsed tool summary line shows a live elapsed-time counter, so long-running tool calls visibly tick instead of looking stuck

~~44[Full changelog for v2.1.207–v2.1.212 →](https://code.claude.com/docs/en/changelog.md#2-1-207)~~

whats-new/2026-w30.md +0 −59 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 30 · July 20–24, 2026~~

~~7> Opus 5 becomes the default Opus model, Claude Code Desktop adds an iOS Simulator pane, and the Claude Security plugin scans your code for vulnerabilities.~~

~~9Releases [v2.1.214 → v2.1.219](https://code.claude.com/docs/en/changelog.md#2-1-214)~~

~~103 features · July 20–24~~

~~12Claude Opus 5~~

~~13new model~~

15Claude Opus 5 is the new default Opus model in Claude Code. It's the default on Max, Team Premium, Enterprise pay-as-you-go, and the Anthropic API, and on Claude Platform on AWS, Amazon Bedrock, and Google Cloud's Agent Platform. On the Anthropic API and on Max, Team, and Enterprise plans, Opus 5 runs with a [1M-token context window](https://code.claude.com/docs/en/model-config.md#extended-context); on Amazon Bedrock and Google Cloud's Agent Platform, select the 1M model variant. Fast mode moves to Opus 5 at \$10/\$50 per MTok. Requires v2.1.219 or later.

17<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/N3yEaTYPXMXFrF6k/images/whats-new/opus-5.mp4?fit=max&auto=format&n=N3yEaTYPXMXFrF6k&q=85&s=8536b1cb3180e539008f39930403e47b" />

~~19Switch to Opus 5 by name, or pick it from the model picker:~~

~~21```text Claude Code theme={null}~~

~~22> /model claude-opus-5~~

~~23```~~

~~25[Model configuration](https://code.claude.com/docs/en/model-config.md#available-models)~~

~~27iOS Simulator in Claude Code Desktop~~

~~28Desktop~~

30Claude Code Desktop on macOS gets an iOS Simulator pane, in public beta on Pro, Max, and Team plans. When Claude builds, launches, or checks your app in a simulator, the pane opens next to the conversation and streams the device screen live, so you can watch Claude tap through the app to verify its changes or drive the device yourself. Requires Xcode with the iOS platform installed, and Claude Desktop v1.24012.0 or later.

32![Claude Code Desktop with the iOS Simulator pane showing an iPhone app next to the conversation](https://mintcdn.com/claude-code/N3yEaTYPXMXFrF6k/images/whats-new/ios-simulator.jpg?fit=max\&auto=format\&n=N3yEaTYPXMXFrF6k\&q=85\&s=6c88418ed14ed0fb12cc1af75b17f2ee)

~~34Ask Claude to run or test your app, and the pane opens when the app launches:~~

~~36```text Claude Code theme={null}~~

~~37> Build the app and run it in the simulator to check the onboarding flow.~~

~~38```~~

~~40[Test iOS apps in the simulator](https://code.claude.com/docs/en/desktop-ios-simulator.md#run-your-app-in-the-simulator)~~

~~42Claude Security plugin~~

~~43plugin~~

45The Claude Security plugin runs a multi-agent vulnerability scan of your codebase inside a Claude Code session: agents map your architecture, build a threat model, hunt for vulnerabilities, and independently review every finding before writing the report to a `CLAUDE-SECURITY-<timestamp>/` directory. Scan a whole repository or only a branch's diff, a pull request, or a single commit, then turn the findings you choose into reviewed patches that you apply yourself.

~~47Install the plugin from the official Anthropic marketplace, run `/reload-plugins`, then start a scan with `/claude-security`:~~

~~49```text Claude Code theme={null}~~

~~50> /plugin install claude-security@claude-plugins-official~~

~~51```~~

~~53[Scan and fix your codebase](https://code.claude.com/docs/en/claude-security.md#scan-and-fix-your-codebase)~~

~~55Other wins~~

57[`/code-review`](https://code.claude.com/docs/en/code-review-local) now runs as a background subagent with its own context window, so review work stays out of your conversation and the findings arrive when it completes`/verify`, `/code-review`, and `/deep-research` run only when you invoke them; Claude no longer launches them on its own[Emoji shortcodes](https://code.claude.com/docs/en/interactive-mode.md#emoji-shortcodes) autocomplete in the prompt input: type `:heart:` to insert an emoji, or two or more characters after `:` for suggestions; turn it off with `emojiCompletionEnabled`Skills with `context: fork` [run in the background](https://code.claude.com/docs/en/skills.md#run-skills-in-a-subagent) by default, and `background: false` in the skill's frontmatter waits for the result in the same turnA session runs up to 20 subagents concurrently by default; change the [limit](https://code.claude.com/docs/en/sub-agents.md#concurrent-subagent-limit) with `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS``--max-budget-usd` now enforces the cap on subagents: once spend reaches it, Claude can't start more and running background subagents stopNew [`sandbox.filesystem.disabled`](https://code.claude.com/docs/en/sandboxing#disable-filesystem-isolation) setting skips filesystem isolation while keeping network egress controlIn auto mode, the checks for dangerous `rm` commands, background jobs, and suspicious Windows paths no longer open permission dialogs; the auto-mode classifier adjudicates them insteadBash permission checks fail closed on more shell forms, including file-descriptor redirects, Zsh variable subscripts in `[[ ]]` comparisons, `help` and `man` invocations that could run unsafe options, and commands over 10,000 characters[Fast mode](https://code.claude.com/docs/en/fast-mode.md) no longer supports Opus 4.7: `/fast` now applies to Opus 5 and Opus 4.8Long-running tool calls emit a periodic progress heartbeat instead of going silent

~~59[Full changelog for v2.1.214–v2.1.219 →](https://code.claude.com/docs/en/changelog.md#2-1-214)~~

whats-new/2026-w32.md +0 −69 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 32 · August 3–7, 2026~~

~~7> Claude Code sessions message each other, self-hosted environments run cloud sessions on your infrastructure, and auto mode becomes the default permission mode.~~

~~9Releases [v2.1.220 → v2.1.224](https://code.claude.com/docs/en/changelog.md#2-1-220)~~

~~103 features · August 3–7~~

~~12Cross-session messaging~~

~~13v2.1.224~~

15Your Claude Code sessions can now message each other. Claude discovers your other sessions with the `ListAgents` tool and sends with `SendMessage`, either when you ask it to or on its own, such as after a change in one session affects what another is working on. A message is text Claude writes for the other session, never your conversation history or files. Available on macOS and Linux. Requires v2.1.224 or later.

17<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/N3yEaTYPXMXFrF6k/images/whats-new/cross-session-messaging.mp4?fit=max&auto=format&n=N3yEaTYPXMXFrF6k&q=85&s=8f33c3390f78660a4a26dc980f46159f" />

~~19With two sessions open on the same machine, ask one of them to pass something along:~~

~~21```text title="Claude Code" wrap theme={null}~~

~~22Tell the session working on the payments API that users.name is now users.display_name~~

~~23```~~

~~25The other session shows a `Message from` row once Claude has read the message; press `Ctrl+O` to expand it. To see which sessions Claude can reach, run `/list-agents`.~~

~~27[Message another session](https://code.claude.com/docs/en/cross-session-messaging.md#message-another-session)~~

~~29Self-hosted environments~~

~~30v2.1.224~~

32Self-hosted environments run Claude Code cloud sessions on your organization's own infrastructure, in public beta on Team and Enterprise plans. Run `claude self-hosted-runner` on your machines or containers to turn them into runners. When someone picks your environment while starting a session from claude.ai, the mobile or desktop apps, or `claude --cloud`, that session runs inside your network, with access to your internal services. An Owner turns on **Allow self-hosted environments** in [admin settings](https://claude.ai/admin-settings/cloud-environments) first.

34![The self-hosted environments admin page listing environments such as linux-dev and macos-prod with their status and active session counts](https://mintcdn.com/claude-code/N3yEaTYPXMXFrF6k/images/whats-new/self-hosted-environments.jpg?fit=max\&auto=format\&n=N3yEaTYPXMXFrF6k\&q=85\&s=ae9152cb1670c8af517d1aee57689b14)

~~36Signed in as an Owner, run the guided setup, which walks you through creating the environment and starts a runner:~~

~~38```bash terminal theme={null}~~

~~39claude self-hosted-runner setup~~

~~40```~~

~~42The environment shows **Healthy** in admin settings once the runner registers.~~

~~44[Self-hosted environments quickstart](https://code.claude.com/docs/en/self-hosted-environments-quickstart.md#set-up-an-environment-and-runner)~~

~~46Auto mode becomes the default~~

~~47CLI~~

49Starting August 14, auto mode is the default permission mode for new sessions on Pro, Max, and Team plans. If you set a default mode yourself, it stays in place unless you accept the one-time switch prompt, and a default your organization manages doesn't change. You can still switch modes at any time. Already in effect on those plans: the classifier calls auto mode makes no longer count toward your usage limits.

~~51To start every session in auto mode before the switch, set it as your default in your user settings:~~

~~53```json ~/.claude/settings.json {3} theme={null}~~

~~54{~~

~~55 "permissions": {~~

~~56 "defaultMode": "auto"~~

~~57 }~~

~~58}~~

~~59```~~

~~61New sessions then show `auto mode on` in the status bar.~~

~~63[Auto mode requirements and controls](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode)~~

~~65Other wins~~

67The VS Code extension gets [Focus view](https://code.claude.com/docs/en/vs-code.md#extension-settings), which hides tool activity behind one expandable row per turn; toggle it from the command menu or with `Ctrl+Alt+F` (`Ctrl+Option+F` on Mac)Sandbox credential files accept [`mode: "mask"`](https://code.claude.com/docs/en/sandboxing#mask-credential-files) on Linux and WSL2, so sandboxed commands read a sentinel copy while the sandbox proxy substitutes the real value on egress; credential masking also gains `extract`, JWT-aware `decode`, and AWS SigV4 re-signing optionsMarketplaces can distribute a plugin as a [zip archive](https://code.claude.com/docs/en/plugins/marketplace-reference.md#archive-plugin-source) with the new `archive` source, downloaded over HTTPS with an optional SHA-256 pin, so installs work without git or npm`/review` is now an alias of [`/code-review`](https://code.claude.com/docs/en/code-review-local), and `/code-review` with no effort level reuses the level you typed lastA session you copy with [`/fork`](https://code.claude.com/docs/en/agent-view#copy-the-session-with-%2Ffork) now makes its code changes in a worktree of its own instead of the original session's checkoutPlugins you install from [`/plugin`](https://code.claude.com/docs/en/plugins/install#install-a-plugin) activate in the current session when it's safe to do so; the install summary reports `Plugin is now active.` or tells you to run `/reload-plugins`[Background sessions](https://code.claude.com/docs/en/agent-view.md#how-file-edits-are-isolated) that changed code in a worktree now commit and push before finishing, open a draft pull request only when the task calls for one, and follow the git instructions in your `CLAUDE.md`The 200-subagent-per-session cap is removed, so long-running sessions no longer refuse new subagents; the [concurrency](https://code.claude.com/docs/en/sub-agents.md#concurrent-subagent-limit) and depth limits still applyA repository's checked-in settings can no longer turn on [Remote Control auto-connect](https://code.claude.com/docs/en/remote-control.md#enable-remote-control-for-all-sessions); set `remoteControlAtStartup` in your user or managed settings instead, and project and local settings can only turn it off[Worktree isolation](https://code.claude.com/docs/en/worktrees.md#how-claude-code-enforces-isolation) now blocks not only file edits but also Bash commands and git redirects that reach the main checkout, in every session type and in the session's subagentsA Bash command can no longer hide part of itself from permission checks, and tab or invisible-Unicode padding no longer hides part of a command from the approval dialogPreToolUse auto-allow hooks no longer bypass tool restrictions in Claude Code's internal side tasks such as summaries and compactionThe [Ultraplan](https://code.claude.com/docs/en/ultraplan) research preview is removed, including the `/ultraplan` command and the `ultraplan` keyword; use plan mode or Claude Code on the web instead

~~69[Full changelog for v2.1.220–v2.1.224 →](https://code.claude.com/docs/en/changelog.md#2-1-220)~~

whats-new/2026-w33.md +0 −57 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 33 · August 10–14, 2026~~

~~7> Claude Code Desktop auto-continues after a usage limit resets, fork mode turns on by default, and GitLab merge requests and marketplaces join GitHub.~~

~~9Releases [v2.1.225 → v2.1.233](https://code.claude.com/docs/en/changelog.md#2-1-225)~~

~~103 features · August 10–14~~

~~12Auto-continue after a usage limit on Desktop~~

~~13Desktop~~

15When you hit your session limit in the Code tab of Claude Code Desktop, the limit card now offers an **Auto-continue when limits reset** checkbox. Check it, and the Desktop app retries the interrupted turn after the reset. The card shows the retry time. The weekly-limit card doesn't offer it.

17<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/2SnAdpL4dJ18nKb3/images/whats-new/desktop-auto-continue.mp4?fit=max&auto=format&n=2SnAdpL4dJ18nKb3&q=85&s=1937f489695feaea715e48ecfd7e62cd" />

19The next time a session-limit card appears, check **Auto-continue when limits reset** and leave the session open. The card shows `Auto-resuming at` followed by the reset time, and the turn picks up on its own once the limit resets.

~~21[What to do when you hit a usage limit](https://code.claude.com/docs/en/errors.md#youve-hit-your-session-limit)~~

~~23Fork mode on by default~~

~~24v2.1.232~~

26Fork mode is now on by default in interactive sessions. Claude can request the `fork` subagent type, which inherits the full conversation and prompt cache instead of starting fresh, so you don't have to re-explain the context for a side task. Subagents Claude spawns in interactive sessions, apart from the ones an agent-team teammate spawns, also run in the background by default.

~~28Start a fork yourself with a task that needs everything you've discussed so far:~~

~~30```text Claude Code theme={null}~~

~~31> /subtask draft unit tests for the parser changes so far~~

~~32```~~

~~34The fork appears in the panel below your prompt and its result arrives in your conversation when it finishes. To turn fork mode off, set `CLAUDE_CODE_FORK_SUBAGENT=0`.~~

~~36[Turn fork mode on or off](https://code.claude.com/docs/en/sub-agents.md#turn-fork-mode-on-or-off)~~

~~38GitLab merge requests and marketplaces~~

~~39v2.1.232~~

41Plugin marketplaces clone bare `gitlab.com` URLs, including nested subgroups. On v2.1.233 or later, pass a GitLab merge request URL to `--worktree` to branch from it, and the `claude agents` view labels sessions linked to a merge request as `!N`. Claude Code also redacts GitLab token families such as `glpat-` and `glrt-`, and protects the `glab` CLI's config store the same way it protects `gh`.

~~43Start a session in a worktree branched from a merge request:~~

~~45```bash terminal theme={null}~~

~~46claude --worktree https://gitlab.com/group/project/-/merge_requests/42~~

~~47```~~

~~49When `origin` is on gitlab.com, Claude Code fetches `merge-requests/42/head` and opens the session on that branch in its own worktree.~~

~~51[Branch a worktree from a pull or merge request](https://code.claude.com/docs/en/worktrees.md#branch-from-a-pull-request)~~

~~53Other wins~~

55Type `@` in the prompt to [mention another Claude session](https://code.claude.com/docs/en/cross-session-messaging.md#message-another-session) by name, and Claude messages it directly with `SendMessage`; a bare name that matches exactly one live session now delivers without a confirmation stepInteractive sessions on one machine keep [unique names](https://code.claude.com/docs/en/cross-session-messaging.md#see-which-sessions-claude-can-reach): if you start or rename a session with a name another live session already uses, Claude Code gives yours a `name-word-word` variant and tells youPlugin marketplaces accept [`command` sources](https://code.claude.com/docs/en/plugins/marketplace-reference#command-plugin-source): a local command prints the plugin directory, which Claude Code re-resolves each session and applies without a restartOn Linux and WSL, set [`CLAUDE_CODE_TOOL_MEMORY_LIMIT`](https://code.claude.com/docs/en/tools-reference#memory-limit-on-linux-and-wsl) to a size such as `4G` to cap the memory Bash and PowerShell tool commands can useThe task-tracking tools, such as `TaskCreate`, `TaskUpdate`, and `TodoWrite`, are [no longer available on Opus 4.8, Sonnet 5, Fable 5, Mythos 5, and later models in those families](https://code.claude.com/docs/en/tools-reference.md#task-tool-availability); set `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` to re-enable them[`/code-review`](https://code.claude.com/docs/en/code-review-local) at high, xhigh, and max effort now runs in a background agent like the other levels[`/plugin install plugin@marketplace`](https://code.claude.com/docs/en/plugins/install#install-a-plugin) refreshes the marketplace first, so newly published plugins install without a manual marketplace updateSettings accept [`additionalMarketplaces` and `allowedMarketplaces`](https://code.claude.com/docs/en/settings-reference#marketplace-key-aliases) as aliases for `extraKnownMarketplaces` and `strictKnownMarketplaces`On newer models, Claude can [overwrite an existing file with the Write tool](https://code.claude.com/docs/en/tools-reference.md#write-tool-behavior) without reading it first this session, matching the Edit tool's rules; older models require the readThe VS Code extension can [organize the sessions list into groups](https://code.claude.com/docs/en/vs-code.md#organize-sessions-into-groups): right-click to create, rename, or delete a group, and Cmd/Ctrl- or Shift-click to move several sessions at onceIf your organization routes Claude Code through a [Claude apps gateway with spend limits](https://code.claude.com/docs/en/claude-apps-gateway-spend-limits.md), Claude Code shows the limit period, its reset time, and the operator's message when you reach the limit

~~57[Full changelog for v2.1.225–v2.1.233 →](https://code.claude.com/docs/en/changelog.md#2-1-225)~~

whats-new/2026-w34.md +0 −69 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 34 · August 17–21, 2026~~

~~7> Draft editable UI artboards with the /design skill, set the Concise output style, and start a Claude Code session on your machine from your phone.~~

~~9Releases [v2.1.234 → v2.1.239](https://code.claude.com/docs/en/changelog.md#2-1-234)~~

~~103 features · August 17–21~~

~~12/design~~

~~13research preview~~

15The `/design` skill brings Claude Design's artboard workflow into the CLI and Claude Code Desktop, built on artifacts. Run it with a brief and Claude publishes a canvas of editable artboards for your UI. Pick one, tweak it, then have Claude implement it. Available on Pro, Max, Team, and Enterprise. Requires v2.1.234 or later.

17<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/2SnAdpL4dJ18nKb3/images/whats-new/design-skill.mp4?fit=max&auto=format&n=2SnAdpL4dJ18nKb3&q=85&s=0b376a94227c14a4204af89c4c9fd7ac" />

~~19Describe what you want designed and let Claude draft the options:~~

~~21```text Claude Code theme={null}~~

~~22> /design redesign the composer based on what people actually use it for~~

~~23```~~

~~25Claude prints a link to the published canvas. Open it, pick an artboard, and tell Claude which option to implement.~~

~~27[Where artifacts are available](https://code.claude.com/docs/en/artifacts.md#availability)~~

~~29Concise output style~~

~~30v2.1.237~~

32Concise is a new built-in output style. Claude leads with the result and skips preamble and narration, while doing the work as thoroughly as in the Default style. When you ask for an explanation or more detail, Claude answers in full. Error reports, security warnings, and confirmations for destructive actions keep their complete content.

34<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/2SnAdpL4dJ18nKb3/images/whats-new/concise-output-style.mp4?fit=max&auto=format&n=2SnAdpL4dJ18nKb3&q=85&s=dfb40ec8921ed1bc82eb629042a8ec17" />

~~36Turn it on under **Output style** in `/config`, or set it in your settings file:~~

~~38```json ~/.claude/settings.json {2} theme={null}~~

~~39{~~

~~40 "outputStyle": "Concise"~~

~~41}~~

~~42```~~

~~44Run `/clear` or start a new session, and Claude's replies lead with the result.~~

~~46[Built-in output styles](https://code.claude.com/docs/en/output-styles.md#built-in-output-styles)~~

~~48Start a session on your machine from your phone~~

~~49mobile~~

~~51Any machine running `claude remote-control` now shows up as a device card at the top of the Code tab in the Claude app. Remote Control is also out of research preview.~~

53![The Code tab in the Claude mobile app with a Devices section showing a connected MacBook as a device card above the sessions list](https://mintcdn.com/claude-code/2SnAdpL4dJ18nKb3/images/whats-new/remote-control-phone-start.jpg?fit=max\&auto=format\&n=2SnAdpL4dJ18nKb3\&q=85\&s=9f0ebedab23aa0e1732cc37782573907)

~~55Start Remote Control on the machine you want to reach, then open the Code tab on your phone:~~

~~57```bash terminal theme={null}~~

~~58claude remote-control~~

~~59```~~

~~61Your machine appears as a device card at the top of the Code tab. Tap it to pick a directory and start a session there.~~

~~63[Start a Remote Control session](https://code.claude.com/docs/en/remote-control.md#start-a-remote-control-session)~~

~~65Other wins~~

67Claude Code now continues your session automatically when a claude.ai usage limit resets; turn it off from the **Continue automatically at usage limit** row in `/config`The optional [`spellcheck` setting](https://code.claude.com/docs/en/interactive-mode#check-spelling-as-you-type) underlines misspelled words in the prompt input as you type, using your installed `aspell`, `hunspell`, or `ispell`On a branch with an open GitLab merge request, with the `glab` CLI authenticated through `glab auth login`, the footer shows an [`MR !N` badge](https://code.claude.com/docs/en/interactive-mode#gitlab-merge-requests) colored by whether the merge request is a draft, open, or mergeableChange the effort level from your phone or claude.ai/code and it [applies to the session on your machine](https://code.claude.com/docs/en/remote-control.md#what-connected-devices-see); Remote Control sessions hosted by Desktop or VS Code also show connected devices the session's current permission modeYou can open [`/permissions`](https://code.claude.com/docs/en/permissions#manage-permissions) or run `/add-dir <path>` while Claude is working; permission rule changes apply to the rest of the current turnWhen background tasks keep a [`/goal`](https://code.claude.com/docs/en/goal#background-work-defers-evaluation) waiting, Claude checks in on them after 30 minutes instead of waiting indefinitely and keeps checking in, at longer intervals while the session sits idle; set `CLAUDE_CODE_GOAL_CHECKIN_MINUTES=0` to opt outYour own prompts now render markdown in the transcript, with highlighted code blocks, inline code, and lists, the same way replies doThe new [`ANTHROPIC_DEFAULT_MODEL`](https://code.claude.com/docs/en/model-config#set-a-default-model-for-new-sessions) environment variable sets the model new sessions start on; a `/model` pick still overrides it and persists across restartsWith the `notify_when_idle` input on `SendMessage`, Claude can ask another Claude Code session on the same machine to [send one notice when it next goes idle](https://code.claude.com/docs/en/cross-session-messaging.md#get-a-notice-when-another-session-goes-idle)Set [`keybindingFlavor`](https://code.claude.com/docs/en/interactive-mode#make-ctrl-w-delete-back-to-whitespace) to `"readline"` to make `Ctrl+W` in the prompt delete back to the previous whitespace, as Bash does, instead of stopping at punctuation such as `/`On native Windows, your Claude Code sessions can now [message each other](https://code.claude.com/docs/en/cross-session-messaging.md#availability) with `SendMessage` and find each other with `ListAgents`, as on macOS and LinuxSelf-hosted runners accept `--defer-shutdown-max-min`, which [keeps serving attached sessions](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#defer-the-drain-past-the-first-signal) for a set number of minutes after SIGTERMSelf-hosted runners accept `--proxy-authorization-command` or `--proxy-authorization-file` to supply a fresh `Proxy-Authorization` header for [egress proxies that require one](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#authenticate-to-an-egress-proxy)

~~69[Full changelog for v2.1.234–v2.1.239 →](https://code.claude.com/docs/en/changelog.md#2-1-234)~~

whats-new/2026-w35.md +0 −65 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 35 · August 24–28, 2026~~

~~7> Resume terminal sessions in the Claude Code Desktop app, review feedback reports that Claude drafts for you, and start a session in restricted mode.~~

~~9Releases [v2.1.240 → v2.1.250](https://code.claude.com/docs/en/changelog.md#2-1-240)~~

~~103 features · August 24–28~~

~~12Resume terminal sessions in the Desktop app~~

~~13Desktop~~

15Type `/resume` in the Claude Code Desktop prompt box to pick up any session you started from the CLI and continue it in the app with the full conversation and context intact. Search your sessions by title, folder, or branch, and preview where you left off before you resume.

17<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/f9HTZGyMtxIFOUgt/images/whats-new/desktop-resume-cli-session.mp4?fit=max&auto=format&n=f9HTZGyMtxIFOUgt&q=85&s=41e4a5fda6b9d63280589f2cbdabf44f" />

~~19In a Desktop session, run the command to list your terminal sessions:~~

~~21```text Claude Code theme={null}~~

~~22> /resume~~

~~23```~~

~~25Select a session and press `Enter`. The conversation opens in the app where you left off.~~

~~27[Move between the CLI and Desktop](https://code.claude.com/docs/en/desktop.md#coming-from-the-cli)~~

~~29Claude-drafted feedback~~

~~30CLI~~

32When a tool keeps failing, Claude can't help with a request, or you point out a mistake, Claude now drafts a feedback report for you with the `SendFeedback` tool. A card above your prompt shows the draft, and you can review, send, or dismiss it from there. Nothing reaches Anthropic until you send it. Requires v2.1.238 or later.

34![A Claude Code session where Claude has drafted a bug report titled Sandbox image pull fails behind proxy, shown as a card above the prompt with options to review, send, or dismiss](https://mintcdn.com/claude-code/f9HTZGyMtxIFOUgt/images/whats-new/claude-drafted-feedback.jpg?fit=max\&auto=format\&n=f9HTZGyMtxIFOUgt\&q=85\&s=5cacb3be0dffd1cbd417381f3721637e)

~~36Run `/feedback` with no argument to open your queue of drafts from every session:~~

~~38```text Claude Code theme={null}~~

~~39> /feedback~~

~~40```~~

~~42Select a draft, then edit, send, or discard it. To turn drafting off, set **Claude-drafted feedback** to `off` in `/config`.~~

~~44[SendFeedback tool behavior](https://code.claude.com/docs/en/tools-reference.md#sendfeedback-tool-behavior)~~

~~46Restricted mode~~

~~47v2.1.248~~

49Restricted mode starts Claude Code without the built-in tools that run commands or code. Use it when an evaluation harness drives `claude` on a shared machine. Start it with `--restricted` or set `CLAUDE_CODE_RESTRICTED=1`. Claude Code also removes `WebFetch`, confines the file tools to the working directories, loads only managed settings and `--settings`, and refuses the `bypassPermissions` permission mode.

~~51Run a non-interactive query without the command-running tools:~~

~~53```bash terminal theme={null}~~

~~54claude --restricted -p "review src/ for SQL injection risks"~~

~~55```~~

57To give Claude one of the removed tools back, list it in `--tools` together with the other built-in tools you want, for example `--tools "Bash,Read,Edit"`. `--tools` is an allowlist, and its `default` preset doesn't restore the removed tools.

~~59[CLI flags](https://code.claude.com/docs/en/cli-reference.md#cli-flags)~~

~~61Other wins~~

63Set the new [`modelPicker`](https://code.claude.com/docs/en/settings-reference#modelpicker) setting to extend or replace the `/model` picker's built-in list with your own ordered, labeled entries, including Amazon Bedrock or Google Cloud's Agent Platform model IDsSet [`promptCacheTtl`](https://code.claude.com/docs/en/prompt-caching#choose-the-ttl-yourself) to `1h` to keep a one-hour prompt cache on the main conversation when you use an API key or a cloud provider; `subagentPromptCacheTtl` sets the TTL for subagents and all other requests outside the main conversationOn Pro, Max, Team, and Enterprise plans, [`/usage`](https://code.claude.com/docs/en/costs#plan-usage-breakdown) adds a Loops breakdown: run count, total tokens, tokens per run, and last run for the `/loop` and scheduled tasks that used the most tokensOrganizations on contracted rates can set the [`modelPricing`](https://code.claude.com/docs/en/costs#report-spend-at-your-contracted-rates) managed setting so `/usage`, the status line, and OpenTelemetry report cost at those rates instead of list price`/login` offers **Sign in with your Console account** under the **Anthropic Console account** option, so members of Console organizations that don't allow API keys can sign in without creating oneRun `/permissions` and open the new [**Auto mode** tab](https://code.claude.com/docs/en/auto-mode-config.md#edit-rules-from-permissions) to view and edit auto mode classifier rules without opening a settings fileWhen auto mode is available, Bash permission prompts in the Manual and `acceptEdits` permission modes offer a [**Yes, and switch to auto mode**](https://code.claude.com/docs/en/permission-modes.md#switch-permission-modes) option; select it to approve the command and switch the session to auto modeAfter you [move a session with `/cd`](https://code.claude.com/docs/en/permissions#move-the-session-to-another-directory), the new directory's project settings, hooks, `.mcp.json` servers, skills, and subagents take effect immediately instead of on the next `--resume`In non-interactive sessions, including `-p` runs, Agent SDK runs, and cloud sessions, Claude Code [continues a response](https://code.claude.com/docs/en/errors.md#the-response-above-may-be-incomplete) that a server error, dropped connection, or stall cut off mid-stream, when the partial response contains text and no tool callsA subagent that stops at its `maxTurns` limit returns its output marked as partial, with a hint that Claude can [continue it with `SendMessage`](https://code.claude.com/docs/en/sub-agents#resume-subagents), instead of appearing finishedOn Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry, sessions on the same machine can now [message each other](https://code.claude.com/docs/en/cross-session-messaging.md#availability), `/loop` can [choose its own interval](https://code.claude.com/docs/en/scheduled-tasks.md#let-claude-choose-the-interval), and `/model` and `/effort` apply immediately instead of after the turn endsThe native installer and auto-updater download a zstd-compressed build, about 75 MB instead of 340 MB on Linux x64, and native builds load code on demand, using roughly 40 to 70 MB less memory per session

~~65[Full changelog for v2.1.240–v2.1.250 →](https://code.claude.com/docs/en/changelog.md#2-1-240)~~

whats-new/2026-w36.md +0 −72 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 36 · August 31 – September 4, 2026~~

~~7> Switch to Claude Fable 5.1, let computer use run in the background on Desktop, and watch Claude's edits in a live /diff panel.~~

~~9Releases [v2.1.251 → v2.1.261](https://code.claude.com/docs/en/changelog.md#2-1-251)~~

~~104 features · August 31 – September 4~~

~~12Claude Fable 5.1~~

~~13new model~~

15Claude Fable 5.1 is available in Claude Code with a 1M-token context window, and the `fable` alias now selects it. In Claude apps gateway sessions, `fable` still selects Fable 5. If your gateway serves Fable 5.1, run `/model claude-fable-5-1`. Requires v2.1.257 or later.

~~17Switch the current session to Fable 5.1 and save it as your default:~~

~~19```text Claude Code theme={null}~~

~~20> /model fable~~

~~21```~~

~~23On the Anthropic API, the picker lists Fable only once the server reports it available for your organization, but typing `/model fable` checks with the server directly.~~

~~25[Work with Fable](https://code.claude.com/docs/en/model-config.md#work-with-fable)~~

~~27Computer use runs in the background on Desktop~~

~~28Desktop~~

30On macOS, computer use in the Claude Code Desktop app now works in the background: Claude sees and acts in the apps you've approved while you keep working. Background computer use is in beta on Pro and Max plans.

32![A Claude Code Desktop session where Claude asks to use Xcode, with a Computer use permission card that reads Let Claude see and act in the apps you approve, in the background or with full control of your screen, next to an Enable button](https://mintcdn.com/claude-code/f9HTZGyMtxIFOUgt/images/whats-new/background-computer-use.jpg?fit=max\&auto=format\&n=f9HTZGyMtxIFOUgt\&q=85\&s=a599a6c6fa544cb8d1b426b93706caf4)

~~34[Let Claude use your computer](https://code.claude.com/docs/en/desktop.md#let-claude-use-your-computer)~~

~~36Live diff panel in fullscreen rendering~~

~~37v2.1.260~~

39In fullscreen rendering, `/diff` now opens a panel beside the conversation instead of a viewer you have to close. The panel lists the changed files with their added and removed line counts and refreshes each time Claude edits a file or runs a shell command. Select lines in the panel with the mouse to attach them to your next prompt.

41<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/f9HTZGyMtxIFOUgt/images/whats-new/diff-panel.mp4?fit=max&auto=format&n=f9HTZGyMtxIFOUgt&q=85&s=9d7553c19e7f227891cd95f1f59d796d" />

~~43With fullscreen rendering on, inside a git repository, and in a terminal at least 110 columns wide, toggle the panel:~~

~~45```text Claude Code theme={null}~~

~~46> /diff~~

~~47```~~

~~49Run `/diff` again or click the `✕` in its header to close it.~~

~~51[Diff panel](https://code.claude.com/docs/en/interactive-mode.md#diff-panel)~~

~~53Find unused skills with /skill-doctor~~

~~54CLI~~

56`/skill-doctor` shows what each of your skills costs in context and how often it gets used, so you can decide which ones to turn off. Every skill in the [skill listing](https://code.claude.com/docs/en/skills.md#skill-descriptions-are-cut-short) adds to your context on every turn, whether or not Claude ever uses it. Requires v2.1.252 or later and isn't available in sessions that skip [feature-flag fetching](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching).

~~58Run it in an interactive session to open the report in the `/plugin` manager's **Stats** tab:~~

~~60```text Claude Code theme={null}~~

~~61> /skill-doctor~~

~~62```~~

~~64In non-interactive mode with `-p`, Claude Code prints the report as text instead.~~

~~66[Find unused skills](https://code.claude.com/docs/en/skills.md#find-unused-skills)~~

~~68Other wins~~

70A [`PreModelSwitch`](https://code.claude.com/docs/en/hooks#premodelswitch) hook can block a model switch you request, and a [`PostModelSwitch`](https://code.claude.com/docs/en/hooks#postmodelswitch) hook can add context for Claude after the session's model changes[`/cost`](https://code.claude.com/docs/en/costs#prompt-cache-statistics) adds a `Prompt cache (main)` line: the share of input tokens served from cache, the cache misses, whether the cache is warm, and a likely cause for the last miss when Claude Code can name one. Status line scripts get a matching `prompt_cache` objectOrganizations can list HTTP and SSE MCP servers under the [`managedMcpServers`](https://code.claude.com/docs/en/managed-mcp#provide-servers-through-managed-settings) managed setting to give them to every user, in addition to the servers that users add on their own`/effort` and the `/model` picker now [save a separate effort level for each model](https://code.claude.com/docs/en/model-config.md#adjust-effort-level); press `s` instead of `Enter` to apply a level to the current session onlyBy default, the auto mode classifier [now also blocks](https://code.claude.com/docs/en/permission-modes.md#what-the-classifier-blocks-by-default) actions such as requesting credentials from the cloud instance-metadata endpoint or connecting to sibling containers that Claude didn't startIn auto mode, Claude Code asks you before Claude [first reads a file outside your working directories](https://code.claude.com/docs/en/permission-modes.md#first-read-outside-the-working-directories), with an option to block such reads from then onRaise [`bashOutputMaxChars`](https://code.claude.com/docs/en/settings-reference#bashoutputmaxchars) and [`taskOutputMaxChars`](https://code.claude.com/docs/en/settings-reference#taskoutputmaxchars), up to 128,000 characters, so Claude receives more of the output from a successful command or background task inlineThe prompt's [word-editing shortcuts follow readline](https://code.claude.com/docs/en/interactive-mode.md#make-ctrl-w-delete-back-to-whitespace) for everyone, and the `keybindingFlavor` setting no longer has any effect. `Ctrl+W` deletes back to the previous whitespace, and `Alt+B`, `Alt+F`, and `Alt+D` treat punctuation such as `/` and `.` as word breaksIf you set `defaultMode` to `"bypassPermissions"` in a project's `.claude/settings.json` or `.claude/settings.local.json`, it [no longer takes effect](https://code.claude.com/docs/en/permission-modes.md#which-mode-a-session-starts-in) and the session starts in Manual mode; set `"bypassPermissions"` in user or managed settings instead, or pass `--permission-mode`Seat-based Enterprise plans now [default to Opus 5](https://code.claude.com/docs/en/model-config.md#default-model-setting)In the VS Code extension, click the model name at the bottom of the prompt box to [open the model picker](https://code.claude.com/docs/en/vs-code.md#use-the-prompt-box)In the VS Code extension, select **Output styles** in the command menu's Customize section to [pick an output style](https://code.claude.com/docs/en/vs-code.md#use-the-prompt-box), including your custom ones

~~72[Full changelog for v2.1.251–v2.1.261 →](https://code.claude.com/docs/en/changelog.md#2-1-251)~~

whats-new/2026-w37.md +0 −42 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# Week 37 · September 7–11, 2026~~

~~7> Test your plugins with claude plugin eval and pop Claude Code Desktop panes out into their own windows.~~

~~9Releases [v2.1.263 → v2.1.269](https://code.claude.com/docs/en/changelog.md#2-1-263)~~

~~102 features · September 7–11~~

~~12Test plugins with claude plugin eval~~

~~13v2.1.269~~

15`claude plugin eval` runs your plugin against a suite of test cases, scores the results, and by default runs each case again without the plugin so you can see what it contributes. `claude plugin eval init` asks you what a good result looks like, then proposes test cases and the checks that score them, tries the suite once, and writes the files. Every run, and every check that has a second model judge the reply, is a real model call on your account.

17![Terminal output of claude plugin eval: a table of seven cases with each case's score with and without the plugin, the delta between them, the run count, and the cost, followed by a summary line with the mean delta, total duration, and total cost](https://mintcdn.com/claude-code/f9HTZGyMtxIFOUgt/images/whats-new/plugin-eval.jpg?fit=max\&auto=format\&n=f9HTZGyMtxIFOUgt\&q=85\&s=913066f6d4a2a15426e98a627802f47f)

~~19From your plugin's root directory, have Claude draft the suite:~~

~~21```bash terminal theme={null}~~

~~22claude plugin eval init~~

~~23```~~

25When Claude tells you the suite is ready, exit the session that `claude plugin eval init` opened and run `claude plugin eval .` to score every case. The summary table prints in your terminal, and `report.html` under `evals/results/` has the per-run detail.

~~27[Test plugins with evals](https://code.claude.com/docs/en/plugin-evals.md)~~

~~29Pop Desktop panes out into their own windows~~

~~30Desktop~~

32In the Claude Code Desktop app, you can pop any pane out into its own window. Drag the diff or terminal to a second screen while Claude keeps working in the main window, then dock the pane back when you're done.

34<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/f9HTZGyMtxIFOUgt/images/whats-new/desktop-pop-out-panes.mp4?fit=max&auto=format&n=f9HTZGyMtxIFOUgt&q=85&s=ff3770dd09bb15ed9cf17a460f3d1e23" />

~~36[Arrange your workspace](https://code.claude.com/docs/en/desktop.md#arrange-your-workspace)~~

~~38Other wins~~

40Set [`maxEffortLevel`](https://code.claude.com/docs/en/settings-reference#maxeffortlevel) at the top level or per model under `modelSettings` to cap the effort level on every provider, including Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry; any higher level runs at the capPoint `--plugin-dir` at a folder of plugins to [load each immediate subfolder that has a manifest](https://code.claude.com/docs/en/plugins/create.md#load-a-directory-or-archive-for-one-session)If WebFetch hasn't finished downloading a page within five minutes, [the fetch fails with a deadline error](https://code.claude.com/docs/en/tools-reference.md#webfetch-tool-behavior) instead of hanging; set `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` to change the deadline, or to `0` to remove the limitPass `--json` to `claude plugin install`, `uninstall`, `update`, `enable`, or `disable` to print the result as [one JSON object on the last line of stdout](https://code.claude.com/docs/en/plugins/cli-reference.md#plugin-json-result)When the auto mode classifier blocks an action, the reason Claude receives [usually names the rule that matched](https://code.claude.com/docs/en/auto-mode-config.md#fix-a-denial-with-an-allow-rule-an-environment-entry-or-a-retry), such as `[Data Exfiltration]`When you type `/` partway through a prompt, you can now pick from [a list of matching commands](https://code.claude.com/docs/en/interactive-mode.md#complete-a-command-mid-prompt) instead of a single suggestion. The list opens as you type in fullscreen rendering. A plugin skill also matches on its name without the plugin prefixIn the VS Code extension, click the agent count at the bottom of the prompt box to open the [agent map](https://code.claude.com/docs/en/vs-code.md#use-the-prompt-box), where you can open a subagent's read-only transcript or stop itIn the VS Code extension, select **Hooks** or **Permissions** in the command menu's Customize section to [add or remove hooks and permission rules](https://code.claude.com/docs/en/vs-code.md#use-the-prompt-box) in your user, project, and local settingsClaude can pick a [browser-tab icon](https://code.claude.com/docs/en/artifacts.md#create-an-artifact) to match each artifact it publishesIn Claude Code on the web, take back a queued message in a cloud session before Claude reads it: remove it from the queue, or press `Esc` or `Up`, and the text returns to the message box

~~42[Full changelog for v2.1.263–v2.1.269 →](https://code.claude.com/docs/en/changelog.md#2-1-263)~~

workflows.md +10 −4

Details

375 375

376 Before v2.1.305, completed agents could also run again when you relaunched an unedited script whose `pipeline()` items or `parallel()` tasks ran more than one agent each. To stop those reruns for new runs, update Claude Code.376 Before v2.1.305, completed agents could also run again when you relaunched an unedited script whose `pipeline()` items or `parallel()` tasks ran more than one agent each. To stop those reruns for new runs, update Claude Code.

377* **Still running when you stopped**: starts over. Stopping the whole run doesn't count any agent as failed.377* **Still running when you stopped**: starts over. Stopping the whole run doesn't count any agent as failed.

378* **[Failed at a usage limit](#when-a-run-hits-your-usage-limit) on v2.1.318 or later**: runs again, and agents that completed return their saved results. If your script called another agent after the failure and that agent returned a result, every agent the script starts after the failed one also runs again.

378* **Failed**: runs again, and so does every agent the script starts after it, even ones that completed. Stopping one agent alone, by selecting it in [`/workflows`](#watch-the-run) and pressing `x`, counts as failing.379* **Failed**: runs again, and so does every agent the script starts after it, even ones that completed. Stopping one agent alone, by selecting it in [`/workflows`](#watch-the-run) and pressing `x`, counts as failing.

379 380

380That last case means a failure in the middle of a fan-out reruns work that already finished. If a script starts A, B, C, and D in that order and B fails, relaunching returns A from cache and runs B, C, and D again.381That last case means a **Failed** agent in the middle of a fan-out reruns work that already finished. If a script starts A, B, C, and D in that order and B is **Failed**, relaunching returns A from cache and runs B, C, and D again.

381 382

382If you edit a script that started A, B, C, and D so that it starts A, C, B, and D, the second agent to start is now C, where the previous run started B. Relaunching returns A from cache and runs C, B, and D again.383If you edit a script that started A, B, C, and D so that it starts A, C, B, and D, the second agent to start is now C, where the previous run started B. Relaunching returns A from cache and runs C, B, and D again.

383 384

395 396

396### When a run hits your usage limit397### When a run hits your usage limit

397 398

398When an agent hits your claude.ai [usage limit](https://code.claude.com/docs/en/interactive-mode.md#wait-for-a-usage-limit-to-reset), the run pauses rather than failing that agent: the agents that hit the limit wait for the reset, and no new agents start. Shortly after the limit resets, the waiting agents run again and the run continues on its own. Requires Claude Code v2.1.271 or later; on earlier versions, the affected agents fail.399When an agent hits your claude.ai [usage limit](https://code.claude.com/docs/en/interactive-mode.md#wait-for-a-usage-limit-to-reset), the run pauses rather than failing that agent. The agents that hit the limit wait for the reset, and no new agents start. Shortly after the limit resets, the waiting agents run again and the run continues on its own. Requires Claude Code v2.1.271 or later, or [v2.1.319 or later](https://code.claude.com/docs/en/desktop.md#claude-code-version-in-the-code-tab) in the Desktop [Code tab](https://code.claude.com/docs/en/desktop.md). On earlier versions, the affected agents fail.

399 400

400While the run waits, its progress line in the task panel and the [`/workflows`](#watch-the-run) header show when the limit resets.401While the run waits, its progress line in the task panel and the [`/workflows`](#watch-the-run) header show when the limit resets. In the Code tab, the run shows a line such as `Paused at usage limit · continues after 3:45 PM if the app stays open`. Keep the app open.

401 402

402The run pauses only when all of these hold; when one doesn't, the affected agent fails instead:403The run pauses only when all of these hold; when one doesn't, the affected agent fails instead:

403 404

404* The session is interactive and signed in with a claude.ai subscription. A run doesn't pause in [non-interactive mode](https://code.claude.com/docs/en/headless.md) with `claude -p` or the [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md), in a [background session](https://code.claude.com/docs/en/agent-view.md), or in a [Remote Control](https://code.claude.com/docs/en/remote-control.md) or [agent team](https://code.claude.com/docs/en/agent-teams.md) teammate session.405* The session is signed in with a claude.ai subscription without [usage-based billing](https://code.claude.com/docs/en/interactive-mode.md#start-a-wait-yourself), and is one of these session types:

406 * An interactive terminal session. A run doesn't pause in [non-interactive mode](https://code.claude.com/docs/en/headless.md) with `claude -p` or the [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md), in a [background session](https://code.claude.com/docs/en/agent-view.md), or in a [Remote Control](https://code.claude.com/docs/en/remote-control.md) or [agent team](https://code.claude.com/docs/en/agent-teams.md) teammate session.

407 * A local session you started in the Code tab. A run doesn't pause in an SSH, WSL, [Dispatch](https://code.claude.com/docs/en/desktop.md#sessions-from-dispatch), or [scheduled task](https://code.claude.com/docs/en/desktop-scheduled-tasks.md) session, in one started from Remote Control or through a [corporate launcher](https://code.claude.com/docs/en/corporate-launcher.md), or while [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/en/env-vars#variables) is set.

405* [`autoContinueAtUsageLimit`](https://code.claude.com/docs/en/settings-reference#autocontinueatusagelimit) is on, the same setting that lets the session itself [wait for a usage limit to reset](https://code.claude.com/docs/en/interactive-mode.md#wait-for-a-usage-limit-to-reset). If you turn it off during a wait, the wait ends and the waiting agents fail.408* [`autoContinueAtUsageLimit`](https://code.claude.com/docs/en/settings-reference#autocontinueatusagelimit) is on, the same setting that lets the session itself [wait for a usage limit to reset](https://code.claude.com/docs/en/interactive-mode.md#wait-for-a-usage-limit-to-reset). If you turn it off during a wait, the wait ends and the waiting agents fail.

409* In the Code tab, the **Auto-continue when limits reset** checkbox on a [session-limit card](https://code.claude.com/docs/en/errors.md#youve-hit-your-session-limit) is checked, as it is by default. If you uncheck it, runs in your Code tab sessions stop pausing, unless managed settings set `autoContinueAtUsageLimit` to `true`.

406* The limit resets within 24 hours. A weekly limit can reset further out.410* The limit resets within 24 hours. A weekly limit can reset further out.

407* The run hasn't already waited twice. When it hits the limit a third time, the agent fails.411* The run hasn't already waited twice. When it hits the limit a third time, the agent fails.

408 412

413To finish a run whose agents failed at the limit, ask Claude to [relaunch the workflow](#which-agents-run-again) after the limit resets.

414

409### When an agent stalls and restarts415### When an agent stalls and restarts

410 416

411An agent whose output stops arriving for long enough starts over from the same prompt. In [`/workflows`](#watch-the-run), its name gains a `(retry 1)` suffix and its detail shows `attempt 2 (stalled)`. The restart is automatic, so you don't need to do anything.417An agent whose output stops arriving for long enough starts over from the same prompt. In [`/workflows`](#watch-the-run), its name gains a `(retry 1)` suffix and its detail shows `attempt 2 (stalled)`. The restart is automatic, so you don't need to do anything.

worktrees.md +1 −1

Details

253 253

254A worktree gets its own files and branch, but it shares the following with the main checkout:254A worktree gets its own files and branch, but it shares the following with the main checkout:

255 255

256* **The repository's `.git` directory**: git commands in a worktree write to the main repository's shared `.git` directory, and [sandboxing](https://code.claude.com/docs/en/sandboxing.md#filesystem-isolation) allows those writes, so commands such as `git commit` work from inside a worktree with the sandbox enabled.256* **The repository's `.git` directory**: git commands in a worktree write to the main repository's shared `.git` directory. With the [sandbox](https://code.claude.com/docs/en/sandboxing.md#filesystem-isolation) enabled, commands such as `git commit` work in a session at the worktree's root, which is where `--worktree` starts one. By default, they [fail with an `index.lock` error if you run `claude` in a subdirectory of the worktree](https://code.claude.com/docs/en/sandboxing#git-index-lock).

257* **Plugins**: plugins installed at [project scope](https://code.claude.com/docs/en/plugins/loading.md#find-where-a-plugin-is-enabled) from the main checkout also load in worktrees of the same repository, so you don't need to reinstall them per worktree.257* **Plugins**: plugins installed at [project scope](https://code.claude.com/docs/en/plugins/loading.md#find-where-a-plugin-is-enabled) from the main checkout also load in worktrees of the same repository, so you don't need to reinstall them per worktree.

258* **Permission approvals**: choosing "Yes, and don't ask again" for a Bash command in a worktree session saves the rule to the main checkout's `.claude/settings.local.json`. The rule applies in the main checkout and in every other worktree of the repository, and it survives the worktree's removal.258* **Permission approvals**: choosing "Yes, and don't ask again" for a Bash command in a worktree session saves the rule to the main checkout's `.claude/settings.local.json`. The rule applies in the main checkout and in every other worktree of the repository, and it survives the worktree's removal.

259 259

zero-data-retention.md +4 −2

Details

41 41

42### What ZDR does not cover42### What ZDR does not cover

43 43

44ZDR does not extend to the following, even for organizations with ZDR enabled. These features follow [standard data retention policies](https://code.claude.com/docs/en/data-usage.md#data-retention):44ZDR does not extend to the following, even for organizations with ZDR enabled. Except where a row says otherwise, these features follow [standard data retention policies](https://code.claude.com/docs/en/data-usage.md#data-retention):

45 45

46| Feature | Details |46| Feature | Details |

47| - | - |47| - | - |

48| Chat on claude.ai | Chat conversations through the Claude for Enterprise web interface are not covered by ZDR. |48| Chat on claude.ai | Chat conversations through the Claude for Enterprise web interface are not covered by ZDR. |

49| Cowork | Cowork sessions are not covered by ZDR. |49| Cowork | Cowork sessions are not covered by ZDR. |

50| Artifacts | Artifacts in chat conversations and Cowork sessions are not covered by ZDR, and are kept until deleted unless your organization sets a retention period for them. Artifacts are not available in Claude Code with ZDR. |

50| Claude Code Analytics | Does not store prompts or model responses, but collects productivity metadata such as account emails and usage statistics. Contribution metrics are not available for ZDR organizations; the [analytics dashboard](https://code.claude.com/docs/en/analytics.md) shows usage metrics only. |51| Claude Code Analytics | Does not store prompts or model responses, but collects productivity metadata such as account emails and usage statistics. Contribution metrics are not available for ZDR organizations; the [analytics dashboard](https://code.claude.com/docs/en/analytics.md) shows usage metrics only. |

51| User and seat management | Administrative data such as account emails and seat assignments is retained under standard policies. |52| User and seat management | Administrative data such as account emails and seat assignments is retained under standard policies. |

52| Third-party integrations | Data processed by third-party tools, MCP servers, or other external integrations is not covered by ZDR. Review those services' data handling practices independently. |53| Third-party integrations | Data processed by third-party tools, MCP servers, or other external integrations is not covered by ZDR. Review those services' data handling practices independently. |

60| [Cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md), including those started from the [Desktop app](https://code.claude.com/docs/en/desktop.md#cloud-sessions) | Requires server-side storage of session data, including conversation history with prompts and completions. |61| [Cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md), including those started from the [Desktop app](https://code.claude.com/docs/en/desktop.md#cloud-sessions) | Requires server-side storage of session data, including conversation history with prompts and completions. |

61| [Chat and Cowork unified](https://support.claude.com/en/articles/17444462-set-up-and-manage-the-new-unified-claude-experience-for-your-enterprise-organization) | Requires cloud sessions. |62| [Chat and Cowork unified](https://support.claude.com/en/articles/17444462-set-up-and-manage-the-new-unified-claude-experience-for-your-enterprise-organization) | Requires cloud sessions. |

62| [Claude Tag](https://claude.com/docs/claude-tag) | Retains channel memory and session transcripts. |63| [Claude Tag](https://claude.com/docs/claude-tag) | Retains channel memory and session transcripts. |

~~63| [Artifacts](https://code.claude.com/docs/en/artifacts.md) | Requires storing published page content on Anthropic-operated infrastructure. |~~64| [Artifacts](https://code.claude.com/docs/en/artifacts.md) in Claude Code | Requires storing published page content on Anthropic-operated infrastructure. |

65| [Claude Docs](https://support.claude.com/en/articles/16923645-get-started-with-claude-docs) | Requires storing document content on Anthropic-operated infrastructure. |

64| Feedback submission (`/feedback`, `/bug`, `/share`) | Submitting feedback sends conversation data to Anthropic. |66| Feedback submission (`/feedback`, `/bug`, `/share`) | Submitting feedback sends conversation data to Anthropic. |

65| [Remote Control](https://code.claude.com/docs/en/remote-control.md) | Stores the session transcript on Anthropic servers to sync the conversation across devices. |67| [Remote Control](https://code.claude.com/docs/en/remote-control.md) | Stores the session transcript on Anthropic servers to sync the conversation across devices. |

66 68

Documentation 2026-11-09 23:02 UTC to 2026-11-10 21:57 UTC