Documentation — Spybara

admin-setup.md +130 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Set up Claude Code for your organization

7> A decision map for administrators deploying Claude Code, covering API providers, managed settings, policy enforcement, usage monitoring, and data handling.

9Claude Code enforces organization policy through managed settings that take precedence over local developer configuration. You deliver those settings from the Claude admin console, your mobile device management (MDM) system, or a file on disk. The settings control which tools, commands, servers, and network destinations Claude can reach.

11This page walks through the deployment decisions in order. Each row links to the section below and to the reference page for that area.

13<Note>

14 SSO, SCIM provisioning, and seat assignment are configured at the Claude account level. See the [Claude Enterprise Administrator Guide](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide) and [seat assignment](https://support.claude.com/en/articles/11845131-use-claude-code-with-your-team-or-enterprise-plan) for those steps.

15</Note>

17| Decision | What you're choosing | Reference |

18| :---------------------------------------------------------------------- | :-------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |

19| [Choose your API provider](#choose-your-api-provider) | Where Claude Code authenticates and how it's billed | [Authentication](/en/authentication), [Bedrock](/en/amazon-bedrock), [Vertex AI](/en/google-vertex-ai), [Foundry](/en/microsoft-foundry) |

20| [Decide how settings reach devices](#decide-how-settings-reach-devices) | How managed policy reaches developer machines | [Server-managed settings](/en/server-managed-settings), [Settings files](/en/settings#settings-files) |

21| [Decide what to enforce](#decide-what-to-enforce) | Which tools, commands, and integrations are allowed | [Permissions](/en/permissions), [Sandboxing](/en/sandboxing) |

22| [Set up usage visibility](#set-up-usage-visibility) | How you track spend and adoption | [Analytics](/en/analytics), [Monitoring](/en/monitoring-usage), [Costs](/en/costs) |

23| [Review data handling](#review-data-handling) | Data retention and compliance posture | [Data usage](/en/data-usage), [Security](/en/security) |

25## Choose your API provider

27Claude Code connects to Claude through one of several API providers. Your choice affects billing, authentication, and which compliance posture you inherit.

29| Provider | Choose this when |

30| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |

31| Claude for Teams / Enterprise | You want Claude Code and claude.ai under one per-seat subscription with no infrastructure to run. This is the default recommendation. |

32| Claude Console | You're API-first or want pay-as-you-go billing |

33| Amazon Bedrock | You want to inherit existing AWS compliance controls and billing |

34| Google Vertex AI | You want to inherit existing GCP compliance controls and billing |

35| Microsoft Foundry | You want to inherit existing Azure compliance controls and billing |

37For the full provider comparison covering authentication, regions, and feature parity, see the [enterprise deployment overview](/en/third-party-integrations). Each provider's auth setup is in [Authentication](/en/authentication).

39Proxy and firewall requirements in [Network configuration](/en/network-config) apply regardless of provider. If you want a single endpoint in front of multiple providers or centralized request logging, see [LLM gateway](/en/llm-gateway).

41## Decide how settings reach devices

43Managed settings define policy that takes precedence over local developer configuration. Claude Code looks for them in four places and uses the first one it finds on a given device.

46| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :------------- |

47| Server-managed | Claude.ai admin console | Highest | All |

49| File-based managed | macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`<br />Linux and WSL: `/etc/claude-code/managed-settings.json`<br />Windows: `C:\Program Files\ClaudeCode\managed-settings.json` | Medium | All |

52Server-managed settings reach devices at authentication time and refresh hourly during active sessions, with no endpoint infrastructure. They require a Claude for Teams or Enterprise plan, so deployments on other providers need one of the file-based or OS-level mechanisms instead.

54If your organization mixes providers, configure [server-managed settings](/en/server-managed-settings) for Claude.ai users plus a [file-based or plist/registry fallback](/en/settings#settings-files) so other users still receive managed policy.

56The plist and HKLM registry locations work with any provider and resist tampering because they require admin privileges to write. The Windows user registry at HKCU is writable without elevation, so treat it as a convenience default rather than an enforcement channel.

58Whichever mechanism you choose, managed values take precedence over user and project settings. Array settings such as `permissions.allow` and `permissions.deny` merge entries from all sources, so developers can extend managed lists but not remove from them.

60See [Server-managed settings](/en/server-managed-settings) and [Settings files and precedence](/en/settings#settings-files).

62## Decide what to enforce

64Managed settings can lock down tools, sandbox execution, restrict MCP servers and plugin sources, and control which hooks run. Each row is a control surface with the setting keys that drive it.

66| Control | What it does | Key settings |

67| :------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------- | :---------------------------------------------------------------------------- |

68| [Permission rules](/en/permissions) | Allow, ask, or deny specific tools and commands | `permissions.allow`, `permissions.deny` |

69| [Permission lockdown](/en/permissions#managed-only-settings) | Only managed permission rules apply; disable `--dangerously-skip-permissions` | `allowManagedPermissionRulesOnly`, `permissions.disableBypassPermissionsMode` |

70| [Sandboxing](/en/sandboxing) | OS-level filesystem and network isolation with domain allowlists | `sandbox.enabled`, `sandbox.network.allowedDomains` |

71| [Managed policy CLAUDE.md](/en/memory#deploy-organization-wide-claude-md) | Org-wide instructions loaded in every session, cannot be excluded | File at the managed policy path |

72| [MCP server control](/en/mcp#managed-mcp-configuration) | Restrict which MCP servers users can add or connect to | `allowedMcpServers`, `deniedMcpServers`, `allowManagedMcpServersOnly` |

73| [Plugin marketplace control](/en/plugin-marketplaces#managed-marketplace-restrictions) | Restrict which marketplace sources users can add | `strictKnownMarketplaces`, `blockedMarketplaces` |

74| [Hook restrictions](/en/settings#hook-configuration) | Only managed hooks load; restrict HTTP hook URLs | `allowManagedHooksOnly`, `allowedHttpHookUrls` |

75| [Version floor](/en/settings) | Prevent auto-update from installing below an org-wide minimum | `minimumVersion` |

77Permission rules and sandboxing cover different layers. Denying WebFetch blocks Claude's fetch tool, but if Bash is allowed, `curl` and `wget` can still reach any URL. Sandboxing closes that gap with a network domain allowlist enforced at the OS level.

79For the threat model these controls defend against, see [Security](/en/security).

81## Set up usage visibility

83Choose monitoring based on what you need to report on.

86| :------------------ | :--------------------------------------------------- | :------------- | :--------------------------------------- |

91Cloud providers expose spend through AWS Cost Explorer, GCP Billing, or Azure Cost Management. Claude for Teams and Enterprise plans include a usage dashboard at [claude.ai/analytics/claude-code](https://claude.ai/analytics/claude-code).

93## Review data handling

95On Team, Enterprise, Claude API, and cloud provider plans, Anthropic does not train models on your code or prompts. Your API provider determines retention and compliance posture.

97| Topic | What to know | Where to start |

98| :------------------------ | :------------------------------------------------------------------------------ | :--------------------------------------------- |

99| Data usage policy | What Anthropic collects, how long it's retained, what's never used for training | [Data usage](/en/data-usage) |

100| Zero Data Retention (ZDR) | Nothing stored after the request completes. Available on Claude for Enterprise | [Zero data retention](/en/zero-data-retention) |

101| Security architecture | Network model, encryption, authentication, audit trail | [Security](/en/security) |

102

103If you need request-level audit logging or to route traffic by data sensitivity, place an [LLM gateway](/en/llm-gateway) between developers and your provider. For regulatory requirements and certifications, see [Legal and compliance](/en/legal-and-compliance).

104

105## Verify and onboard

106

107After configuring managed settings, have a developer run `/status` inside Claude Code. The output includes a line beginning with `Enterprise managed settings` followed by the source in parentheses, one of `(remote)`, `(plist)`, `(HKLM)`, `(HKCU)`, or `(file)`. See [Verify active settings](/en/settings#verify-active-settings).

108

109Share these resources to help developers get started:

110

111* [Quickstart](/en/quickstart): first-session walkthrough from install to working with a project

112* [Common workflows](/en/common-workflows): patterns for everyday tasks like code review, refactoring, and debugging

113* [Claude 101](https://anthropic.skilljar.com/claude-101) and [Claude Code in Action](https://anthropic.skilljar.com/claude-code-in-action): self-paced Anthropic Academy courses

114

115For login issues, point developers to [authentication troubleshooting](/en/troubleshooting#authentication-issues). The most common fixes are:

116

117* Run `/logout` then `/login` to switch accounts

118* Run `claude update` if the enterprise auth option is missing

119* Restart the terminal after updating

120

121If a developer sees "You haven't been added to your organization yet," their seat doesn't include Claude Code access and needs to be updated in the admin console.

122

123## Next steps

124

125With provider and delivery mechanism chosen, move on to detailed configuration:

126

127* [Server-managed settings](/en/server-managed-settings): deliver managed policy from the Claude admin console

128* [Settings reference](/en/settings): every setting key, file location, and precedence rule

129* [Amazon Bedrock](/en/amazon-bedrock), [Google Vertex AI](/en/google-vertex-ai), [Microsoft Foundry](/en/microsoft-foundry): provider-specific deployment

130* [Claude Enterprise Administrator Guide](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide): SSO, SCIM, seat management, and rollout playbook

agent-sdk/observability.md +14 −3

Details

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

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

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

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

148

149The `llm_request`, `tool`, and `hook` spans are children of the enclosing `claude_code.interaction` span. When the agent spawns a subagent through the Task tool, the subagent's `llm_request` and `tool` spans nest under the parent agent's `claude_code.tool` span, so the full delegation chain appears as one trace.

148 150

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

150 152

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

155</Note>157</Note>

156 158

159## Link traces to your application

160

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

162

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

164

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

166

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

158 168

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

186 196

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

188 198

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

190 200

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

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

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

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

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

196 207

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

198 209

agent-sdk/python.md +24 −6

Details

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

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

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

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

792 enable_file_checkpointing: bool = False792 enable_file_checkpointing: bool = False

793 session_store: SessionStore | None = None

793```794```

794 795

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

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

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

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

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

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

834 836

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

836 838

1003 description: str1005 description: str

1004 prompt: str1006 prompt: str

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

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

1009 model: str | None = None

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

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

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

1013 initialPrompt: str | None = None

1014 maxTurns: int | None = None

1015 background: bool | None = None

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

1017 permissionMode: PermissionMode | None = None

1010```1018```

1011 1019

1013| :------------ | :------- | :-------------------------------------------------------------------------------------------------- |1021| :---------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

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

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

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

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

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

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

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

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

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

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

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

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

1035

1036<Note>

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

1038</Note>

1021 1039

1022### `PermissionMode`1040### `PermissionMode`

1023 1041

agent-sdk/session-storage.md +259 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Persist sessions to external storage

7> Mirror session transcripts to S3, Redis, or your own backend so any host can resume them.

9By default, the SDK writes session transcripts to JSONL files under `~/.claude/projects/` on the local filesystem. A `SessionStore` adapter lets you mirror those transcripts to your own backend, such as S3, Redis, or a database, so a session created on one host can be resumed on another.

11Common reasons to use a session store:

13* **Multi-host deployments.** Serverless functions, autoscaled workers, and CI runners don't share a filesystem. A shared store lets any replica resume any session.

14* **Durability.** Local containers are ephemeral. A store backed by S3 or a database survives restarts and redeploys.

15* **Compliance and audit.** Keep transcripts in storage you already govern, with your own retention rules, encryption, and access controls.

17## The `SessionStore` interface

19A `SessionStore` is an object with two required methods, `append` and `load`, and three optional methods. The SDK calls `append` to write transcript entries during a query and `load` to read them back for resume.

21<CodeGroup>

22 ```typescript TypeScript theme={null}

23 // Exported from @anthropic-ai/claude-agent-sdk as

24 // SessionStore, SessionKey, SessionStoreEntry.

26 type SessionKey = {

27 projectKey: string;

28 sessionId: string;

29 subpath?: string;

30 };

32 type SessionStore = {

33 // Required

34 append(key: SessionKey, entries: SessionStoreEntry[]): Promise<void>;

35 load(key: SessionKey): Promise<SessionStoreEntry[] | null>;

37 // Optional

38 listSessions?(

39 projectKey: string,

40 ): Promise<Array<{ sessionId: string; mtime: number }>>;

41 delete?(key: SessionKey): Promise<void>;

42 listSubkeys?(key: {

43 projectKey: string;

44 sessionId: string;

45 }): Promise<string[]>;

46 };

47 ```

49 ```python Python theme={null}

50 # Exported from claude_agent_sdk as

51 # SessionStore, SessionKey, SessionStoreEntry.

53 class SessionKey(TypedDict):

54 project_key: str

55 session_id: str

56 subpath: NotRequired[str]

58 class SessionStore(Protocol):

59 # Required

60 async def append(

61 self, key: SessionKey, entries: list[SessionStoreEntry]

62 ) -> None: ...

63 async def load(self, key: SessionKey) -> list[SessionStoreEntry] | None: ...

65 # Optional — omit or raise NotImplementedError

66 async def list_sessions(

67 self, project_key: str

68 ) -> list[SessionStoreListEntry]: ...

69 async def delete(self, key: SessionKey) -> None: ...

70 async def list_subkeys(self, key: SessionListSubkeysKey) -> list[str]: ...

71 ```

72</CodeGroup>

74`SessionKey` addresses one transcript. `projectKey` is a stable, filesystem-safe encoding of the working directory, `sessionId` is the session UUID, and `subpath` is set when the entry belongs to a subagent transcript or sidecar file rather than the main conversation. Treat `subpath` as an opaque key suffix; it follows the on-disk layout, for example `subagents/agent-<id>`. When `subpath` is undefined the key refers to the main transcript.

76| Method | Required | Called when |

77| :------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

78| `append` | Yes | After each batch of transcript entries is written locally. Entries are JSON-safe objects, one per line in the local JSONL. |

79| `load` | Yes | Once before the subprocess spawns, when `resume` is set. Return `null` if the session is unknown. |

80| `listSessions` | No | By `listSessions({ sessionStore })` and by `query()`/`startup()` with `continue: true`. If undefined, those calls throw. |

81| `delete` | No | By `deleteSession({ sessionStore })`. Deleting the main key (no `subpath`) must cascade to all subkeys for that session. If undefined, deletion is a no-op, which suits append-only backends. |

82| `listSubkeys` | No | During resume, to discover subagent transcripts. If undefined, only the main transcript is restored. |

84## Quick start

86The SDK ships an `InMemorySessionStore` for development and testing. The example below runs a query with the store attached, captures the session ID from the result message, then resumes from the store in a second `query()` call. The second call passes the same store instance plus `resume`, so the SDK loads the transcript from the store instead of the local filesystem:

88<CodeGroup>

89 ```typescript TypeScript theme={null}

90 import { query, InMemorySessionStore } from "@anthropic-ai/claude-agent-sdk";

92 const store = new InMemorySessionStore();

94 let sessionId: string | undefined;

95 for await (const message of query({

96 prompt: "List the TypeScript files under src/",

97 options: { sessionStore: store },

98 })) {

99 if (message.type === "result") {

100 sessionId = message.session_id;

101 }

102 }

103

104 // Resume from the store. The agent has full context from the first call.

105 for await (const message of query({

106 prompt: "Summarize what those files do",

107 options: { sessionStore: store, resume: sessionId },

108 })) {

109 if (message.type === "result" && message.subtype === "success") {

110 console.log(message.result);

111 }

112 }

113 ```

114

115 ```python Python theme={null}

116 import asyncio

117 from claude_agent_sdk import (

118 ClaudeAgentOptions,

119 InMemorySessionStore,

120 ResultMessage,

121 query,

122 )

123

124 store = InMemorySessionStore()

125

126

127 async def main():

128 session_id = None

129 async for message in query(

130 prompt="List the Python files under src/",

131 options=ClaudeAgentOptions(session_store=store),

132 ):

133 if isinstance(message, ResultMessage):

134 session_id = message.session_id

135

136 # Resume from the store. The agent has full context from the first call.

137 async for message in query(

138 prompt="Summarize what those files do",

139 options=ClaudeAgentOptions(session_store=store, resume=session_id),

140 ):

141 if isinstance(message, ResultMessage) and message.subtype == "success":

142 print(message.result)

143

144

145 asyncio.run(main())

146 ```

147</CodeGroup>

148

149## Write your own adapter

150

151Implement `append` and `load` against your backend. Add `listSessions`, `delete`, and `listSubkeys` if you want `listSessions()`, `deleteSession()`, and subagent resume to work against the store.

152

153Entries passed to `append` are typed as `SessionStoreEntry` (a `{ type: string; ... }` object). Treat them as opaque JSON-safe values: persist them in order and return them from `load` in the same order. `load` must return entries that are deep-equal to what was appended; byte-equal serialization is not required, so backends like Postgres `jsonb` that reorder object keys are fine.

154

155## Reference implementations

156

157The TypeScript SDK repository includes runnable reference adapters for S3, Redis, and Postgres under [`examples/session-stores/`](https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples/session-stores). They are not published to npm; copy the `src/` file you need into your project and install the corresponding backend client.

158

159| Adapter | Backend client | Storage model |

160| :----------------------------------------------------------------------------------------------------------------------------- | :------------------- | :--------------------------------------------------------------------------- |

161| [`S3SessionStore`](https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples/session-stores/s3) | `@aws-sdk/client-s3` | One JSONL part file per `append()`; `load()` lists, sorts, and concatenates. |

162| [`RedisSessionStore`](https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples/session-stores/redis) | `ioredis` | `RPUSH`/`LRANGE` list per transcript, plus a sorted-set session index. |

163| [`PostgresSessionStore`](https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples/session-stores/postgres) | `pg` | One row per entry in a `jsonb` table, ordered by `BIGSERIAL`. |

164

165Each adapter takes a pre-configured client instance, so you control credentials, TLS, region, and pooling. For example, with S3:

166

167```typescript TypeScript theme={null}

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

169import { S3Client } from "@aws-sdk/client-s3";

170import { S3SessionStore } from "./S3SessionStore"; // copied from examples/session-stores/s3

171

172const store = new S3SessionStore({

173 bucket: "my-claude-sessions",

174 prefix: "transcripts",

175 client: new S3Client({ region: "us-east-1" }),

176});

177

178for await (const message of query({

179 prompt: "Hello!",

180 options: { sessionStore: store },

181})) {

182 if (message.type === "result" && message.subtype === "success") {

183 console.log(message.result);

184 }

185}

186

187// Later, possibly on a different host:

188for await (const message of query({

189 prompt: "Continue where we left off",

190 options: { sessionStore: store, resume: "previous-session-id" },

191})) {

192 // ...

193}

194```

195

196### Validate your adapter

197

198Both SDKs ship a conformance suite that asserts the behavioral contract `append`, `load`, and the optional methods must satisfy. Tests for optional methods skip automatically when those methods are not implemented.

199

200In TypeScript, copy [`shared/conformance.ts`](https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/examples/session-stores/shared/conformance.ts) from the example directory into your test suite. In Python, the suite ships in the package:

201

202```python Python theme={null}

203import pytest

204from claude_agent_sdk.testing import run_session_store_conformance

205

206

207@pytest.mark.asyncio

208async def test_my_store_conformance():

209 await run_session_store_conformance(MyRedisStore)

210```

211

212## Behavior notes

213

214### Dual-write architecture

215

216The store is a mirror, not a replacement. The Claude Code subprocess always writes to local disk first; the SDK then forwards each batch to `append()`. If you want the local copy to be ephemeral, point `CLAUDE_CONFIG_DIR` at a temp directory in `options.env`. Because the mirror depends on local writes, `sessionStore` cannot be combined with `persistSession: false`; the SDK throws if you set both. It also throws if combined with `enableFileCheckpointing`, since file-history backup blobs are written directly to local disk and are not mirrored to the store.

217

218### Mirror writes are best-effort

219

220If `append()` rejects or times out, the error is logged, a `{ type: "system", subtype: "mirror_error" }` message is emitted into the iterator, and the query continues. The local transcript is already durable on disk, so a store outage does not interrupt the agent or lose data locally. Batches that fail are not retried, so monitor for `mirror_error` if you need to detect store data loss.

221

222### `getSessionMessages` returns the post-compaction chain

223

224`getSessionMessages({ sessionStore })` returns the linked message chain the agent would see on resume. After auto-compaction, earlier turns are replaced by a summary, so a session whose store holds 503 raw entries may return 18 messages from `getSessionMessages`. For the full raw history, including pre-compaction turns and metadata entries, call `store.load(key)` directly.

225

226### `forkSession` is not a byte copy

227

228`forkSession({ sessionStore })` reads the source entries, rewrites every `sessionId` field and remaps message UUIDs, then appends the transformed entries under a new key. An adapter-level copy or `CopyObject` shortcut would produce a transcript that still references the old session ID, so the SDK does not use one.

229

230### Subagent transcripts

231

232Subagent transcripts are mirrored under `subpath: "subagents/agent-<id>"`. `listSubagents({ sessionStore })` requires the adapter to implement `listSubkeys`; `getSubagentMessages({ sessionStore })` uses it when available but falls back to the direct subpath when it is undefined. Resume also calls `listSubkeys` to restore subagent files; without it, only the main transcript is materialized.

233

234### Retention

235

236The SDK never deletes from your store on its own. Retention is the adapter's responsibility: implement TTLs, S3 lifecycle policies, or scheduled cleanup according to your compliance requirements. Local transcripts under `CLAUDE_CONFIG_DIR` are swept independently by the `cleanupPeriodDays` setting.

237

238## Supported on

239

240The following SDK functions accept a `sessionStore` option and operate against the store instead of the local filesystem when it is provided:

241

242* [`query()`](/en/agent-sdk/typescript#query)

243* [`startup()`](/en/agent-sdk/typescript#startup)

244* [`listSessions()`](/en/agent-sdk/typescript#list-sessions)

245* [`getSessionInfo()`](/en/agent-sdk/typescript#get-session-info)

246* [`getSessionMessages()`](/en/agent-sdk/typescript#get-session-messages)

247* [`renameSession()`](/en/agent-sdk/typescript#rename-session)

248* [`tagSession()`](/en/agent-sdk/typescript#tag-session)

249* [`deleteSession()`](/en/agent-sdk/typescript)

250* [`forkSession()`](/en/agent-sdk/typescript)

251* [`listSubagents()`](/en/agent-sdk/typescript)

252* [`getSubagentMessages()`](/en/agent-sdk/typescript)

253

254## Related resources

255

256* [Work with sessions](/en/agent-sdk/sessions): Continue, resume, and fork without a custom store

257* [Host the SDK](/en/agent-sdk/hosting): Deployment patterns for multi-host environments

258* [TypeScript `Options`](/en/agent-sdk/typescript#options): Full option reference

259* [`examples/session-stores/`](https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples/session-stores): Runnable S3, Redis, and Postgres reference adapters

agent-sdk/sessions.md +2 −0

Details

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

234</Tip>234</Tip>

235 235

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

237

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

237 239

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

agent-sdk/subagents.md +10 −3

Details

160### AgentDefinition configuration160### AgentDefinition configuration

161 161

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

176

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

171 178

172<Note>179<Note>

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

agent-sdk/typescript.md +37 −3

Details

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

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

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

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

467 prompt: string;468 prompt: string;

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

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

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

472 initialPrompt?: string;

471 maxTurns?: number;473 maxTurns?: number;

474 background?: boolean;

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

477 permissionMode?: PermissionMode;

472 criticalSystemReminder_EXPERIMENTAL?: string;478 criticalSystemReminder_EXPERIMENTAL?: string;

473};479};

474```480```

475 481

477| :------------------------------------ | :------- | :---------------------------------------------------------------------------- |483| :------------------------------------ | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

487 498

488### `AgentMcpServerSpec`499### `AgentMcpServerSpec`

800 | SDKTaskNotificationMessage811 | SDKTaskNotificationMessage

801 | SDKTaskStartedMessage812 | SDKTaskStartedMessage

802 | SDKTaskProgressMessage813 | SDKTaskProgressMessage

814 | SDKTaskUpdatedMessage

803 | SDKFilesPersistedEvent815 | SDKFilesPersistedEvent

804 | SDKToolUseSummaryMessage816 | SDKToolUseSummaryMessage

805 | SDKRateLimitEvent817 | SDKRateLimitEvent

2676};2688};

2677```2689```

2678 2690

2691### `SDKTaskUpdatedMessage`

2692

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

2694

2695```typescript theme={null}

2696type SDKTaskUpdatedMessage = {

2697 type: "system";

2698 subtype: "task_updated";

2699 task_id: string;

2700 patch: {

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

2702 description?: string;

2703 end_time?: number;

2704 total_paused_ms?: number;

2705 error?: string;

2706 is_backgrounded?: boolean;

2707 };

2708 uuid: UUID;

2709 session_id: string;

2710};

2711```

2712

2679### `SDKFilesPersistedEvent`2713### `SDKFilesPersistedEvent`

2680 2714

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

best-practices.md +1 −1

Details

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

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

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

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

402 402

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

404 404

claude-directory.md +42 −3

Details

1390 1390

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

1392 1392

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

1394 1394

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

1396 1396

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

1398

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

1398 1400

1399<ClaudeExplorer />1401<ClaudeExplorer />

1400 1402

1406| ----------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1408| ----------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

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

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

1410 1412

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

1412 1414

1415## Choose the right file

1416

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

1418

1420| :------------------------------------------------- | :--------------------------------------- | :---------------- | :------------------------------------------------- |

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

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

1430

1413## File reference1431## File reference

1414 1432

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

1445 1463

1464## Troubleshoot configuration

1465

1466If a setting, hook, or file isn't taking effect, scan the symptoms below.

1467

1468| Symptom | Cause | Fix |

1469| :--------------------------------------------------------------- | :------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1471| Hook never fires | `matcher` value is lowercase, for example `"bash"` | Matching is case-sensitive. Tool names are capitalized: `Bash`, `Edit`, `Write`, `Read`. |

1472| Hook never fires | Hooks are in a standalone `.claude/hooks.json` file | There is no standalone hooks file. Define hooks under the `"hooks"` key in `settings.json`. See [hook configuration](/en/hooks). |

1473| Permissions, hooks, or env set globally are ignored | Configuration was added to `~/.claude.json` | `~/.claude.json` holds app state and UI toggles. `permissions`, `hooks`, and `env` belong in `~/.claude/settings.json`. These are two different files. |

1474| A `settings.json` value seems ignored | The same key is set in `settings.local.json` | `settings.local.json` overrides `settings.json`, and both override `~/.claude/settings.json`. See [settings precedence](/en/settings#settings-precedence). |

1475| Skill doesn't appear in `/skills` | Skill file is at `.claude/skills/name.md` instead of in a folder | Use a folder with `SKILL.md` inside: `.claude/skills/name/SKILL.md`. |

1476| Subdirectory `CLAUDE.md` instructions seem ignored | Subdirectory files load on demand, not at session start | They load when Claude reads a file in that directory with the Read tool, not at launch and not when writing or creating files there. See [how CLAUDE.md files load](/en/memory#how-claude-md-files-load). |

1477| Subagent ignores `CLAUDE.md` instructions | Subagents don't always inherit project memory | Put critical rules in the agent file body, which becomes the subagent's system prompt. See [subagent configuration](/en/sub-agents). |

1478| Cleanup logic never runs at session end | No `SessionEnd` hook configured | `SessionStart` and `SessionEnd` both exist. See the [hook events list](/en/hooks#hook-events). |

1479| MCP servers in `.mcp.json` never load | File is under `.claude/` or uses Claude Desktop's config format | Project MCP config lives at the repository root as `.mcp.json`, not inside `.claude/`. See [MCP configuration](/en/mcp). |

1480| Project MCP server added but doesn't appear | The one-time approval prompt was dismissed | Project-scoped servers require approval. Run `/mcp` to see status and approve. |

1481| MCP server fails to start from some directories | `command` or `args` uses a relative file path | Use absolute paths for local scripts. Executables on your `PATH` like `npx` or `uvx` work as-is. |

1482| MCP server starts without expected environment variables | Variables are in `settings.json` `env`, which doesn't propagate to MCP child processes | Set per-server `env` inside `.mcp.json` instead. |

1483| `Bash(rm *)` deny rule doesn't block `/bin/rm` or `find -delete` | Prefix rules match the literal command string, not the underlying executable | Add explicit patterns for each variant, or use a [PreToolUse hook](/en/hooks-guide) or the [sandbox](/en/sandboxing) for a hard guarantee. |

1484

1446## Check what loaded1485## Check what loaded

1447 1486

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

commands.md +2 −2

Details

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

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

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

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

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

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

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

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

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

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

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

common-workflows.md +9 −1

Details

403 403

404***404***

405 405

406## Work in notes and non-code folders

407

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

409

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

411

412***

413

406## Work with images414## Work with images

407 415

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

506 514

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

508 516

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

510 518

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

512 520

desktop.md +24 −0

Details

539 539

540The remote machine must run Linux or macOS, and Claude Code must be installed on it. Once connected, SSH sessions support permission modes, connectors, plugins, and MCP servers.540The remote machine must run Linux or macOS, and Claude Code must be installed on it. Once connected, SSH sessions support permission modes, connectors, plugins, and MCP servers.

541 541

542#### Pre-configure SSH connections for your team

543

544Administrators can distribute SSH connections to team members by adding `sshConfigs` to a [managed settings](/en/settings#settings-precedence) file. Connections defined this way appear in each user's environment dropdown automatically and are shown as managed, so users can select them but cannot edit or delete them in the app.

545

546The following example pre-configures a single connection that opens in `~/projects` on the remote host:

547

548```json theme={null}

549{

550 "sshConfigs": [

551 {

552 "id": "shared-dev-vm",

553 "name": "Shared Dev VM",

554 "sshHost": "user@dev.example.com",

555 "sshPort": 22,

556 "sshIdentityFile": "~/.ssh/id_ed25519",

557 "startDirectory": "~/projects"

558 }

559 ]

560}

561```

562

563Each entry requires `id`, `name`, and `sshHost`. The `sshPort`, `sshIdentityFile`, and `startDirectory` fields are optional. Users can also add `sshConfigs` to their own `~/.claude/settings.json`, which is where connections added through the dialog are stored.

564

542## Enterprise configuration565## Enterprise configuration

543 566

544Organizations on Team or Enterprise plans can manage desktop app behavior through admin console controls, managed settings files, and device management policies.567Organizations on Team or Enterprise plans can manage desktop app behavior through admin console controls, managed settings files, and device management policies.

561| `permissions.disableBypassPermissionsMode` | set to `"disable"` to prevent users from enabling Bypass permissions mode. |584| `permissions.disableBypassPermissionsMode` | set to `"disable"` to prevent users from enabling Bypass permissions mode. |

562| `disableAutoMode` | set to `"disable"` to prevent users from enabling [Auto](/en/permission-modes#eliminate-prompts-with-auto-mode) mode. Removes Auto from the mode selector. Also accepted under `permissions`. |585| `disableAutoMode` | set to `"disable"` to prevent users from enabling [Auto](/en/permission-modes#eliminate-prompts-with-auto-mode) mode. Removes Auto from the mode selector. Also accepted under `permissions`. |

563| `autoMode` | customize what the auto mode classifier trusts and blocks across your organization. See [Configure the auto mode classifier](/en/permissions#configure-the-auto-mode-classifier). |586| `autoMode` | customize what the auto mode classifier trusts and blocks across your organization. See [Configure the auto mode classifier](/en/permissions#configure-the-auto-mode-classifier). |

587| `sshConfigs` | pre-configure [SSH connections](#pre-configure-ssh-connections-for-your-team) that appear in the environment dropdown. Users cannot edit or delete managed connections. |

564 588

565`permissions.disableBypassPermissionsMode` and `disableAutoMode` also work in user and project settings, but placing them in managed settings prevents users from overriding them. `autoMode` is read from user settings, `.claude/settings.local.json`, and managed settings, but not from the checked-in `.claude/settings.json`: a cloned repo cannot inject its own classifier rules. For the complete list of managed-only settings including `allowManagedPermissionRulesOnly` and `allowManagedHooksOnly`, see [managed-only settings](/en/permissions#managed-only-settings).589`permissions.disableBypassPermissionsMode` and `disableAutoMode` also work in user and project settings, but placing them in managed settings prevents users from overriding them. `autoMode` is read from user settings, `.claude/settings.local.json`, and managed settings, but not from the checked-in `.claude/settings.json`: a cloned repo cannot inject its own classifier rules. For the complete list of managed-only settings including `allowManagedPermissionRulesOnly` and `allowManagedHooksOnly`, see [managed-only settings](/en/permissions#managed-only-settings).

566 590

env-vars.md +3 −2

Details

128| `CLAUDE_CODE_SHELL` | Override automatic shell detection. Useful when your login shell differs from your preferred working shell (for example, `bash` vs `zsh`) |128| `CLAUDE_CODE_SHELL` | Override automatic shell detection. Useful when your login shell differs from your preferred working shell (for example, `bash` vs `zsh`) |

129| `CLAUDE_CODE_SHELL_PREFIX` | Command prefix to wrap all bash commands (for example, for logging or auditing). Example: `/path/to/logger.sh` will execute `/path/to/logger.sh <command>` |129| `CLAUDE_CODE_SHELL_PREFIX` | Command prefix to wrap all bash commands (for example, for logging or auditing). Example: `/path/to/logger.sh` will execute `/path/to/logger.sh <command>` |

130| `CLAUDE_CODE_SIMPLE` | Set to `1` to run with a minimal system prompt and only the Bash, file read, and file edit tools. MCP tools from `--mcp-config` are still available. Disables auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md. The [`--bare`](/en/headless#start-faster-with-bare-mode) CLI flag sets this |130| `CLAUDE_CODE_SIMPLE` | Set to `1` to run with a minimal system prompt and only the Bash, file read, and file edit tools. MCP tools from `--mcp-config` are still available. Disables auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md. The [`--bare`](/en/headless#start-faster-with-bare-mode) CLI flag sets this |

131| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | Set to `1` to use the minimal system prompt and collapsed tool descriptions from `CLAUDE_CODE_SIMPLE` without the other simple-mode changes. The full tool set, hooks, MCP servers, and CLAUDE.md discovery remain enabled |

132| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Skip Azure authentication for Microsoft Foundry (for example, when using an LLM gateway) |133| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Skip Azure authentication for Microsoft Foundry (for example, when using an LLM gateway) |

196| `OTEL_LOG_RAW_API_BODIES` | Set to `1` to emit the full Anthropic Messages API request and response JSON as OpenTelemetry log events (`api_request_body`, `api_response_body`). Disabled by default; bodies include the entire conversation history. See [Monitoring](/en/monitoring-usage) |197| `OTEL_LOG_RAW_API_BODIES` | Emit Anthropic Messages API request and response JSON as `api_request_body` / `api_response_body` log events. Set to `1` for inline bodies truncated at 60 KB, or `file:<dir>` to write untruncated bodies to disk and emit a `body_ref` path instead. Disabled by default; bodies include the entire conversation history. See [Monitoring](/en/monitoring-usage#api-request-body-event) |

197| `OTEL_LOG_TOOL_CONTENT` | Set to `1` to include tool input and output content in OpenTelemetry span events. Disabled by default to protect sensitive data. See [Monitoring](/en/monitoring-usage) |198| `OTEL_LOG_TOOL_CONTENT` | Set to `1` to include tool input and output content in OpenTelemetry span events. Disabled by default to protect sensitive data. See [Monitoring](/en/monitoring-usage) |

198| `OTEL_LOG_TOOL_DETAILS` | Set to `1` to include tool input arguments, MCP server names, and tool details in OpenTelemetry traces and logs. Disabled by default to protect PII. See [Monitoring](/en/monitoring-usage) |199| `OTEL_LOG_TOOL_DETAILS` | Set to `1` to include tool input arguments, MCP server names, raw error strings on tool failures, and other tool details in OpenTelemetry traces and logs. Disabled by default to protect PII. See [Monitoring](/en/monitoring-usage) |

199| `OTEL_LOG_USER_PROMPTS` | Set to `1` to include user prompt text in OpenTelemetry traces and logs. Disabled by default (prompts are redacted). See [Monitoring](/en/monitoring-usage) |200| `OTEL_LOG_USER_PROMPTS` | Set to `1` to include user prompt text in OpenTelemetry traces and logs. Disabled by default (prompts are redacted). See [Monitoring](/en/monitoring-usage) |

200| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | Set to `false` to exclude account UUID from metrics attributes (default: included). See [Monitoring](/en/monitoring-usage) |201| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | Set to `false` to exclude account UUID from metrics attributes (default: included). See [Monitoring](/en/monitoring-usage) |

201| `OTEL_METRICS_INCLUDE_SESSION_ID` | Set to `false` to exclude session ID from metrics attributes (default: included). See [Monitoring](/en/monitoring-usage) |202| `OTEL_METRICS_INCLUDE_SESSION_ID` | Set to `false` to exclude session ID from metrics attributes (default: included). See [Monitoring](/en/monitoring-usage) |

hooks.md +61 −9

Details

18 18

19<div style={{maxWidth: "500px", margin: "0 auto"}}>19<div style={{maxWidth: "500px", margin: "0 auto"}}>

20 <Frame>20 <Frame>

21 <img src="https://mintcdn.com/claude-code/UMJp-WgTWngzO609/images/hooks-lifecycle.svg?fit=max&auto=format&n=UMJp-WgTWngzO609&q=85&s=3f4de67df216c87dc313943b32c15f62" alt="Hook lifecycle diagram showing SessionStart, then a per-turn loop containing UserPromptSubmit, the nested agentic loop (PreToolUse, PermissionRequest, PostToolUse, SubagentStart/Stop, TaskCreated, TaskCompleted), and Stop or StopFailure, followed by TeammateIdle, PreCompact, PostCompact, and SessionEnd, with Elicitation and ElicitationResult nested inside MCP tool execution, PermissionDenied as a side branch from PermissionRequest for auto-mode denials, and WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged, and FileChanged as standalone async events" width="520" height="1155" data-path="images/hooks-lifecycle.svg" />21 <img src="https://mintcdn.com/claude-code/NgDeMMkM7ZmaRibg/images/hooks-lifecycle.svg?fit=max&auto=format&n=NgDeMMkM7ZmaRibg&q=85&s=ec53c77f9943a6470cb2c8ecace6d809" alt="Hook lifecycle diagram showing SessionStart, then a per-turn loop containing UserPromptSubmit, UserPromptExpansion for slash commands, the nested agentic loop (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, SubagentStart/Stop, TaskCreated, TaskCompleted), and Stop or StopFailure, followed by TeammateIdle, PreCompact, PostCompact, and SessionEnd, with Elicitation and ElicitationResult nested inside MCP tool execution, PermissionDenied as a side branch from PermissionRequest for auto-mode denials, and WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged, and FileChanged as standalone async events" width="520" height="1155" data-path="images/hooks-lifecycle.svg" />

22 </Frame>22 </Frame>

23</div>23</div>

24 24

25The table below summarizes when each event fires. The [Hook events](#hook-events) section documents the full input schema and decision control options for each one.25The table below summarizes when each event fires. The [Hook events](#hook-events) section documents the full input schema and decision control options for each one.

26 26

27| Event | When it fires |27| Event | When it fires |

~~28| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |~~28| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

29| `SessionStart` | When a session begins or resumes |29| `SessionStart` | When a session begins or resumes |

30| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |30| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |

31| `UserPromptExpansion` | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion |

31| `PreToolUse` | Before a tool call executes. Can block it |32| `PreToolUse` | Before a tool call executes. Can block it |

32| `PermissionRequest` | When a permission dialog appears |33| `PermissionRequest` | When a permission dialog appears |

33| `PermissionDenied` | When a tool call is denied by the auto mode classifier. Return `{retry: true}` to tell the model it may retry the denied tool call |34| `PermissionDenied` | When a tool call is denied by the auto mode classifier. Return `{retry: true}` to tell the model it may retry the denied tool call |

203| `UserPromptExpansion` | command name | your skill or command names |

204| `UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove` | no matcher support | always fires on every occurrence |206| `UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove` | no matcher support | always fires on every occurrence |

512 514

513The exit code from your hook command tells Claude Code whether the action should proceed, be blocked, or be ignored.515The exit code from your hook command tells Claude Code whether the action should proceed, be blocked, or be ignored.

514 516

515**Exit 0** means success. Claude Code parses stdout for [JSON output fields](#json-output). JSON output is only processed on exit 0. For most events, stdout is written to the debug log but not shown in the transcript. The exceptions are `UserPromptSubmit` and `SessionStart`, where stdout is added as context that Claude can see and act on.517**Exit 0** means success. Claude Code parses stdout for [JSON output fields](#json-output). JSON output is only processed on exit 0. For most events, stdout is written to the debug log but not shown in the transcript. The exceptions are `UserPromptSubmit`, `UserPromptExpansion`, and `SessionStart`, where stdout is added as context that Claude can see and act on.

516 518

517**Exit 2** means a blocking error. Claude Code ignores stdout and any JSON in it. Instead, stderr text is fed back to Claude as an error message. The effect depends on the event: `PreToolUse` blocks the tool call, `UserPromptSubmit` rejects the prompt, and so on. See [exit code 2 behavior](#exit-code-2-behavior-per-event) for the full list.519**Exit 2** means a blocking error. Claude Code ignores stdout and any JSON in it. Instead, stderr text is fed back to Claude as an error message. The effect depends on the event: `PreToolUse` blocks the tool call, `UserPromptSubmit` rejects the prompt, and so on. See [exit code 2 behavior](#exit-code-2-behavior-per-event) for the full list.

518 520

542Exit code 2 is the way a hook signals "stop, don't do this." The effect depends on the event, because some events represent actions that can be blocked (like a tool call that hasn't happened yet) and others represent things that already happened or can't be prevented.544Exit code 2 is the way a hook signals "stop, don't do this." The effect depends on the event, because some events represent actions that can be blocked (like a tool call that hasn't happened yet) and others represent things that already happened or can't be prevented.

543 545

545| :------------------- | :--------- | :----------------------------------------------------------------------------------------------------------------------------------- |547| :-------------------- | :--------- | :----------------------------------------------------------------------------------------------------------------------------------- |

546| `PreToolUse` | Yes | Blocks the tool call |548| `PreToolUse` | Yes | Blocks the tool call |

547| `PermissionRequest` | Yes | Denies the permission |549| `PermissionRequest` | Yes | Denies the permission |

548| `UserPromptSubmit` | Yes | Blocks prompt processing and erases the prompt |550| `UserPromptSubmit` | Yes | Blocks prompt processing and erases the prompt |

551| `UserPromptExpansion` | Yes | Blocks the expansion |

549| `Stop` | Yes | Prevents Claude from stopping, continues the conversation |552| `Stop` | Yes | Prevents Claude from stopping, continues the conversation |

550| `SubagentStop` | Yes | Prevents the subagent from stopping |553| `SubagentStop` | Yes | Prevents the subagent from stopping |

551| `TeammateIdle` | Yes | Prevents the teammate from going idle (teammate continues working) |554| `TeammateIdle` | Yes | Prevents the teammate from going idle (teammate continues working) |

618Not every event supports blocking or controlling behavior through JSON. The events that do each use a different set of fields to express that decision. Use this table as a quick reference before writing a hook:621Not every event supports blocking or controlling behavior through JSON. The events that do each use a different set of fields to express that decision. Use this table as a quick reference before writing a hook:

619 622

621| :-------------------------------------------------------------------------------------------------------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |624| :------------------------------------------------------------------------------------------------------------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

623| TeammateIdle, TaskCreated, TaskCompleted | Exit code or `continue: false` | Exit code 2 blocks the action with stderr feedback. JSON `{"continue": false, "stopReason": "..."}` also stops the teammate entirely, matching `Stop` hook behavior |626| TeammateIdle, TaskCreated, TaskCompleted | Exit code or `continue: false` | Exit code 2 blocks the action with stderr feedback. JSON `{"continue": false, "stopReason": "..."}` also stops the teammate entirely, matching `Stop` hook behavior |

633 636

634<Tabs>637<Tabs>

635 <Tab title="Top-level decision">638 <Tab title="Top-level decision">

636 Used by `UserPromptSubmit`, `PostToolUse`, `PostToolUseFailure`, `Stop`, `SubagentStop`, `ConfigChange`, and `PreCompact`. The only value is `"block"`. To allow the action to proceed, omit `decision` from your JSON, or exit 0 without any JSON at all:639 Used by `UserPromptSubmit`, `UserPromptExpansion`, `PostToolUse`, `PostToolUseFailure`, `Stop`, `SubagentStop`, `ConfigChange`, and `PreCompact`. The only value is `"block"`. To allow the action to proceed, omit `decision` from your JSON, or exit 0 without any JSON at all:

637 640

638 ```json theme={null}641 ```json theme={null}

639 {642 {

865 block prompts or want more structured control.868 block prompts or want more structured control.

866</Note>869</Note>

867 870

871### UserPromptExpansion

872

873Runs when a user-typed slash command expands into a prompt before reaching Claude. Use this to block specific commands from direct invocation, inject context for a particular skill, or log which commands users invoke. For example, a hook matching `deploy` can block `/deploy` unless an approval file is present, or a hook matching a review skill can append the team's review checklist as `additionalContext`.

874

875This event covers the path `PreToolUse` does not: a `PreToolUse` hook matching the `Skill` tool fires only when Claude calls the tool, but typing `/skillname` directly bypasses `PreToolUse`. `UserPromptExpansion` fires on that direct path.

876

877Matches on `command_name`. Leave the matcher empty to fire on every prompt-type slash command.

878

879#### UserPromptExpansion input

880

881In addition to the [common input fields](#common-input-fields), UserPromptExpansion hooks receive `expansion_type`, `command_name`, `command_args`, `command_source`, and the original `prompt` string. The `expansion_type` field is `slash_command` for skill and custom commands, or `mcp_prompt` for MCP server prompts.

882

883```json theme={null}

884{

885 "session_id": "abc123",

886 "transcript_path": "/Users/.../00893aaf.jsonl",

887 "cwd": "/Users/...",

888 "permission_mode": "default",

889 "hook_event_name": "UserPromptExpansion",

890 "expansion_type": "slash_command",

891 "command_name": "example-skill",

892 "command_args": "arg1 arg2",

893 "command_source": "plugin",

894 "prompt": "/example-skill arg1 arg2"

895}

896```

897

898#### UserPromptExpansion decision control

899

900`UserPromptExpansion` hooks can block the expansion or add context. All [JSON output fields](#json-output) are available.

901

902| Field | Description |

903| :------------------ | :------------------------------------------------------------------------------- |

904| `decision` | `"block"` prevents the slash command from expanding. Omit to allow it to proceed |

905| `reason` | Shown to the user when `decision` is `"block"` |

906| `additionalContext` | String added to Claude's context alongside the expanded prompt |

907

908```json theme={null}

909{

910 "decision": "block",

911 "reason": "This slash command is not available",

912 "hookSpecificOutput": {

913 "hookEventName": "UserPromptExpansion",

914 "additionalContext": "Additional context for this expansion"

915 }

916}

917```

918

868### PreToolUse919### PreToolUse

869 920

870Runs after Claude creates tool parameters and before processing the tool call. Matches on tool name: `Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `WebFetch`, `WebSearch`, `AskUserQuestion`, `ExitPlanMode`, and any [MCP tool names](#match-mcp-tools).921Runs after Claude creates tool parameters and before processing the tool call. Matches on tool name: `Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `WebFetch`, `WebSearch`, `AskUserQuestion`, `ExitPlanMode`, and any [MCP tool names](#match-mcp-tools).

1700 1751

1701Runs when the working directory changes during a session, for example when Claude executes a `cd` command. Use this to react to directory changes: reload environment variables, activate project-specific toolchains, or run setup scripts automatically. Pairs with [FileChanged](#filechanged) for tools like [direnv](https://direnv.net/) that manage per-directory environment.1752Runs when the working directory changes during a session, for example when Claude executes a `cd` command. Use this to react to directory changes: reload environment variables, activate project-specific toolchains, or run setup scripts automatically. Pairs with [FileChanged](#filechanged) for tools like [direnv](https://direnv.net/) that manage per-directory environment.

1702 1753

1703CwdChanged hooks have access to `CLAUDE_ENV_FILE`. Variables written to that file persist into subsequent Bash commands for the session, just as in [SessionStart hooks](#persist-environment-variables). Only `type: "command"` hooks are supported.1754CwdChanged hooks have access to `CLAUDE_ENV_FILE`. Variables written to that file persist into subsequent Bash commands for the session, just as in [SessionStart hooks](#persist-environment-variables).

1704 1755

1705CwdChanged does not support matchers and fires on every directory change.1756CwdChanged does not support matchers and fires on every directory change.

1706 1757

1738* **Build the watch list**: the value is split on `|` and each segment is registered as a literal filename in the working directory, so `".envrc|.env"` watches exactly those two files. Regex patterns are not useful here: a value like `^\.env` would watch a file literally named `^\.env`.1789* **Build the watch list**: the value is split on `|` and each segment is registered as a literal filename in the working directory, so `".envrc|.env"` watches exactly those two files. Regex patterns are not useful here: a value like `^\.env` would watch a file literally named `^\.env`.

1739* **Filter which hooks run**: when a watched file changes, the same value filters which hook groups run using the standard [matcher rules](#matcher-patterns) against the changed file's basename.1790* **Filter which hooks run**: when a watched file changes, the same value filters which hook groups run using the standard [matcher rules](#matcher-patterns) against the changed file's basename.

1740 1791

1741FileChanged hooks have access to `CLAUDE_ENV_FILE`. Variables written to that file persist into subsequent Bash commands for the session, just as in [SessionStart hooks](#persist-environment-variables). Only `type: "command"` hooks are supported.1792FileChanged hooks have access to `CLAUDE_ENV_FILE`. Variables written to that file persist into subsequent Bash commands for the session, just as in [SessionStart hooks](#persist-environment-variables).

1742 1793

1743#### FileChanged input1794#### FileChanged input

1744 1795

2087* `SubagentStop`2138* `SubagentStop`

2088* `TaskCompleted`2139* `TaskCompleted`

2089* `TaskCreated`2140* `TaskCreated`

2141* `UserPromptExpansion`

2090* `UserPromptSubmit`2142* `UserPromptSubmit`

2091 2143

2092Events that support `command` and `http` hooks but not `prompt` or `agent`:2144Events that support `command` and `http` hooks but not `prompt` or `agent`:

hooks-guide.md +4 −2

Details

426Hook events fire at specific lifecycle points in Claude Code. When an event fires, all matching hooks run in parallel, and identical hook commands are automatically deduplicated. The table below shows each event and when it triggers:426Hook events fire at specific lifecycle points in Claude Code. When an event fires, all matching hooks run in parallel, and identical hook commands are automatically deduplicated. The table below shows each event and when it triggers:

427 427

428| Event | When it fires |428| Event | When it fires |

429| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |429| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

432| `UserPromptExpansion` | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion |

434| `PermissionDenied` | When a tool call is denied by the auto mode classifier. Return `{retry: true}` to tell the model it may retry the denied tool call |435| `PermissionDenied` | When a tool call is denied by the auto mode classifier. Return `{retry: true}` to tell the model it may retry the denied tool call |

503 504

504The exit code determines what happens next:505The exit code determines what happens next:

505 506

506* **Exit 0**: the action proceeds. For `UserPromptSubmit` and `SessionStart` hooks, anything you write to stdout is added to Claude's context.507* **Exit 0**: the action proceeds. For `UserPromptSubmit`, `UserPromptExpansion`, and `SessionStart` hooks, anything you write to stdout is added to Claude's context.

507* **Exit 2**: the action is blocked. Write a reason to stderr, and Claude receives it as feedback so it can adjust.508* **Exit 2**: the action is blocked. Write a reason to stderr, and Claude receives it as feedback so it can adjust.

508* **Any other exit code**: the action proceeds. The transcript shows a `<hook name> hook error` notice followed by the first line of stderr; the full stderr goes to the [debug log](/en/hooks#debug-hooks).509* **Any other exit code**: the action proceeds. The transcript shows a `<hook name> hook error` notice followed by the first line of stderr; the full stderr goes to the [debug log](/en/hooks#debug-hooks).

509 510

583| `UserPromptExpansion` | command name | your skill or command names |

582| `UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `CwdChanged` | no matcher support | always fires on every occurrence |584| `UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `CwdChanged` | no matcher support | always fires on every occurrence |

583 585

584A few more examples showing matchers on different event types:586A few more examples showing matchers on different event types:

interactive-mode.md +1 −1

Details

301 301

302When working on complex, multi-step work, Claude creates a task list to track progress. Tasks appear in the status area of your terminal with indicators showing what's pending, in progress, or complete.302When working on complex, multi-step work, Claude creates a task list to track progress. Tasks appear in the status area of your terminal with indicators showing what's pending, in progress, or complete.

303 303

304* Press `Ctrl+T` to toggle the task list view. The display shows up to 10 tasks at a time304* Press `Ctrl+T` to toggle the task list view. The display shows up to 5 tasks at a time

305* To see all tasks or clear them, ask Claude directly: "show me all tasks" or "clear all tasks"305* To see all tasks or clear them, ask Claude directly: "show me all tasks" or "clear all tasks"

306* Tasks persist across context compactions, helping Claude stay organized on larger projects306* Tasks persist across context compactions, helping Claude stay organized on larger projects

307* To share a task list across sessions, set `CLAUDE_CODE_TASK_LIST_ID` to use a named directory in `~/.claude/tasks/`: `CLAUDE_CODE_TASK_LIST_ID=my-project claude`307* To share a task list across sessions, set `CLAUDE_CODE_TASK_LIST_ID` to use a named directory in `~/.claude/tasks/`: `CLAUDE_CODE_TASK_LIST_ID=my-project claude`

mcp.md +1 −1

Details

938 938

939<Steps>939<Steps>

940 <Step title="Configure MCP servers in Claude.ai">940 <Step title="Configure MCP servers in Claude.ai">

941 Add servers at [claude.ai/settings/connectors](https://claude.ai/settings/connectors). On Team and Enterprise plans, only admins can add servers.941 Add servers at [claude.ai/customize/connectors](https://claude.ai/customize/connectors). On Team and Enterprise plans, only admins can add servers.

942 </Step>942 </Step>

943 943

944 <Step title="Authenticate the MCP server">944 <Step title="Authenticate the MCP server">

monitoring-usage.md +285 −18

Details

69### Common configuration variables69### Common configuration variables

70 70

72| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |72| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |

73| `CLAUDE_CODE_ENABLE_TELEMETRY` | Enables telemetry collection (required) | `1` |73| `CLAUDE_CODE_ENABLE_TELEMETRY` | Enables telemetry collection (required) | `1` |

88| `OTEL_LOG_TOOL_DETAILS` | Enable logging of tool parameters and input arguments in tool events and trace span attributes: Bash commands, MCP server and tool names, skill names, and tool input (default: disabled) | `1` to enable |88| `OTEL_LOG_TOOL_DETAILS` | Enable logging of tool parameters and input arguments in tool events and trace span attributes: Bash commands, MCP server and tool names, skill names, and tool input (default: disabled) | `1` to enable |

89| `OTEL_LOG_TOOL_CONTENT` | Enable logging of tool input and output content in span events (default: disabled). Requires [tracing](#traces-beta). Content is truncated at 60 KB | `1` to enable |89| `OTEL_LOG_TOOL_CONTENT` | Enable logging of tool input and output content in span events (default: disabled). Requires [tracing](#traces-beta). Content is truncated at 60 KB | `1` to enable |

90| `OTEL_LOG_RAW_API_BODIES` | Emit the full Anthropic Messages API request and response JSON as `api_request_body` / `api_response_body` log events (default: disabled). Bodies include the entire conversation history and are truncated at 60 KB. Enabling this implies consent to everything `OTEL_LOG_USER_PROMPTS`, `OTEL_LOG_TOOL_DETAILS`, and `OTEL_LOG_TOOL_CONTENT` would reveal | `1` to enable |90| `OTEL_LOG_RAW_API_BODIES` | Emit the full Anthropic Messages API request and response JSON as `api_request_body` / `api_response_body` log events (default: disabled). Bodies include the entire conversation history. Enabling this implies consent to everything `OTEL_LOG_USER_PROMPTS`, `OTEL_LOG_TOOL_DETAILS`, and `OTEL_LOG_TOOL_CONTENT` would reveal | `1` for inline bodies truncated at 60 KB, or `file:<dir>` for untruncated bodies on disk with a `body_ref` pointer in the event |

91| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | Metrics temporality preference (default: `delta`). Set to `cumulative` if your backend expects cumulative temporality | `delta`, `cumulative` |91| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | Metrics temporality preference (default: `delta`). Set to `cumulative` if your backend expects cumulative temporality | `delta`, `cumulative` |

92| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Interval for refreshing dynamic headers (default: 1740000ms / 29 minutes) | `900000` |92| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Interval for refreshing dynamic headers (default: 1740000ms / 29 minutes) | `900000` |

93 93

123 123

124In Agent SDK and non-interactive sessions started with `-p`, Claude Code also reads `TRACEPARENT` and `TRACESTATE` from its own environment when starting each interaction span. This lets an embedding process pass its active W3C trace context into the subprocess so Claude Code's spans appear as children of the caller's distributed trace. Interactive sessions ignore inbound `TRACEPARENT` to avoid accidentally inheriting ambient values from CI or container environments.124In Agent SDK and non-interactive sessions started with `-p`, Claude Code also reads `TRACEPARENT` and `TRACESTATE` from its own environment when starting each interaction span. This lets an embedding process pass its active W3C trace context into the subprocess so Claude Code's spans appear as children of the caller's distributed trace. Interactive sessions ignore inbound `TRACEPARENT` to avoid accidentally inheriting ambient values from CI or container environments.

125 125

126#### Span hierarchy

127

128Each user prompt starts a `claude_code.interaction` root span. API calls, tool calls, and hook executions are recorded as its children. Tool spans have two child spans of their own: one for the time spent waiting on a permission decision and one for the execution itself. When the Task tool spawns a subagent, the subagent's API and tool spans nest under the parent's `claude_code.tool` span.

129

130```text theme={null}

131claude_code.interaction

132├── claude_code.llm_request

133├── claude_code.hook (requires detailed beta tracing)

134└── claude_code.tool

135 ├── claude_code.tool.blocked_on_user

136 ├── claude_code.tool.execution

137 └── (Task tool) subagent claude_code.llm_request / claude_code.tool spans

138```

139

140In Agent SDK and `claude -p` sessions, `claude_code.interaction` itself becomes a child of the caller's span when `TRACEPARENT` is set in the environment.

141

142#### Span attributes

143

144Every span carries the [standard attributes](#standard-attributes) plus a `span.type` attribute matching its name. The tables below list the additional attributes set on each span. The `llm_request`, `tool.execution`, and `hook` spans set OpenTelemetry status `ERROR` when they record a failure; the other spans always end with status `UNSET`.

145

146**`claude_code.interaction`**

147

148| Attribute | Description | Gated by |

149| ------------------------- | --------------------------------------------------------- | ----------------------- |

150| `user_prompt` | Prompt text. Value is `<REDACTED>` unless the gate is set | `OTEL_LOG_USER_PROMPTS` |

151| `user_prompt_length` | Prompt length in characters | |

152| `interaction.sequence` | 1-based counter of interactions in this session | |

153| `interaction.duration_ms` | Wall-clock duration of the turn | |

154

155**`claude_code.llm_request`**

156

157| Attribute | Description | Gated by |

158| ------------------------ | -------------------------------------------------------------------------------- | -------- |

159| `model` | Model identifier | |

160| `gen_ai.system` | Always `anthropic`. OpenTelemetry GenAI semantic convention | |

161| `gen_ai.request.model` | Same value as `model`. OpenTelemetry GenAI semantic convention | |

162| `query_source` | Subsystem that issued the request, such as `repl_main_thread` or a subagent name | |

163| `speed` | `fast` or `normal` | |

164| `llm_request.context` | `interaction`, `tool`, or `standalone` depending on the parent span | |

165| `duration_ms` | Wall-clock duration including retries | |

166| `ttft_ms` | Time to first token in milliseconds | |

167| `input_tokens` | Input token count from the API usage block | |

168| `output_tokens` | Output token count | |

169| `cache_read_tokens` | Tokens read from prompt cache | |

170| `cache_creation_tokens` | Tokens written to prompt cache | |

171| `request_id` | Anthropic API request ID from the `request-id` response header | |

172| `gen_ai.response.id` | Same value as `request_id`. OpenTelemetry GenAI semantic convention | |

173| `client_request_id` | Client-generated `x-client-request-id` of the final attempt | |

174| `attempt` | Total attempts made for this request | |

175| `success` | `true` or `false` | |

176| `status_code` | HTTP status code when the request failed | |

177| `error` | Error message when the request failed | |

178| `response.has_tool_call` | `true` when the response contained tool-use blocks | |

179

180Each retry attempt is also recorded as a `gen_ai.request.attempt` span event with `attempt` and `client_request_id` attributes.

181

182**`claude_code.tool`**

183

184| Attribute | Description | Gated by |

185| --------------- | ----------------------------------------------------------- | ----------------------- |

186| `tool_name` | Tool name | |

187| `duration_ms` | Wall-clock duration including permission wait and execution | |

188| `result_tokens` | Approximate token size of the tool result | |

189| `file_path` | Target file path for Read, Edit, and Write tools | `OTEL_LOG_TOOL_DETAILS` |

190| `full_command` | Command string for the Bash tool | `OTEL_LOG_TOOL_DETAILS` |

191| `skill_name` | Skill name for the Skill tool | `OTEL_LOG_TOOL_DETAILS` |

192| `subagent_type` | Subagent type for the Task tool | `OTEL_LOG_TOOL_DETAILS` |

193

194When `OTEL_LOG_TOOL_CONTENT=1`, this span also records a `tool.output` span event whose attributes contain the tool's input and output bodies, truncated at 60 KB per attribute.

195

196**`claude_code.tool.blocked_on_user`**

197

198| Attribute | Description | Gated by |

199| ------------- | --------------------------------------------------- | -------- |

200| `duration_ms` | Time spent waiting for the permission decision | |

201| `decision` | `accept` or `reject` | |

202| `source` | Decision source, matching the `tool_decision` event | |

203

204**`claude_code.tool.execution`**

205

206| Attribute | Description | Gated by |

207| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |

208| `duration_ms` | Time spent running the tool body | |

209| `success` | `true` or `false` | |

210| `error` | Error category string when execution failed, such as `Error:ENOENT` or `ShellError`. Contains the full error message instead when the gate is set | `OTEL_LOG_TOOL_DETAILS` |

211

212**`claude_code.hook`**

213

214This span is emitted only when detailed beta tracing is active, which requires `ENABLE_BETA_TRACING_DETAILED=1` and `BETA_TRACING_ENDPOINT` in addition to the trace exporter configuration above. In interactive CLI sessions, this also requires your organization to be allowlisted for the feature. Agent SDK and non-interactive `-p` sessions are not gated. It is not emitted when only `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` is set.

215

216| Attribute | Description | Gated by |

217| ------------------------ | ------------------------------------------------ | ----------------------- |

218| `hook_event` | Hook event type, such as `PreToolUse` | |

219| `hook_name` | Full hook name, such as `PreToolUse:Write` | |

220| `num_hooks` | Number of matching hook commands executed | |

221| `hook_definitions` | JSON-serialized hook configuration | `OTEL_LOG_TOOL_DETAILS` |

222| `duration_ms` | Wall-clock duration of all matching hooks | |

223| `num_success` | Count of hooks that completed successfully | |

224| `num_blocking` | Count of hooks that returned a blocking decision | |

225| `num_non_blocking_error` | Count of hooks that failed without blocking | |

226| `num_cancelled` | Count of hooks cancelled before completion | |

227

228<Note>

229 Additional content-bearing attributes such as `new_context`, `system_prompt_preview`, `tool_input`, and `response.model_output` are emitted only when detailed beta tracing is active. They are not part of the stable span schema.

230</Note>

231

126### Dynamic headers232### Dynamic headers

127 233

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

289**Attributes**:395**Attributes**:

290 396

291* All [standard attributes](#standard-attributes)397* All [standard attributes](#standard-attributes)

398* `start_type`: How the session was started. One of `"fresh"`, `"resume"`, or `"continue"`

292 399

293#### Lines of code counter400#### Lines of code counter

294 401

323 430

324* All [standard attributes](#standard-attributes)431* All [standard attributes](#standard-attributes)

325* `model`: Model identifier (for example, "claude-sonnet-4-6")432* `model`: Model identifier (for example, "claude-sonnet-4-6")

433* `query_source`: Category of the subsystem that issued the request. One of `"main"`, `"subagent"`, or `"auxiliary"`

434* `speed`: `"fast"` when the request used fast mode. Absent otherwise

326 435

327#### Token counter436#### Token counter

328 437

333* All [standard attributes](#standard-attributes)442* All [standard attributes](#standard-attributes)

334* `type`: (`"input"`, `"output"`, `"cacheRead"`, `"cacheCreation"`)443* `type`: (`"input"`, `"output"`, `"cacheRead"`, `"cacheCreation"`)

335* `model`: Model identifier (for example, "claude-sonnet-4-6")444* `model`: Model identifier (for example, "claude-sonnet-4-6")

445* `query_source`: Category of the subsystem that issued the request. One of `"main"`, `"subagent"`, or `"auxiliary"`

446* `speed`: `"fast"` when the request used fast mode. Absent otherwise

336 447

337#### Code edit tool decision counter448#### Code edit tool decision counter

338 449

403* `tool_name`: Name of the tool514* `tool_name`: Name of the tool

404* `success`: `"true"` or `"false"`515* `success`: `"true"` or `"false"`

405* `duration_ms`: Execution time in milliseconds516* `duration_ms`: Execution time in milliseconds

406* `error`: Error message (if failed)517* `error_type`: Error category string when the tool failed, such as `"Error:ENOENT"` or `"ShellError"`

518* `error` (when `OTEL_LOG_TOOL_DETAILS=1`): Full error message when the tool failed

407* `decision_type`: Either `"accept"` or `"reject"`519* `decision_type`: Either `"accept"` or `"reject"`

408* `decision_source`: Decision source - `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`520* `decision_source`: Decision source - `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`

409* `tool_result_size_bytes`: Size of the tool result in bytes521* `tool_result_size_bytes`: Size of the tool result in bytes

412 * For Bash tool: includes `bash_command`, `full_command`, `timeout`, `description`, `dangerouslyDisableSandbox`, and `git_commit_id` (the commit SHA, when a `git commit` command succeeds)524 * For Bash tool: includes `bash_command`, `full_command`, `timeout`, `description`, `dangerouslyDisableSandbox`, and `git_commit_id` (the commit SHA, when a `git commit` command succeeds)

413 * For MCP tools: includes `mcp_server_name`, `mcp_tool_name`525 * For MCP tools: includes `mcp_server_name`, `mcp_tool_name`

414 * For Skill tool: includes `skill_name`526 * For Skill tool: includes `skill_name`

527 * For Task tool: includes `subagent_type`

415* `tool_input` (when `OTEL_LOG_TOOL_DETAILS=1`): JSON-serialized tool arguments. Individual values over 512 characters are truncated, and the full payload is bounded to \~4 K characters. Applies to all tools including MCP tools.528* `tool_input` (when `OTEL_LOG_TOOL_DETAILS=1`): JSON-serialized tool arguments. Individual values over 512 characters are truncated, and the full payload is bounded to \~4 K characters. Applies to all tools including MCP tools.

416 529

417#### API request event530#### API request event

435* `cache_creation_tokens`: Number of tokens used for cache creation548* `cache_creation_tokens`: Number of tokens used for cache creation

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

437* `speed`: `"fast"` or `"normal"`, indicating whether fast mode was active550* `speed`: `"fast"` or `"normal"`, indicating whether fast mode was active

551* `query_source`: Subsystem that issued the request, such as `"repl_main_thread"`, `"compact"`, or a subagent name

438 552

439#### API error event553#### API error event

440 554

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

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

457* `speed`: `"fast"` or `"normal"`, indicating whether fast mode was active571* `speed`: `"fast"` or `"normal"`, indicating whether fast mode was active

572* `query_source`: Subsystem that issued the request, such as `"repl_main_thread"`, `"compact"`, or a subagent name

458 573

459#### API request body event574#### API request body event

460 575

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

462 577

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

464 579

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

469* `event.timestamp`: ISO 8601 timestamp584* `event.timestamp`: ISO 8601 timestamp

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

471* `body`: JSON-serialized Messages API request parameters (system prompt, messages, tools, etc.), truncated at 60 KB. Extended-thinking content in prior assistant turns is redacted.586* `body`: JSON-serialized Messages API request parameters (system prompt, messages, tools, etc.), truncated at 60 KB. Extended-thinking content in prior assistant turns is redacted. Emitted only in inline mode (`OTEL_LOG_RAW_API_BODIES=1`).

472* `body_length`: Original (pre-truncation) JSON length in characters587* `body_ref`: Absolute path to a `<dir>/<uuid>.request.json` file containing the untruncated body. Emitted only in file mode (`OTEL_LOG_RAW_API_BODIES=file:<dir>`).

473* `body_truncated`: `"true"` when truncation occurred (absent otherwise)588* `body_length`: Untruncated body length. UTF-8 bytes when `OTEL_LOG_RAW_API_BODIES=file:<dir>`, or UTF-16 code units when `=1`

589* `body_truncated`: `"true"` when inline truncation occurred. Absent in file mode and when no truncation occurred.

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

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

476 592

477#### API response body event593#### API response body event

478 594

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

480 596

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

482 598

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

487* `event.timestamp`: ISO 8601 timestamp603* `event.timestamp`: ISO 8601 timestamp

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

489* `body`: JSON-serialized Messages API response (id, content blocks, usage, stop reason), truncated at 60 KB. Extended-thinking content is redacted.605* `body`: JSON-serialized Messages API response (id, content blocks, usage, stop reason), truncated at 60 KB. Extended-thinking content is redacted. Emitted only in inline mode (`OTEL_LOG_RAW_API_BODIES=1`).

490* `body_length`: Original (pre-truncation) JSON length in characters606* `body_ref`: Absolute path to a `<dir>/<request_id>.response.json` file containing the untruncated body. Emitted only in file mode (`OTEL_LOG_RAW_API_BODIES=file:<dir>`).

491* `body_truncated`: `"true"` when truncation occurred (absent otherwise)607* `body_length`: Untruncated body length. UTF-8 bytes when `OTEL_LOG_RAW_API_BODIES=file:<dir>`, or UTF-16 code units when `=1`

608* `body_truncated`: `"true"` when inline truncation occurred. Absent in file mode and when no truncation occurred.

492* `model`: Model identifier609* `model`: Model identifier

493* `query_source`: Subsystem that issued the request610* `query_source`: Subsystem that issued the request

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

509* `decision`: Either `"accept"` or `"reject"`626* `decision`: Either `"accept"` or `"reject"`

510* `source`: Decision source - `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`627* `source`: Decision source - `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`

511 628

629#### Permission mode changed event

630

631Logged when the permission mode changes, for example from `Shift+Tab` cycling, exiting plan mode, or an auto mode gate check.

632

633**Event Name**: `claude_code.permission_mode_changed`

634

635**Attributes**:

636

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

638* `event.name`: `"permission_mode_changed"`

639* `event.timestamp`: ISO 8601 timestamp

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

641* `from_mode`: The previous permission mode, for example `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, or `"bypassPermissions"`

642* `to_mode`: The new permission mode

643* `trigger`: What caused the change. One of `"shift_tab"`, `"exit_plan_mode"`, `"auto_gate_denied"`, or `"auto_opt_in"`. Absent when the transition originates from the SDK or bridge

644

645#### Auth event

646

647Logged when `/login` or `/logout` completes.

648

649**Event Name**: `claude_code.auth`

650

651**Attributes**:

652

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

654* `event.name`: `"auth"`

655* `event.timestamp`: ISO 8601 timestamp

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

657* `action`: `"login"` or `"logout"`

658* `success`: `"true"` or `"false"`

659* `auth_method`: Authentication method, such as `"oauth"`

660* `error_category`: Categorical error kind when the action failed. The raw error message is never included

661* `status_code`: HTTP status code as a string when the action failed with an HTTP error

662

663#### MCP server connection event

664

665Logged when an MCP server connects, disconnects, or fails to connect.

666

667**Event Name**: `claude_code.mcp_server_connection`

668

669**Attributes**:

670

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

672* `event.name`: `"mcp_server_connection"`

673* `event.timestamp`: ISO 8601 timestamp

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

675* `status`: `"connected"`, `"failed"`, or `"disconnected"`

676* `transport_type`: Server transport, such as `"stdio"`, `"sse"`, or `"http"`

677* `server_scope`: Scope the server is configured at, such as `"user"`, `"project"`, or `"local"`

678* `duration_ms`: Connection attempt duration in milliseconds

679* `error_code`: Error code when the connection failed

680* `server_name` (when `OTEL_LOG_TOOL_DETAILS=1`): Configured server name

681* `error` (when `OTEL_LOG_TOOL_DETAILS=1`): Full error message when the connection failed

682

683#### Internal error event

684

685Logged when Claude Code catches an unexpected internal error. Only the error class name and an errno-style code are recorded. The error message and stack trace are never included. This event is not emitted when running against Bedrock, Vertex, or Foundry, or when `DISABLE_ERROR_REPORTING` is set.

686

687**Event Name**: `claude_code.internal_error`

688

689**Attributes**:

690

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

692* `event.name`: `"internal_error"`

693* `event.timestamp`: ISO 8601 timestamp

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

695* `error_name`: Error class name, such as `"TypeError"` or `"SyntaxError"`

696* `error_code`: Node.js errno code such as `"ENOENT"` when present on the error

697

512#### Plugin installed event698#### Plugin installed event

513 699

514Logged when a plugin finishes installing, from both the `claude plugin install` CLI command and the interactive `/plugin` UI.700Logged when a plugin finishes installing, from both the `claude plugin install` CLI command and the interactive `/plugin` UI.

521* `event.name`: `"plugin_installed"`707* `event.name`: `"plugin_installed"`

522* `event.timestamp`: ISO 8601 timestamp708* `event.timestamp`: ISO 8601 timestamp

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

524* `plugin.name`: Name of the installed plugin

525* `plugin.version`: Plugin version when declared in the marketplace entry

526* `marketplace.name`: Marketplace the plugin was installed from

527* `marketplace.is_official`: `"true"` if the marketplace is an official Anthropic marketplace, `"false"` otherwise710* `marketplace.is_official`: `"true"` if the marketplace is an official Anthropic marketplace, `"false"` otherwise

528* `install.trigger`: `"cli"` or `"ui"`711* `install.trigger`: `"cli"` or `"ui"`

712* `plugin.name`: Name of the installed plugin. For third-party marketplaces this is included only when `OTEL_LOG_TOOL_DETAILS=1`

713* `plugin.version`: Plugin version when declared in the marketplace entry. For third-party marketplaces this is included only when `OTEL_LOG_TOOL_DETAILS=1`

714* `marketplace.name`: Marketplace the plugin was installed from. For third-party marketplaces this is included only when `OTEL_LOG_TOOL_DETAILS=1`

529 715

530#### Skill activated event716#### Skill activated event

531 717

539* `event.name`: `"skill_activated"`725* `event.name`: `"skill_activated"`

540* `event.timestamp`: ISO 8601 timestamp726* `event.timestamp`: ISO 8601 timestamp

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

542* `skill.name`: Name of the skill728* `skill.name`: Name of the skill. For user-defined and third-party plugin skills the value is the placeholder `"custom_skill"` unless `OTEL_LOG_TOOL_DETAILS=1`

543* `skill.source`: Where the skill was loaded from (for example, `"bundled"`, `"userSettings"`, `"projectSettings"`, `"plugin"`)729* `skill.source`: Where the skill was loaded from (for example, `"bundled"`, `"userSettings"`, `"projectSettings"`, `"plugin"`)

544* `plugin.name`: Name of the owning plugin when the skill is provided by a plugin730* `plugin.name` (when `OTEL_LOG_TOOL_DETAILS=1` or the plugin is from an official marketplace): Name of the owning plugin when the skill is provided by a plugin

545* `marketplace.name`: Marketplace the owning plugin was installed from, when the skill is provided by a plugin731* `marketplace.name` (when `OTEL_LOG_TOOL_DETAILS=1` or the plugin is from an official marketplace): Marketplace the owning plugin was installed from, when the skill is provided by a plugin

732

733#### API retries exhausted event

734

735Logged once when an API request fails after more than one attempt. Emitted alongside the final `api_error` event.

736

737**Event Name**: `claude_code.api_retries_exhausted`

738

739**Attributes**:

740

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

742* `event.name`: `"api_retries_exhausted"`

743* `event.timestamp`: ISO 8601 timestamp

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

745* `model`: Model used

746* `error`: Final error message

747* `status_code`: HTTP status code as a string

748* `total_attempts`: Total number of attempts made

749* `total_retry_duration_ms`: Total wall-clock time across all attempts

750* `speed`: `"fast"` or `"normal"`

751

752#### Hook execution start event

753

754Logged when one or more hooks begin executing for a hook event.

755

756**Event Name**: `claude_code.hook_execution_start`

757

758**Attributes**:

759

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

761* `event.name`: `"hook_execution_start"`

762* `event.timestamp`: ISO 8601 timestamp

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

764* `hook_event`: Hook event type, such as `"PreToolUse"` or `"PostToolUse"`

765* `hook_name`: Full hook name including matcher, such as `"PreToolUse:Write"`

766* `num_hooks`: Number of matching hook commands

767* `managed_only`: `"true"` when only managed-policy hooks are permitted

768* `hook_source`: `"policySettings"` or `"merged"`

769* `hook_definitions`: JSON-serialized hook configuration. Included only when both detailed beta tracing and `OTEL_LOG_TOOL_DETAILS=1` are enabled

770

771#### Hook execution complete event

772

773Logged when all hooks for a hook event have finished.

774

775**Event Name**: `claude_code.hook_execution_complete`

776

777**Attributes**:

778

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

780* `event.name`: `"hook_execution_complete"`

781* `event.timestamp`: ISO 8601 timestamp

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

783* `hook_event`: Hook event type

784* `hook_name`: Full hook name including matcher

785* `num_hooks`: Number of matching hook commands

786* `num_success`: Count that completed successfully

787* `num_blocking`: Count that returned a blocking decision

788* `num_non_blocking_error`: Count that failed without blocking

789* `num_cancelled`: Count cancelled before completion

790* `total_duration_ms`: Wall-clock duration of all matching hooks

791* `managed_only`: `"true"` when only managed-policy hooks are permitted

792* `hook_source`: `"policySettings"` or `"merged"`

793* `hook_definitions`: JSON-serialized hook configuration. Included only when both detailed beta tracing and `OTEL_LOG_TOOL_DETAILS=1` are enabled

794

795#### Compaction event

796

797Logged when conversation compaction completes.

798

799**Event Name**: `claude_code.compaction`

800

801**Attributes**:

802

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

804* `event.name`: `"compaction"`

805* `event.timestamp`: ISO 8601 timestamp

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

807* `trigger`: `"auto"` or `"manual"`

808* `success`: `"true"` or `"false"`

809* `duration_ms`: Compaction duration

810* `pre_tokens`: Approximate token count before compaction

811* `post_tokens`: Approximate token count after compaction

812* `error`: Error message when compaction failed

546 813

547## Interpret metrics and events data814## Interpret metrics and events data

548 815

648* User prompt content is not collected by default. Only prompt length is recorded. To include prompt content, set `OTEL_LOG_USER_PROMPTS=1`915* User prompt content is not collected by default. Only prompt length is recorded. To include prompt content, set `OTEL_LOG_USER_PROMPTS=1`

649* Tool input arguments and parameters are not logged by default. To include them, set `OTEL_LOG_TOOL_DETAILS=1`. When enabled, `tool_result` events include a `tool_parameters` attribute with Bash commands, MCP server and tool names, and skill names, plus a `tool_input` attribute with file paths, URLs, search patterns, and other arguments. Trace spans include the same `tool_input` attribute and input-derived attributes such as `file_path`. Individual values over 512 characters are truncated and the total is bounded to \~4 K characters, but the arguments may still contain sensitive values. Configure your telemetry backend to filter or redact these attributes as needed916* Tool input arguments and parameters are not logged by default. To include them, set `OTEL_LOG_TOOL_DETAILS=1`. When enabled, `tool_result` events include a `tool_parameters` attribute with Bash commands, MCP server and tool names, and skill names, plus a `tool_input` attribute with file paths, URLs, search patterns, and other arguments. Trace spans include the same `tool_input` attribute and input-derived attributes such as `file_path`. Individual values over 512 characters are truncated and the total is bounded to \~4 K characters, but the arguments may still contain sensitive values. Configure your telemetry backend to filter or redact these attributes as needed

650* Tool input and output content is not logged in trace spans by default. To include it, set `OTEL_LOG_TOOL_CONTENT=1`. When enabled, span events include full tool input and output content truncated at 60 KB per span. This can include raw file contents from Read tool results and Bash command output. Configure your telemetry backend to filter or redact these attributes as needed917* Tool input and output content is not logged in trace spans by default. To include it, set `OTEL_LOG_TOOL_CONTENT=1`. When enabled, span events include full tool input and output content truncated at 60 KB per span. This can include raw file contents from Read tool results and Bash command output. Configure your telemetry backend to filter or redact these attributes as needed

651* Raw Anthropic Messages API request and response bodies are not logged by default. To include them, set `OTEL_LOG_RAW_API_BODIES=1`. When enabled, each API call emits `api_request_body` and `api_response_body` log events whose `body` attribute is the JSON-serialized payload, truncated at 60 KB. These bodies contain the full conversation history (system prompt, every prior user and assistant turn, tool results), so enabling this implies consent to everything the other `OTEL_LOG_*` content flags would reveal. Claude's extended-thinking content is always redacted from these bodies regardless of other settings918* Raw Anthropic Messages API request and response bodies are not logged by default. To include them, set `OTEL_LOG_RAW_API_BODIES`. With `=1`, each API call emits `api_request_body` and `api_response_body` log events whose `body` attribute is the JSON-serialized payload, truncated at 60 KB. With `=file:<dir>`, untruncated bodies are written to `.request.json` and `.response.json` files under that directory and the events carry a `body_ref` path instead of the inline body. Ship the directory with a log collector or sidecar rather than through the telemetry stream. In both modes, bodies contain the full conversation history (system prompt, every prior user and assistant turn, tool results), so enabling this implies consent to everything the other `OTEL_LOG_*` content flags would reveal. Claude's extended-thinking content is always redacted from these bodies regardless of other settings

652 919

653## Monitor Claude Code on Amazon Bedrock920## Monitor Claude Code on Amazon Bedrock

654 921

network-config.md +3 −3

Details

112 112

113Ensure these URLs are allowlisted in your proxy configuration and firewall rules. This is especially important when using Claude Code in containerized or restricted network environments.113Ensure these URLs are allowlisted in your proxy configuration and firewall rules. This is especially important when using Claude Code in containerized or restricted network environments.

114 114

115The native installer and update checks also require the following URLs. Allowlist both, since the installer and auto-updater fetch from `storage.googleapis.com` while plugin downloads use `downloads.claude.ai`. If you install Claude Code through npm or manage your own binary distribution, end users may not need access:115The native installer and update checks also require the following URLs. Allowlist both, since clients running older Claude Code versions fetch from `storage.googleapis.com`. If you install Claude Code through npm or manage your own binary distribution, end users may not need access:

116 116

117* `storage.googleapis.com`: download bucket for the Claude Code binary and auto-updater117* `downloads.claude.ai`: download host for the Claude Code binary, auto-updater, version pointers, manifests, install script, signing keys, and plugin executables

118* `downloads.claude.ai`: CDN hosting the install script, version pointers, manifests, signing keys, and plugin executables118* `storage.googleapis.com`: legacy download host used by older clients

119 119

120The [Chrome integration](/en/chrome) connects to the browser extension over a WebSocket bridge. If you use Claude in Chrome, allowlist `bridge.claudeusercontent.com` for outbound WebSocket connections.120The [Chrome integration](/en/chrome) connects to the browser extension over a WebSocket bridge. If you use Claude in Chrome, allowlist `bridge.claudeusercontent.com` for outbound WebSocket connections.

121 121

permissions.md +1 −1

Details

277* Filesystem restrictions in the sandbox use Read and Edit deny rules, not separate sandbox configuration277* Filesystem restrictions in the sandbox use Read and Edit deny rules, not separate sandbox configuration

278* Network restrictions combine WebFetch permission rules with the sandbox's `allowedDomains` and `deniedDomains` lists278* Network restrictions combine WebFetch permission rules with the sandbox's `allowedDomains` and `deniedDomains` lists

279 279

280When sandboxing is enabled with `autoAllowBashIfSandboxed: true`, which is the default, sandboxed Bash commands run without prompting even if your permissions include `ask: Bash(*)`. The sandbox boundary substitutes for the per-command prompt. See [sandbox modes](/en/sandboxing#sandbox-modes) to change this behavior.280When sandboxing is enabled with `autoAllowBashIfSandboxed: true`, which is the default, sandboxed Bash commands run without prompting even if your permissions include `ask: Bash(*)`. The sandbox boundary substitutes for the per-command prompt. Explicit deny rules still apply, and `rm` or `rmdir` commands that target `/`, your home directory, or other critical system paths still trigger a prompt. See [sandbox modes](/en/sandboxing#sandbox-modes) to change this behavior.

281 281

282## Managed settings282## Managed settings

283 283

plugin-dependencies.md +30 −3

Details

8 8

9A plugin can depend on other plugins by listing them in `plugin.json` or in its marketplace entry. By default, a dependency tracks the latest available version, so an upstream release can change the dependency under your plugin without warning. Version constraints let you hold a dependency at a tested version range until you choose to move.9A plugin can depend on other plugins by listing them in `plugin.json` or in its marketplace entry. By default, a dependency tracks the latest available version, so an upstream release can change the dependency under your plugin without warning. Version constraints let you hold a dependency at a tested version range until you choose to move.

10 10

~~11When you install a plugin that declares dependencies, Claude Code resolves and installs them automatically and lists which dependencies were added at the end of the install output.~~11When you install a plugin that declares dependencies, Claude Code resolves and installs them automatically and lists which dependencies were added at the end of the install output. If a dependency later goes missing, `/reload-plugins` and the background plugin auto-update install it automatically, provided its marketplace is already in your configured marketplaces. Dependencies from a marketplace you have not added are left unresolved.

12 12

13This guide is for plugin authors who declare dependencies in `plugin.json` and for marketplace maintainers who tag releases. To install plugins that have dependencies, see [Discover and install plugins](/en/discover-plugins). For the full manifest schema, see the [Plugins reference](/en/plugins-reference).13This guide is for plugin authors who declare dependencies in `plugin.json` and for marketplace maintainers who tag releases. To install plugins that have dependencies, see [Discover and install plugins](/en/discover-plugins). For the full manifest schema, see the [Plugins reference](/en/plugins-reference).

14 14

44An entry can be a bare string with only the plugin name, like `"audit-logger"` in the example above, which depends on whatever version that plugin's marketplace provides. For more control, use an object with these fields:44An entry can be a bare string with only the plugin name, like `"audit-logger"` in the example above, which depends on whatever version that plugin's marketplace provides. For more control, use an object with these fields:

45 45

47| :------------ | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |47| :------------ | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

49| `version` | string | A [semver range](https://github.com/npm/node-semver#ranges) such as `~2.1.0`, `^2.0`, `>=1.4`, or `=2.1.0`. The dependency is fetched at the highest tagged version that satisfies this range. |49| `version` | string | A [semver range](https://github.com/npm/node-semver#ranges) such as `~2.1.0`, `^2.0`, `>=1.4`, or `=2.1.0`. The dependency is fetched at the highest tagged version that satisfies this range. |

50| `marketplace` | string | A different marketplace to resolve `name` in. Cross-marketplace dependencies are blocked unless the target marketplace is allowlisted in the root marketplace's `marketplace.json`. |50| `marketplace` | string | A different marketplace to resolve `name` in. Cross-marketplace dependencies are blocked unless the target marketplace is listed in [`allowCrossMarketplaceDependenciesOn`](#depend-on-a-plugin-from-another-marketplace) in the root marketplace's `marketplace.json`. |

51 51

52The `version` field accepts any expression supported by Node's `semver` package, including caret, tilde, hyphen, and comparator ranges. Pre-release versions such as `2.0.0-beta.1` are excluded unless your range opts in with a pre-release suffix like `^2.0.0-0`.52The `version` field accepts any expression supported by Node's `semver` package, including caret, tilde, hyphen, and comparator ranges. Pre-release versions such as `2.0.0-beta.1` are excluded unless your range opts in with a pre-release suffix like `^2.0.0-0`.

53 53

54## Depend on a plugin from another marketplace

56By default, Claude Code refuses to auto-install a dependency that lives in a different marketplace than the plugin declaring it. This prevents one marketplace from silently pulling in plugins from a source you have not reviewed.

58To allow it, the maintainer of the root marketplace adds the target marketplace name to `allowCrossMarketplaceDependenciesOn` in `marketplace.json`. The root marketplace is the one that hosts the plugin the user is installing; only its allowlist is consulted, so trust does not chain through intermediate marketplaces.

60The following `marketplace.json` allows `deploy-kit` to depend on a plugin from `acme-shared`:

62```json .claude-plugin/marketplace.json theme={null}

63{

64 "name": "acme-tools",

65 "owner": { "name": "Acme" },

66 "allowCrossMarketplaceDependenciesOn": ["acme-shared"],

67 "plugins": [

68 {

69 "name": "deploy-kit",

70 "source": "./deploy-kit",

71 "dependencies": [

72 { "name": "audit-logger", "marketplace": "acme-shared" }

73 ]

74 }

75 ]

76}

77```

79If the field is missing or does not include the target marketplace, install fails with a `cross-marketplace` error naming the field to set. Users can still install the dependency manually first, which satisfies the constraint without changing the allowlist.

54## Tag plugin releases for version resolution81## Tag plugin releases for version resolution

55 82

56Version constraints resolve against git tags on the marketplace repository. For Claude Code to find a dependency's available versions, the upstream plugin's releases must be tagged using a specific naming convention.83Version constraints resolve against git tags on the marketplace repository. For Claude Code to find a dependency's available versions, the upstream plugin's releases must be tagged using a specific naming convention.

plugin-marketplaces.md +3 −2

Details

169 169

170### Optional metadata170### Optional fields

171 171

173| :--------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |173| :------------------------------------ | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

176| `metadata.pluginRoot` | string | Base directory prepended to relative plugin source paths (for example, `"./plugins"` lets you write `"source": "formatter"` instead of `"source": "./plugins/formatter"`) |176| `metadata.pluginRoot` | string | Base directory prepended to relative plugin source paths (for example, `"./plugins"` lets you write `"source": "formatter"` instead of `"source": "./plugins/formatter"`) |

177| `allowCrossMarketplaceDependenciesOn` | array | Other marketplaces that plugins in this marketplace may depend on. Dependencies from a marketplace not listed here are blocked at install. See [Depend on a plugin from another marketplace](/en/plugin-dependencies#depend-on-a-plugin-from-another-marketplace). |

177 178

178## Plugin entries179## Plugin entries

179 180

plugins-reference.md +2 −1

Details

109Plugin hooks respond to the same lifecycle events as [user-defined hooks](/en/hooks):109Plugin hooks respond to the same lifecycle events as [user-defined hooks](/en/hooks):

110 110

111| Event | When it fires |111| Event | When it fires |

112| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |112| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

115| `UserPromptExpansion` | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion |

117| `PermissionDenied` | When a tool call is denied by the auto mode classifier. Return `{retry: true}` to tell the model it may retry the denied tool call |118| `PermissionDenied` | When a tool call is denied by the auto mode classifier. Return `{retry: true}` to tell the model it may retry the denied tool call |

sandboxing.md +2 −2

Details

97 97

98This opens a menu where you can choose between sandbox modes. If required dependencies are missing (such as `bubblewrap` or `socat` on Linux), the menu displays installation instructions for your platform.98This opens a menu where you can choose between sandbox modes. If required dependencies are missing (such as `bubblewrap` or `socat` on Linux), the menu displays installation instructions for your platform.

99 99

100By default, if the sandbox cannot start (missing dependencies, unsupported platform, or platform restrictions), Claude Code shows a warning and runs commands without sandboxing. To make this a hard failure instead, set [`sandbox.failIfUnavailable`](/en/settings#sandbox-settings) to `true`. This is intended for managed deployments that require sandboxing as a security gate.100By default, if the sandbox cannot start (missing dependencies or unsupported platform), Claude Code shows a warning and runs commands without sandboxing. To make this a hard failure instead, set [`sandbox.failIfUnavailable`](/en/settings#sandbox-settings) to `true`. This is intended for managed deployments that require sandboxing as a security gate.

101 101

102### Sandbox modes102### Sandbox modes

103 103

104Claude Code offers two sandbox modes:104Claude Code offers two sandbox modes:

105 105

106**Auto-allow mode**: Bash commands will attempt to run inside the sandbox and are automatically allowed without requiring permission. Commands that cannot be sandboxed (such as those needing network access to non-allowed hosts) fall back to the regular permission flow. Explicit deny rules are always respected. Ask rules apply only to commands that fall back to the regular permission flow.106**Auto-allow mode**: Bash commands will attempt to run inside the sandbox and are automatically allowed without requiring permission. Commands that cannot be sandboxed (such as those needing network access to non-allowed hosts) fall back to the regular permission flow. Explicit deny rules are always respected, and `rm` or `rmdir` commands that target `/`, your home directory, or other critical system paths still trigger a permission prompt. Ask rules apply only to commands that fall back to the regular permission flow.

107 107

108**Regular permissions mode**: All bash commands go through the standard permission flow, even when sandboxed. This provides more control but requires more approvals.108**Regular permissions mode**: All bash commands go through the standard permission flow, even when sandboxed. This provides more control but requires more approvals.

109 109

settings.md +4 −3

Details

87 87

88 * **Server-managed settings**: delivered from Anthropic's servers via the Claude.ai admin console. See [server-managed settings](/en/server-managed-settings).88 * **Server-managed settings**: delivered from Anthropic's servers via the Claude.ai admin console. See [server-managed settings](/en/server-managed-settings).

89 * **MDM/OS-level policies**: delivered through native device management on macOS and Windows:89 * **MDM/OS-level policies**: delivered through native device management on macOS and Windows:

~~90 * macOS: `com.anthropic.claudecode` managed preferences domain (deployed via configuration profiles in Jamf, Iru (Kandji), or other MDM tools)~~90 * macOS: `com.anthropic.claudecode` managed preferences domain. The plist's top-level keys mirror `managed-settings.json`, with nested settings as dictionaries and arrays as plist arrays. Deploy via configuration profiles in Jamf, Iru (Kandji), or similar MDM tools.

91 * Windows: `HKLM\SOFTWARE\Policies\ClaudeCode` registry key with a `Settings` value (REG\_SZ or REG\_EXPAND\_SZ) containing JSON (deployed via Group Policy or Intune)91 * Windows: `HKLM\SOFTWARE\Policies\ClaudeCode` registry key with a `Settings` value (REG\_SZ or REG\_EXPAND\_SZ) containing JSON (deployed via Group Policy or Intune)

92 * Windows (user-level): `HKCU\SOFTWARE\Policies\ClaudeCode` (lowest policy priority, only used when no admin-level source exists)92 * Windows (user-level): `HKCU\SOFTWARE\Policies\ClaudeCode` (lowest policy priority, only used when no admin-level source exists)

93 * **File-based**: `managed-settings.json` and `managed-mcp.json` deployed to system directories:93 * **File-based**: `managed-settings.json` and `managed-mcp.json` deployed to system directories:

217| `spinnerTipsOverride` | Override spinner tips with custom strings. `tips`: array of tip strings. `excludeDefault`: if `true`, only show custom tips; if `false` or absent, custom tips are merged with built-in tips | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |217| `spinnerTipsOverride` | Override spinner tips with custom strings. `tips`: array of tip strings. `excludeDefault`: if `true`, only show custom tips; if `false` or absent, custom tips are merged with built-in tips | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |

218| `spinnerVerbs` | Customize the action verbs shown in the spinner and turn duration messages. Set `mode` to `"replace"` to use only your verbs, or `"append"` to add them to the defaults | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |218| `spinnerVerbs` | Customize the action verbs shown in the spinner and turn duration messages. Set `mode` to `"replace"` to use only your verbs, or `"append"` to add them to the defaults | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |

219| `sshConfigs` | SSH connections to show in the [Desktop](/en/desktop#pre-configure-ssh-connections-for-your-team) environment dropdown. Each entry requires `id`, `name`, and `sshHost`; `sshPort`, `sshIdentityFile`, and `startDirectory` are optional. When set in managed settings, connections are read-only for users. Read from managed and user settings only | `[{"id": "dev-vm", "name": "Dev VM", "sshHost": "user@dev.example.com"}]` |

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

220| `strictKnownMarketplaces` | (Managed settings only) Allowlist of plugin marketplaces users can add. Undefined = no restrictions, empty array = lockdown. Applies to marketplace additions only. See [Managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |221| `strictKnownMarketplaces` | (Managed settings only) Allowlist of plugin marketplaces users can add. Undefined = no restrictions, empty array = lockdown. Applies to marketplace additions only. See [Managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |

221| `tui` | Terminal UI renderer. Use `"fullscreen"` for the flicker-free [alt-screen renderer](/en/fullscreen) with virtualized scrollback. Use `"default"` for the classic main-screen renderer. Set via `/tui` | `"fullscreen"` |222| `tui` | Terminal UI renderer. Use `"fullscreen"` for the flicker-free [alt-screen renderer](/en/fullscreen) with virtualized scrollback. Use `"default"` for the classic main-screen renderer. Set via `/tui` | `"fullscreen"` |

284| :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------- |285| :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------- |

286| `failIfUnavailable` | Exit with an error at startup if `sandbox.enabled` is true but the sandbox cannot start (missing dependencies, unsupported platform, or platform restrictions). When false (default), a warning is shown and commands run unsandboxed. Intended for managed settings deployments that require sandboxing as a hard gate | `true` |287| `failIfUnavailable` | Exit with an error at startup if `sandbox.enabled` is true but the sandbox cannot start (missing dependencies or unsupported platform). When false (default), a warning is shown and commands run unsandboxed. Intended for managed settings deployments that require sandboxing as a hard gate | `true` |

289| `allowUnsandboxedCommands` | Allow commands to run outside the sandbox via the `dangerouslyDisableSandbox` parameter. When set to `false`, the `dangerouslyDisableSandbox` escape hatch is completely disabled and all commands must run sandboxed (or be in `excludedCommands`). Useful for enterprise policies that require strict sandboxing. Default: true | `false` |290| `allowUnsandboxedCommands` | Allow commands to run outside the sandbox via the `dangerouslyDisableSandbox` parameter. When set to `false`, the `dangerouslyDisableSandbox` escape hatch is completely disabled and all commands must run sandboxed (or be in `excludedCommands`). Useful for enterprise policies that require strict sandboxing. Default: true | `false` |

482 483

483### Verify active settings484### Verify active settings

484 485

485Run `/status` inside Claude Code to see which settings sources are active and where they come from. The output shows each configuration layer (managed, user, project) along with its origin, such as `Enterprise managed settings (remote)`, `Enterprise managed settings (plist)`, `Enterprise managed settings (HKLM)`, or `Enterprise managed settings (file)`. If a settings file contains errors, `/status` reports the issue so you can fix it.486Run `/status` inside Claude Code to see which settings sources are active and where they come from. The output shows each configuration layer (managed, user, project) along with its origin, such as `Enterprise managed settings (remote)`, `Enterprise managed settings (plist)`, `Enterprise managed settings (HKLM)`, `Enterprise managed settings (HKCU)`, or `Enterprise managed settings (file)`. If a settings file contains errors, `/status` reports the issue so you can fix it.

486 487

487### Key points about the configuration system488### Key points about the configuration system

488 489

setup.md +1 −1

Details

364 Set `VERSION` to the release you want to verify.364 Set `VERSION` to the release you want to verify.

365 365

366 ```bash theme={null}366 ```bash theme={null}

367 REPO=https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases367 REPO=https://downloads.claude.ai/claude-code-releases

368 VERSION=2.1.89368 VERSION=2.1.89

369 curl -fsSLO "$REPO/$VERSION/manifest.json"369 curl -fsSLO "$REPO/$VERSION/manifest.json"

370 curl -fsSLO "$REPO/$VERSION/manifest.json.sig"370 curl -fsSLO "$REPO/$VERSION/manifest.json.sig"

skills.md +3 −1

Details

192| `description` | Recommended | What the skill does and when to use it. Claude uses this to decide when to apply the skill. If omitted, uses the first paragraph of markdown content. Front-load the key use case: the combined `description` and `when_to_use` text is truncated at 1,536 characters in the skill listing to reduce context usage. |192| `description` | Recommended | What the skill does and when to use it. Claude uses this to decide when to apply the skill. If omitted, uses the first paragraph of markdown content. Front-load the key use case: the combined `description` and `when_to_use` text is truncated at 1,536 characters in the skill listing to reduce context usage. |

193| `when_to_use` | No | Additional context for when Claude should invoke the skill, such as trigger phrases or example requests. Appended to `description` in the skill listing and counts toward the 1,536-character cap. |193| `when_to_use` | No | Additional context for when Claude should invoke the skill, such as trigger phrases or example requests. Appended to `description` in the skill listing and counts toward the 1,536-character cap. |

194| `argument-hint` | No | Hint shown during autocomplete to indicate expected arguments. Example: `[issue-number]` or `[filename] [format]`. |194| `argument-hint` | No | Hint shown during autocomplete to indicate expected arguments. Example: `[issue-number]` or `[filename] [format]`. |

195| `arguments` | No | Named positional arguments for [`$name` substitution](#available-string-substitutions) in the skill content. Accepts a space-separated string or a YAML list. Names map to argument positions in order. |

195| `disable-model-invocation` | No | Set to `true` to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually with `/name`. Default: `false`. |196| `disable-model-invocation` | No | Set to `true` to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually with `/name`. Default: `false`. |

196| `user-invocable` | No | Set to `false` to hide from the `/` menu. Use for background knowledge users shouldn't invoke directly. Default: `true`. |197| `user-invocable` | No | Set to `false` to hide from the `/` menu. Use for background knowledge users shouldn't invoke directly. Default: `true`. |

197| `allowed-tools` | No | Tools Claude can use without asking permission when this skill is active. Accepts a space-separated string or a YAML list. |198| `allowed-tools` | No | Tools Claude can use without asking permission when this skill is active. Accepts a space-separated string or a YAML list. |

198| `model` | No | Model to use when this skill is active. |199| `model` | No | Model to use when this skill is active. The override applies for the rest of the current turn and is not saved to settings; the session model resumes on your next prompt. Accepts the same values as [`/model`](/en/model-config), or `inherit` to keep the active model. |

199| `effort` | No | [Effort level](/en/model-config#adjust-effort-level) when this skill is active. Overrides the session effort level. Default: inherits from session. Options: `low`, `medium`, `high`, `xhigh`, `max`; available levels depend on the model. |200| `effort` | No | [Effort level](/en/model-config#adjust-effort-level) when this skill is active. Overrides the session effort level. Default: inherits from session. Options: `low`, `medium`, `high`, `xhigh`, `max`; available levels depend on the model. |

200| `context` | No | Set to `fork` to run in a forked subagent context. |201| `context` | No | Set to `fork` to run in a forked subagent context. |

201| `agent` | No | Which subagent type to use when `context: fork` is set. |202| `agent` | No | Which subagent type to use when `context: fork` is set. |

212| `$ARGUMENTS` | All arguments passed when invoking the skill. If `$ARGUMENTS` is not present in the content, arguments are appended as `ARGUMENTS: <value>`. |213| `$ARGUMENTS` | All arguments passed when invoking the skill. If `$ARGUMENTS` is not present in the content, arguments are appended as `ARGUMENTS: <value>`. |

214| `$N` | Shorthand for `$ARGUMENTS[N]`, such as `$0` for the first argument or `$1` for the second. |215| `$N` | Shorthand for `$ARGUMENTS[N]`, such as `$0` for the first argument or `$1` for the second. |

216| `$name` | Named argument declared in the [`arguments`](#frontmatter-reference) frontmatter list. Names map to positions in order, so with `arguments: [issue, branch]` the placeholder `$issue` expands to the first argument and `$branch` to the second. |

215| `${CLAUDE_SESSION_ID}` | The current session ID. Useful for logging, creating session-specific files, or correlating skill output with sessions. |217| `${CLAUDE_SESSION_ID}` | The current session ID. Useful for logging, creating session-specific files, or correlating skill output with sessions. |

216| `${CLAUDE_SKILL_DIR}` | The directory containing the skill's `SKILL.md` file. For plugin skills, this is the skill's subdirectory within the plugin, not the plugin root. Use this in bash injection commands to reference scripts or files bundled with the skill, regardless of the current working directory. |218| `${CLAUDE_SKILL_DIR}` | The directory containing the skill's `SKILL.md` file. For plugin skills, this is the skill's subdirectory within the plugin, not the plugin root. Use this in bash injection commands to reference scripts or files bundled with the skill, regardless of the current working directory. |

217 219

statusline.md +2 −2

Details

25 25

26## Set up a status line26## Set up a status line

27 27

28Use the [`/statusline` command](#use-the-statusline-command) to have Claude Code generate a script for you, or [manually create a script](#manually-configure-a-status-line) and add it to your settings.28Use the [`/statusline` command](#use-the-%2Fstatusline-command) to have Claude Code generate a script for you, or [manually create a script](#manually-configure-a-status-line) and add it to your settings.

29 29

30### Use the /statusline command30### Use the /statusline command

31 31

72 72

73This walkthrough shows what's happening under the hood by manually creating a status line that displays the current model, working directory, and context window usage percentage.73This walkthrough shows what's happening under the hood by manually creating a status line that displays the current model, working directory, and context window usage percentage.

74 74

~~75<Note>Running [`/statusline`](#use-the-statusline-command) with a description of what you want configures all of this for you automatically.</Note>~~75<Note>Running [`/statusline`](#use-the-%2Fstatusline-command) with a description of what you want configures all of this for you automatically.</Note>

76 76

77These examples use Bash scripts, which work on macOS and Linux. On Windows, see [Windows configuration](#windows-configuration) for PowerShell and Git Bash examples.77These examples use Bash scripts, which work on macOS and Linux. On Windows, see [Windows configuration](#windows-configuration) for PowerShell and Git Bash examples.

78 78

sub-agents.md +3 −3

Details

500Define hooks directly in the subagent's markdown file. These hooks only run while that specific subagent is active and are cleaned up when it finishes.500Define hooks directly in the subagent's markdown file. These hooks only run while that specific subagent is active and are cleaned up when it finishes.

501 501

502<Note>502<Note>

503 Frontmatter hooks fire when the agent is spawned as a subagent through the Agent tool or an @-mention. They do not fire when the agent runs as the main session via [`--agent`](#invoke-subagents-explicitly) or the `agent` setting. For session-wide hooks, configure them in [`settings.json`](/en/hooks).503 Frontmatter hooks fire when the agent is spawned as a subagent through the Agent tool or an @-mention, and when the agent runs as the main session via [`--agent`](#invoke-subagents-explicitly) or the `agent` setting. In the main-session case they run alongside any hooks defined in [`settings.json`](/en/hooks).

504</Note>504</Note>

505 505

506All [hook events](/en/hooks#hook-events) are supported. The most common events for subagents are:506All [hook events](/en/hooks#hook-events) are supported. The most common events for subagents are:

531---531---

532```532```

533 533

534`Stop` hooks in frontmatter are automatically converted to `SubagentStop` events.534When the agent is invoked as a subagent, `Stop` hooks in frontmatter are automatically converted to `SubagentStop` events.

535 535

536#### Project-level hooks for subagent events536#### Project-level hooks for subagent events

537 537

688 688

689Consider [Skills](/en/skills) instead when you want reusable prompts or workflows that run in the main conversation context rather than isolated subagent context.689Consider [Skills](/en/skills) instead when you want reusable prompts or workflows that run in the main conversation context rather than isolated subagent context.

690 690

691For a quick question about something already in your conversation, use [`/btw`](/en/interactive-mode#side-questions-with-btw) instead of a subagent. It sees your full context but has no tool access, and the answer is discarded rather than added to history.691For a quick question about something already in your conversation, use [`/btw`](/en/interactive-mode#side-questions-with-%2Fbtw) instead of a subagent. It sees your full context but has no tool access, and the answer is discarded rather than added to history.

692 692

693<Note>693<Note>

694 Subagents cannot spawn other subagents. If your workflow requires nested delegation, use [Skills](/en/skills) or [chain subagents](#chain-subagents) from the main conversation.694 Subagents cannot spawn other subagents. If your workflow requires nested delegation, use [Skills](/en/skills) or [chain subagents](#chain-subagents) from the main conversation.

terminal-config.md +1 −1

Details

29| VS Code, Cursor, Windsurf, Alacritty, Zed | Run `/terminal-setup` once |29| VS Code, Cursor, Windsurf, Alacritty, Zed | Run `/terminal-setup` once |

30| Windows Terminal, gnome-terminal, JetBrains IDEs such as PyCharm and Android Studio | Not available; use Ctrl+J or `\` then Enter |30| Windows Terminal, gnome-terminal, JetBrains IDEs such as PyCharm and Android Studio | Not available; use Ctrl+J or `\` then Enter |

31 31

32For VS Code, Cursor, Windsurf, Alacritty, and Zed, `/terminal-setup` writes Shift+Enter and other keybindings into the terminal's configuration file. If it reports a conflict such as `Found existing VSCode terminal Shift+Enter key binding`, remove that entry from the terminal's own keybindings file, for example VS Code's `keybindings.json`, and run the command again. Run `/terminal-setup` directly in the host terminal rather than inside tmux or screen, since it needs to write to the host terminal's configuration.32For VS Code, Cursor, Windsurf, Alacritty, and Zed, `/terminal-setup` writes Shift+Enter and other keybindings into the terminal's configuration file. In VS Code, Cursor, and Windsurf it also sets `terminal.integrated.mouseWheelScrollSensitivity` in the editor settings for smoother scrolling in [fullscreen mode](/en/fullscreen). Existing bindings and settings are left in place; if you see a message such as `VSCode terminal Shift+Enter key binding already configured`, no change was made. Run `/terminal-setup` directly in the host terminal rather than inside tmux or screen, since it needs to write to the host terminal's configuration.

33 33

34If you are running inside tmux, Shift+Enter also requires the [tmux configuration below](#configure-tmux) even when the outer terminal supports it.34If you are running inside tmux, Shift+Enter also requires the [tmux configuration below](#configure-tmux) even when the outer terminal supports it.

35 35

troubleshooting.md +9 −9

Details

41 41

42### Check network connectivity42### Check network connectivity

43 43

~~44The installer downloads from `storage.googleapis.com`. Verify you can reach it:~~44The installer downloads from `downloads.claude.ai`. Verify you can reach it:

45 45

46```bash theme={null}46```bash theme={null}

~~47curl -sI https://storage.googleapis.com~~47curl -sI https://downloads.claude.ai

48```48```

49 49

50If this fails, your network may be blocking the connection. Common causes:50If this fails, your network may be blocking the connection. Common causes:

51 51

~~52* Corporate firewalls or proxies blocking Google Cloud Storage~~52* Corporate firewalls or proxies blocking `downloads.claude.ai`

53* Regional network restrictions: try a VPN or alternative network53* Regional network restrictions: try a VPN or alternative network

54* TLS/SSL issues: update your system's CA certificates, or check if `HTTPS_PROXY` is configured54* TLS/SSL issues: update your system's CA certificates, or check if `HTTPS_PROXY` is configured

55 55

279 279

280**Solutions:**280**Solutions:**

281 281

2821. **Check network stability**: Claude Code binaries are hosted on Google Cloud Storage. Test that you can reach it:2821. **Check network stability**: Claude Code binaries are hosted at `downloads.claude.ai`. Test that you can reach it:

283 ```bash theme={null}283 ```bash theme={null}

284 curl -fsSL https://storage.googleapis.com -o /dev/null284 curl -fsSL https://downloads.claude.ai -o /dev/null

285 ```285 ```

286 If the command completes silently, your connection is fine and the issue is likely intermittent. Retry the install command. If you see an error, your network may be blocking the download.286 If the command completes silently, your connection is fine and the issue is likely intermittent. Retry the install command. If you see an error, your network may be blocking the download.

287 287

337 ```337 ```

338 Alternatively, install with `winget install Anthropic.ClaudeCode`, which avoids curl entirely.338 Alternatively, install with `winget install Anthropic.ClaudeCode`, which avoids curl entirely.

339 339

340### `Failed to fetch version from storage.googleapis.com`340### `Failed to fetch version from downloads.claude.ai`

341 341

342The installer couldn't reach the download server. This typically means `storage.googleapis.com` is blocked on your network.342The installer couldn't reach the download server. This typically means `downloads.claude.ai` is blocked on your network.

343 343

344**Solutions:**344**Solutions:**

345 345

3461. **Test connectivity directly**:3461. **Test connectivity directly**:

347 ```bash theme={null}347 ```bash theme={null}

348 curl -sI https://storage.googleapis.com348 curl -sI https://downloads.claude.ai

349 ```349 ```

350 350

3512. **If behind a proxy**, set `HTTPS_PROXY` so the installer can route through it. See [proxy configuration](/en/network-config#proxy-configuration) for details.3512. **If behind a proxy**, set `HTTPS_PROXY` so the installer can route through it. See [proxy configuration](/en/network-config#proxy-configuration) for details.

502 ```502 ```

503 If it shows `linux-vdso.so` or references to `/lib/x86_64-linux-gnu/`, you're on glibc. If it shows `musl`, you're on musl.503 If it shows `linux-vdso.so` or references to `/lib/x86_64-linux-gnu/`, you're on glibc. If it shows `musl`, you're on musl.

504 504

5052. **If you're on glibc but got the musl binary**, remove the installation and reinstall. You can also manually download the correct binary from the GCS bucket at `https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/{VERSION}/manifest.json`. File a [GitHub issue](https://github.com/anthropics/claude-code/issues) with the output of `ldd /bin/ls` and `ls /lib/libc.musl*`.5052. **If you're on glibc but got the musl binary**, remove the installation and reinstall. You can also manually download the correct binary using the manifest at `https://downloads.claude.ai/claude-code-releases/{VERSION}/manifest.json`. File a [GitHub issue](https://github.com/anthropics/claude-code/issues) with the output of `ldd /bin/ls` and `ls /lib/libc.musl*`.

506 506

5073. **If you're actually on musl** (Alpine Linux), install the required packages:5073. **If you're actually on musl** (Alpine Linux), install the required packages:

508 ```bash theme={null}508 ```bash theme={null}

ultrareview.md +4 −4

Details

49Ultrareview is a premium feature that bills against extra usage rather than your plan's included usage.49Ultrareview is a premium feature that bills against extra usage rather than your plan's included usage.

50 50

~~52| ------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------- |~~52| ------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------- |

~~53| Pro | 3 free runs, one-time | billed as [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |~~53| Pro | 3 free runs through May 5, 2026 | billed as [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

~~54| Max | 3 free runs, one-time | billed as [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |~~54| Max | 3 free runs through May 5, 2026 | billed as [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

56 56

57Pro and Max subscribers receive three free ultrareview runs to try the feature. These three runs are a one-time allotment per account and do not refresh. After you use them, each review is billed to extra usage and typically costs \$5 to \$20 depending on the size of the change.57Pro and Max subscribers receive three free ultrareview runs to try the feature. These three runs are a one-time allotment per account, do not refresh, and expire on May 5, 2026. After you use all three, or after the free run period ends, each review is billed to extra usage and typically costs \$5 to \$20 depending on the size of the change.

58 58

59Because ultrareview always bills as extra usage outside the free runs, your account or organization must have extra usage enabled before you can launch a paid review. If extra usage is not enabled, Claude Code blocks the launch and links you to the billing settings where you can turn it on. You can also run `/extra-usage` to check or change your current setting.59Because ultrareview always bills as extra usage outside the free runs, your account or organization must have extra usage enabled before you can launch a paid review. If extra usage is not enabled, Claude Code blocks the launch and links you to the billing settings where you can turn it on. You can also run `/extra-usage` to check or change your current setting.

60 60

vs-code.md +1 −1

Details

95* **Permission modes**: click the mode indicator at the bottom of the prompt box to switch modes. In normal mode, Claude asks permission before each action. In Plan mode, Claude describes what it will do and waits for approval before making changes. VS Code automatically opens the plan as a full markdown document where you can add inline comments to give feedback before Claude begins. In auto-accept mode, Claude makes edits without asking. Set the default in VS Code settings under `claudeCode.initialPermissionMode`.95* **Permission modes**: click the mode indicator at the bottom of the prompt box to switch modes. In normal mode, Claude asks permission before each action. In Plan mode, Claude describes what it will do and waits for approval before making changes. VS Code automatically opens the plan as a full markdown document where you can add inline comments to give feedback before Claude begins. In auto-accept mode, Claude makes edits without asking. Set the default in VS Code settings under `claudeCode.initialPermissionMode`.

96* **Command menu**: click `/` or type `/` to open the command menu. Options include attaching files, switching models, toggling extended thinking, viewing plan usage (`/usage`), and starting a [Remote Control](/en/remote-control) session (`/remote-control`). The Customize section provides access to MCP servers, hooks, memory, permissions, and plugins. Items with a terminal icon open in the integrated terminal.96* **Command menu**: click `/` or type `/` to open the command menu. Options include attaching files, switching models, toggling extended thinking, viewing plan usage (`/usage`), and starting a [Remote Control](/en/remote-control) session (`/remote-control`). The Customize section provides access to MCP servers, hooks, memory, permissions, and plugins. Items with a terminal icon open in the integrated terminal.

97* **Context indicator**: the prompt box shows how much of Claude's context window you're using. Claude automatically compacts when needed, or you can run `/compact` manually.97* **Context indicator**: the prompt box shows how much of Claude's context window you're using. Claude automatically compacts when needed, or you can run `/compact` manually.

98* **Extended thinking**: lets Claude spend more time reasoning through complex problems. Toggle it on via the command menu (`/`). See [Extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) for details.98* **Extended thinking**: lets Claude spend more time reasoning through complex problems. Toggle it on via the command menu (`/`). Claude's reasoning appears in the conversation as collapsed blocks: click a block to read it, or press `Ctrl+O` to expand or collapse every thinking block in the session. See [Extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) for details.

99* **Multi-line input**: press `Shift+Enter` to add a new line without sending. This also works in the "Other" free-text input of question dialogs.99* **Multi-line input**: press `Shift+Enter` to add a new line without sending. This also works in the "Other" free-text input of question dialogs.

100 100

101### Reference files and folders101### Reference files and folders

zero-data-retention.md +1 −1

Details

61 61

62## Request ZDR62## Request ZDR

63 63

64To request ZDR for Claude Code on Claude for Enterprise, contact your Anthropic account team. Your account team will submit the request internally, and Anthropic will review and enable ZDR on your organization after confirming eligibility. All enablement actions are audit-logged.64To request ZDR for Claude Code on Claude for Enterprise, [contact sales](https://www.anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=zero_data_retention_request) or your Anthropic account team. Your account team will submit the request internally, and Anthropic will review and enable ZDR on your organization after confirming eligibility. All enablement actions are audit-logged.

65 65

66If you are currently using ZDR for Claude Code via pay-as-you-go API keys, you can transition to Claude for Enterprise to gain access to administrative features while maintaining ZDR for Claude Code. Contact your account team to coordinate the migration.66If you are currently using ZDR for Claude Code via pay-as-you-go API keys, you can transition to Claude for Enterprise to gain access to administrative features while maintaining ZDR for Claude Code. Contact your account team to coordinate the migration.

Documentation 2026-04-20 21:14 UTC to 2026-04-21 21:14 UTC