Documentation — Spybara

agent-sdk/agent-loop.md +1 −1

Details

214| `"acceptEdits"` | Auto-approves file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.); other Bash commands follow default rules |214| `"acceptEdits"` | Auto-approves file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.); other Bash commands follow default rules |

215| `"plan"` | Claude explores and plans without editing your source files; file edits are never auto-approved and prompt through your `canUseTool` callback |215| `"plan"` | Claude explores and plans without editing your source files; file edits are never auto-approved and prompt through your `canUseTool` callback |

216| `"dontAsk"` | Never prompts. Tools pre-approved by [permission rules](/en/settings#permission-settings) run; everything else is denied. `AskUserQuestion`, connector tools [your organization set to `ask`](/en/mcp#organization-controls-on-connector-tools), and MCP tools marked [`requiresUserInteraction`](/en/mcp#require-approval-for-a-specific-tool) are denied even if you've allowed them |216| `"dontAsk"` | Never prompts. Tools pre-approved by [permission rules](/en/settings#permission-settings) run; everything else is denied. `AskUserQuestion`, connector tools [your organization set to `ask`](/en/mcp#organization-controls-on-connector-tools), and MCP tools marked [`requiresUserInteraction`](/en/mcp#require-approval-for-a-specific-tool) are denied even if you've allowed them |

217| `"auto"` | Uses a model classifier to approve or deny each tool call. See [Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) for availability and behavior |217| `"auto"` | Uses a model classifier to approve or deny permission prompts. See [Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) for availability and behavior |

218| `"bypassPermissions"` | Runs all allowed tools without asking, except tools matched by an explicit [`ask` rule](/en/settings#permission-settings), connector tools [your organization set to `ask`](/en/mcp#organization-controls-on-connector-tools), and tools that require user interaction; see [How permissions are evaluated](/en/agent-sdk/permissions#how-permissions-are-evaluated) for the precedence order. Cannot be used when running as root on Unix. Use only in isolated environments where the agent's actions cannot affect systems you care about |218| `"bypassPermissions"` | Runs all allowed tools without asking, except tools matched by an explicit [`ask` rule](/en/settings#permission-settings), connector tools [your organization set to `ask`](/en/mcp#organization-controls-on-connector-tools), and tools that require user interaction; see [How permissions are evaluated](/en/agent-sdk/permissions#how-permissions-are-evaluated) for the precedence order. Cannot be used when running as root on Unix. Use only in isolated environments where the agent's actions cannot affect systems you care about |

219 219

220For interactive applications, use `"default"` with a tool approval callback to surface approval prompts. For autonomous agents on a dev machine, `"acceptEdits"` auto-approves file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.) while still gating other `Bash` commands behind allow rules. Reserve `"bypassPermissions"` for CI, containers, or other isolated environments. See [Permissions](/en/agent-sdk/permissions) for full details.220For interactive applications, use `"default"` with a tool approval callback to surface approval prompts. For autonomous agents on a dev machine, `"acceptEdits"` auto-approves file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.) while still gating other `Bash` commands behind allow rules. Reserve `"bypassPermissions"` for CI, containers, or other isolated environments. See [Permissions](/en/agent-sdk/permissions) for full details.

agent-sdk/custom-tools.md +8 −2

Details

176 ```176 ```

177</CodeGroup>177</CodeGroup>

178 178

179Combine this snippet with the tool and server definitions from the [weather tool example](#weather-tool-example) in one file, then run it with `python weather.py` for Python or `npx tsx weather.ts` for TypeScript. Claude calls `get_temperature` and the script prints a one-line answer with the current temperature in San Francisco.

180

179### Add more tools181### Add more tools

180 182

181A server holds as many tools as you list in its `tools` array. With more than one tool on a server, you can list each one in `allowedTools` individually or use the wildcard `mcp__weather__*` to cover every tool the server exposes.183A server holds as many tools as you list in its `tools` array. With more than one tool on a server, you can list each one in `allowedTools` individually or use the wildcard `mcp__weather__*` to cover every tool the server exposes.

182 184

183The example below adds a second tool, `get_precipitation_chance`, to the `weatherServer` from the [weather tool example](#weather-tool-example) and rebuilds it with both tools in the array.185The example below defines a second tool, `get_precipitation_chance`, and replaces the `weatherServer` definition from the [weather tool example](#weather-tool-example) with one that lists both tools in the array.

184 186

185<CodeGroup>187<CodeGroup>

186 ```python Python theme={null}188 ```python Python theme={null}

263 ```265 ```

264</CodeGroup>266</CodeGroup>

265 267

266Every tool in this array consumes context window space on every turn. If you're defining dozens of tools, see [tool search](/en/agent-sdk/tool-search) to load them on demand instead.268[Tool search](/en/agent-sdk/tool-search) is on by default and defers SDK MCP tools: Claude sees each tool's name in a compact list and loads its full schema on demand. With tool search disabled, every tool in this array consumes context window space on every turn. In TypeScript, pass `alwaysLoad: true` in the `extras` argument of [`tool()`](/en/agent-sdk/typescript#tool) or in the options of [`createSdkMcpServer()`](/en/agent-sdk/typescript#createsdkmcpserver) to keep a tool's full schema in the initial prompt.

267 269

268### Add tool annotations270### Add tool annotations

269 271

355 import json357 import json

356 import httpx358 import httpx

357 from typing import Any359 from typing import Any

360 from claude_agent_sdk import tool

358 361

359 from claude_agent_sdk import tool362 from claude_agent_sdk import tool

360 363

465 ```python Python theme={null}468 ```python Python theme={null}

466 import base64469 import base64

467 import httpx470 import httpx

471 from claude_agent_sdk import tool

468 472

469 from claude_agent_sdk import tool473 from claude_agent_sdk import tool

470 474

762 766

763Once the server is defined, pass it to `query` the same way as the weather example. This example sends three different prompts in a loop to show the same tool handling different unit types. For each response, it inspects `AssistantMessage` objects (which contain the tool calls Claude made during that turn) and prints each `ToolUseBlock` before printing the final `ResultMessage` text. This lets you see when Claude is using the tool versus answering from its own knowledge.767Once the server is defined, pass it to `query` the same way as the weather example. This example sends three different prompts in a loop to show the same tool handling different unit types. For each response, it inspects `AssistantMessage` objects (which contain the tool calls Claude made during that turn) and prints each `ToolUseBlock` before printing the final `ResultMessage` text. This lets you see when Claude is using the tool versus answering from its own knowledge.

764 768

769Because [tool search](/en/agent-sdk/tool-search) is on by default, the output may also include a `ToolSearch` call as Claude loads the deferred tool schema.

770

765<CodeGroup>771<CodeGroup>

766 ```python Python theme={null}772 ```python Python theme={null}

767 import asyncio773 import asyncio

agent-sdk/overview.md +44 −7

Details

6 6

7> Build production AI agents with Claude Code as a library7> Build production AI agents with Claude Code as a library

8 8

9Build AI agents that autonomously read files, run commands, search the web, edit code, and more. The Agent SDK gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript. For other languages, [run the CLI programmatically](/en/headless) with the `-p` flag and `--output-format json`. For the thinking behind agent harness design, see [A harness for every task: dynamic workflows in Claude Code](https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code) on the blog.9Build AI agents that autonomously read files, run commands, search the web, edit code, and more. The Agent SDK gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript. For other languages, [run the CLI programmatically](/en/headless) with the `-p` flag and `--output-format json`. For the thinking behind agent harness design, see [A harness for every task: dynamic workflows in Claude Code](https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code) on the blog. To run the example below, install the SDK first by following the steps in [Get started](#get-started).

10 10

11<CodeGroup>11<CodeGroup>

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

56 <Tabs>56 <Tabs>

57 <Tab title="TypeScript">57 <Tab title="TypeScript">

58 ```bash theme={null}58 ```bash theme={null}

59 npm init -y

60 npm pkg set type=module

59 npm install @anthropic-ai/claude-agent-sdk61 npm install @anthropic-ai/claude-agent-sdk

62 npm install --save-dev tsx

60 ```63 ```

65 Setting `"type": "module"` in `package.json` lets your agent script use top-level `await`, and [tsx](https://tsx.is) runs TypeScript files directly. In an existing CommonJS project, skip the first two commands and name your script `agent.mts` instead of `agent.ts`.

61 </Tab>66 </Tab>

62 67

63 <Tab title="Python (uv)">68 <Tab title="Python (uv)">

95 </Tabs>100 </Tabs>

96 101

97 <Note>102 <Note>

~~98 The TypeScript SDK bundles a native Claude Code binary for your platform as an optional dependency, so you don't need to install Claude Code separately.~~103 Both the TypeScript and Python SDKs bundle a native Claude Code binary for your platform, so you don't need to install Claude Code separately.

99 </Note>104 </Note>

100 </Step>105 </Step>

101 106

160 }165 }

161 ```166 ```

162 </CodeGroup>167 </CodeGroup>

168

169 Save the example as `agent.py` or `agent.ts`, then run it. The agent prints a short summary of the files in the directory.

170

171 <Tabs>

172 <Tab title="TypeScript">

173 ```bash theme={null}

174 npx tsx agent.ts

175 ```

176

177 If you named your script `agent.mts` for a CommonJS project, run `npx tsx agent.mts` instead.

178 </Tab>

179

180 <Tab title="Python (uv)">

181 ```bash theme={null}

182 uv run agent.py

183 ```

184 </Tab>

185

186 <Tab title="Python (pip)">

187 With the virtual environment activated, on macOS or Linux:

188

189 ```bash theme={null}

190 python3 agent.py

191 ```

192

193 On Windows, run `python agent.py`.

194 </Tab>

195 </Tabs>

163 </Step>196 </Step>

164</Steps>197</Steps>

165 198

244 277

245 async def main():278 async def main():

246 async for message in query(279 async for message in query(

247 prompt="Refactor utils.py to improve readability",280 prompt="Create a file named hello.py that prints a greeting",

248 options=ClaudeAgentOptions(281 options=ClaudeAgentOptions(

249 allowed_tools=["Read", "Edit"],282 allowed_tools=["Read", "Edit"],

250 permission_mode="acceptEdits",283 permission_mode="acceptEdits",

273 };306 };

274 307

275 for await (const message of query({308 for await (const message of query({

276 prompt: "Refactor utils.py to improve readability",309 prompt: "Create a file named hello.ts that prints a greeting",

277 options: {310 options: {

278 allowedTools: ["Read", "Edit"],311 allowedTools: ["Read", "Edit"],

279 permissionMode: "acceptEdits",312 permissionMode: "acceptEdits",

287 ```320 ```

288 </CodeGroup>321 </CodeGroup>

289 322

323 After the agent finishes, run `cat audit.log` to see the recorded file changes.

324

290 [Learn more about hooks →](/en/agent-sdk/hooks)325 [Learn more about hooks →](/en/agent-sdk/hooks)

291 </Tab>326 </Tab>

292 327

365 options=ClaudeAgentOptions(400 options=ClaudeAgentOptions(

366 mcp_servers={401 mcp_servers={

367 "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}402 "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}

368 }403 },

404 allowed_tools=["mcp__playwright__*"],

369 ),405 ),

370 ):406 ):

371 if hasattr(message, "result"):407 if hasattr(message, "result"):

383 options: {419 options: {

384 mcpServers: {420 mcpServers: {

385 playwright: { command: "npx", args: ["@playwright/mcp@latest"] }421 playwright: { command: "npx", args: ["@playwright/mcp@latest"] }

386 }422 },

423 allowedTools: ["mcp__playwright__*"]

387 }424 }

388 })) {425 })) {

389 if ("result" in message) console.log(message.result);426 if ("result" in message) console.log(message.result);

536 <Tab title="Agent SDK vs Client SDK">573 <Tab title="Agent SDK vs Client SDK">

537 The [Anthropic Client SDK](https://platform.claude.com/docs/en/api/client-sdks) gives you direct API access: you send prompts and implement tool execution yourself. The **Agent SDK** gives you Claude with built-in tool execution.574 The [Anthropic Client SDK](https://platform.claude.com/docs/en/api/client-sdks) gives you direct API access: you send prompts and implement tool execution yourself. The **Agent SDK** gives you Claude with built-in tool execution.

538 575

539 With the Client SDK, you implement a tool loop. With the Agent SDK, Claude handles it:576 With the Client SDK, you implement a tool loop. With the Agent SDK, Claude handles it. This simplified pseudocode shows the difference:

540 577

541 <CodeGroup>578 <CodeGroup>

542 ```python Python theme={null}579 ```python Python theme={null}

agent-sdk/permissions.md +1 −1

Details

115| `acceptEdits` | Auto-accept file edits | File edits and [filesystem operations](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, etc.) are automatically approved |115| `acceptEdits` | Auto-accept file edits | File edits and [filesystem operations](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, etc.) are automatically approved |

116| `bypassPermissions` | Bypass permission checks | Tools run without permission prompts, except tools matched by an explicit [`ask` rule](#how-permissions-are-evaluated), connector tools [your organization set to `ask`](/en/mcp#organization-controls-on-connector-tools), and tools that require user interaction (use with caution) |116| `bypassPermissions` | Bypass permission checks | Tools run without permission prompts, except tools matched by an explicit [`ask` rule](#how-permissions-are-evaluated), connector tools [your organization set to `ask`](/en/mcp#organization-controls-on-connector-tools), and tools that require user interaction (use with caution) |

117| `plan` | Planning mode | Claude explores and plans without editing your source files; file edits are never auto-approved and prompt through your `canUseTool` callback |117| `plan` | Planning mode | Claude explores and plans without editing your source files; file edits are never auto-approved and prompt through your `canUseTool` callback |

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

119 119

120<Warning>120<Warning>

121 **Subagent inheritance:** Subagents inherit the parent session's permission mode. An [`AgentDefinition`'s `permissionMode`](/en/agent-sdk/typescript#agentdefinition) can override it, except when the parent uses `bypassPermissions`, `acceptEdits`, or `auto`: those modes apply to every subagent and can't be overridden per subagent.121 **Subagent inheritance:** Subagents inherit the parent session's permission mode. An [`AgentDefinition`'s `permissionMode`](/en/agent-sdk/typescript#agentdefinition) can override it, except when the parent uses `bypassPermissions`, `acceptEdits`, or `auto`: those modes apply to every subagent and can't be overridden per subagent.

agent-sdk/python.md +20 −6

Details

2458 "prompt": str, # The task for the agent to perform2458 "prompt": str, # The task for the agent to perform

2459 "subagent_type": str | None, # The type of specialized agent to use2459 "subagent_type": str | None, # The type of specialized agent to use

2461 "run_in_background": bool | None, # Launch the agent in the background2461 "run_in_background": bool | None, # Agents run in the background by default; set to False to run synchronously

2462 "name": str | None, # Name for the spawned agent2462 "name": str | None, # Name for the spawned agent

2464 "isolation": "worktree" | "remote" | None, # Isolation mode for the agent's changes2465 "isolation": "worktree" | "remote" | None, # Isolation mode for the agent's changes

2465}2466}

2466```2467```

2481 "citations": list | None,2482 "citations": list | None,

2482 }2483 }

2483 ],2484 ],

2484 "resolvedModel": str | None, # Model the subagent actually ran on2485 "resolvedModel": str | None, # Model the subagent started on

2486 "modelsUsed": list[str] | None, # Models used in order, with consecutive repeats collapsed

2485 "totalToolUseCount": int, # Number of tool calls the agent made2487 "totalToolUseCount": int, # Number of tool calls the agent made

2486 "totalDurationMs": int, # Execution duration in milliseconds2488 "totalDurationMs": int, # Execution duration in milliseconds

2487 "totalTokens": int, # Total tokens used2489 "totalTokens": int, # Total tokens used

2521 "isAsync": bool | None, # True on background launches2523 "isAsync": bool | None, # True on background launches

2522 "agentId": str, # ID of the launched agent2524 "agentId": str, # ID of the launched agent

2523 "description": str, # The task description2525 "description": str, # The task description

2524 "resolvedModel": str | None, # Model the subagent runs on2526 "resolvedModel": str | None, # Model in use at the backgrounding transition

2527 "modelsUsed": list[str] | None, # Models used before backgrounding, in order, with consecutive repeats collapsed

2525 "prompt": str, # The prompt the agent runs2528 "prompt": str, # The prompt the agent runs

2526 "outputFile": str, # File path where the agent's output is written2529 "outputFile": str, # File path where the agent's output is written

2527 "canReadOutputFile": bool | None, # Whether the output file can be read directly2530 "canReadOutputFile": bool | None, # Whether the output file can be read directly

2543 2546

2544Returns the result from the subagent. The output is discriminated on the `status` field: `"completed"` for finished tasks, `"async_launched"` for background tasks, and `"remote_launched"` for tasks Claude Code dispatched to a remote cloud session, where `sessionUrl` links to that session and `taskId` identifies it. Worktree-isolated runs include `worktreePath` and `worktreeBranch` on the `completed` variant.2547Returns the result from the subagent. The output is discriminated on the `status` field: `"completed"` for finished tasks, `"async_launched"` for background tasks, and `"remote_launched"` for tasks Claude Code dispatched to a remote cloud session, where `sessionUrl` links to that session and `taskId` identifies it. Worktree-isolated runs include `worktreePath` and `worktreeBranch` on the `completed` variant.

2545 2548

2546The `resolvedModel` field on the `completed` and `async_launched` variants names the model the subagent actually ran on, which can differ from the requested `model` input when [`availableModels`](/en/model-config#restrict-model-selection) or another override applies. {/* min-version: 2.1.174 */}This field requires Claude Code v2.1.174 or later.2549On the `completed` variant, `resolvedModel` names the model the subagent started on, which can differ from the requested `model` input when [`availableModels`](/en/model-config#restrict-model-selection) or another override applies. {/* min-version: 2.1.174 */}This field requires Claude Code v2.1.174 or later. On the `async_launched` variant, `resolvedModel` names the model in use when the agent moved to the background, so a swap that happened before backgrounding is reflected there. The `modelsUsed` field on both variants lists the models used in order, with consecutive repeats collapsed; it's set only when the model was swapped mid-run. {/* min-version: 2.1.212 */}`modelsUsed` and the backgrounding-time `resolvedModel` behavior require Claude Code v2.1.212 or later.

2547 2550

2548### AskUserQuestion2551### AskUserQuestion

2549 2552

2563 {2566 {

2564 "label": str, # Display text for this option (1-5 words)2567 "label": str, # Display text for this option (1-5 words)

2565 "description": str, # Explanation of what this option means2568 "description": str, # Explanation of what this option means

2569 "preview": str | None, # Preview content rendered when the option is focused

2566 }2570 }

2567 ],2571 ],

2568 "multiSelect": bool, # Set to true to allow multiple selections2572 "multiSelect": bool, # Set to true to allow multiple selections

2572 # User answers populated by the permission system. Multi-select2576 # User answers populated by the permission system. Multi-select

2573 # answers are a comma-joined string of the selected labels; a2577 # answers are a comma-joined string of the selected labels; a

2574 # list of labels is accepted on input and coerced to that form2578 # list of labels is accepted on input and coerced to that form

2579 "annotations": dict[str, dict] | None,

2580 # Per-question annotations from the user, keyed by question text.

2581 # Each value can carry "preview" (the selected option's preview

2582 # content) and "notes" (free-text notes on the selection)

2583 "metadata": dict | None, # Analytics metadata, such as {"source": "remember"}; not displayed to the user

2575}2584}

2576```2585```

2577 2586

2583 {2592 {

2584 "question": str,2593 "question": str,

2585 "header": str,2594 "header": str,

2586 "options": [{"label": str, "description": str}],2595 "options": [{"label": str, "description": str, "preview": str | None}],

2587 "multiSelect": bool,2596 "multiSelect": bool,

2588 }2597 }

2589 ],2598 ],

2590 "answers": dict[str, str], # Maps question text to answer string2599 "answers": dict[str, str], # Maps question text to answer string

2591 # Multi-select answers are comma-separated2600 # Multi-select answers are comma-separated

2601 "response": str | None,

2602 # Freeform reply typed instead of answering the questions; when set,

2603 # Claude receives "The user responded: ..." in place of the answer list

2604 "annotations": dict[str, dict] | None, # Per-question "preview" and "notes" from the user's selections

2605 "afkTimeoutMs": int | None, # Set when the dialog auto-resolved after this many milliseconds of user inactivity; absent when the user answered

2592}2606}

2593```2607```

2594 2608

agent-sdk/quickstart.md +2 −2

Details

90 </Tabs>90 </Tabs>

91 91

92 <Note>92 <Note>

~~93 The TypeScript SDK bundles a native Claude Code binary for your platform as an optional dependency, so you don't need to install Claude Code separately.~~93 Both the TypeScript and Python SDKs bundle a native Claude Code binary for your platform, so you don't need to install Claude Code separately.

94 </Note>94 </Note>

95 </Step>95 </Step>

96 96

358| `dontAsk` | Denies anything not in `allowedTools`; connector tools [your organization set to `ask`](/en/mcp#organization-controls-on-connector-tools) and tools that require user interaction are denied even if you've listed them | Locked-down headless agents |358| `dontAsk` | Denies anything not in `allowedTools`; connector tools [your organization set to `ask`](/en/mcp#organization-controls-on-connector-tools) and tools that require user interaction are denied even if you've listed them | Locked-down headless agents |

360| `bypassPermissions` | Runs every tool without prompting, except tools matched by an explicit [`ask` rule](/en/agent-sdk/permissions#how-permissions-are-evaluated), connector tools [your organization set to `ask`](/en/mcp#organization-controls-on-connector-tools), and tools that require user interaction. In the TypeScript SDK, also requires `allowDangerouslySkipPermissions: true` in `options` | Sandboxed CI, fully trusted environments |360| `bypassPermissions` | Runs every tool without prompting, except tools matched by an explicit [`ask` rule](/en/agent-sdk/permissions#how-permissions-are-evaluated), connector tools [your organization set to `ask`](/en/mcp#organization-controls-on-connector-tools), and tools that require user interaction. In the TypeScript SDK, also requires `allowDangerouslySkipPermissions: true` in `options` | Sandboxed CI, fully trusted environments |

362 362

agent-sdk/typescript.md +8 −4

Details

123 description: string,123 description: string,

124 inputSchema: Schema,124 inputSchema: Schema,

125 handler: (args: InferShape<Schema>, extra: unknown) => Promise<CallToolResult>,125 handler: (args: InferShape<Schema>, extra: unknown) => Promise<CallToolResult>,

126 extras?: { annotations?: ToolAnnotations }126 extras?: { annotations?: ToolAnnotations; searchHint?: string; alwaysLoad?: boolean }

127): SdkMcpToolDefinition<Schema>;127): SdkMcpToolDefinition<Schema>;

128```128```

129 129

130#### Parameters130#### Parameters

131 131

133| :------------ | :---------------------------------------------------------------- | :------------------------------------------------------------------------------ |133| :------------ | :----------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

138| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)` }` | Optional MCP tool annotations providing behavioral hints to clients |138| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)`; searchHint?: string; alwaysLoad?: boolean }` | Optional extras. `annotations` provides MCP behavioral hints to clients. `searchHint` is a one-line capability phrase shown in the deferred-tool list when [tool search](/en/agent-sdk/tool-search) is active. `alwaysLoad: true` keeps this tool's full schema in the initial prompt instead of deferring it |

139 139

140#### `ToolAnnotations`140#### `ToolAnnotations`

141 141

172function createSdkMcpServer(options: {172function createSdkMcpServer(options: {

173 name: string;173 name: string;

174 version?: string;174 version?: string;

175 instructions?: string;

175 tools?: Array<SdkMcpToolDefinition<any>>;176 tools?: Array<SdkMcpToolDefinition<any>>;

177 alwaysLoad?: boolean;

176}): McpSdkServerConfigWithInstance;178}): McpSdkServerConfigWithInstance;

177```179```

178 180

179#### Parameters181#### Parameters

180 182

182| :---------------- | :---------------------------- | :------------------------------------------------------- |184| :--------------------- | :---------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

187| `options.instructions` | `string` | Optional server instructions, returned from `initialize` and surfaced to the model as an MCP instructions block |

189| `options.alwaysLoad` | `boolean` | When `true`, every tool from this server stays in the initial prompt and is never deferred behind [tool search](/en/agent-sdk/tool-search). Combines with per-tool `alwaysLoad` in [`tool()`](#tool) |

186 190

187### `listSessions()`191### `listSessions()`

188 192

claude-directory.md +2 −2

Details

1447The explorer covers files you author and edit. A few related files live elsewhere:1447The explorer covers files you author and edit. A few related files live elsewhere:

1448 1448

1450| ----------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1450| ----------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

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

1454 1454

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

1456 1456

errors.md +4 −4

Details

836 836

837### PDF errors837### PDF errors

838 838

839The PDF you attached couldn't be processed.839The PDF you attached couldn't be processed. The messages are shown here in their non-interactive form; in an interactive session they instead prompt you to double press esc and try again.

840 840

841```text theme={null}841```text theme={null}

842PDF too large (max 100 pages, 32 MB). Try splitting it or extracting text first.842PDF too large (max 100 pages, 20MB). Try reading the file a different way (e.g., extract text with pdftotext).

843PDF is password protected. Try removing protection or extracting text first.843PDF is password protected. Try using a CLI tool to extract or convert the PDF.

844The PDF file was not valid. Try converting to a different format first.844The PDF file was not valid. Try converting it to text first (e.g., pdftotext).

845```845```

846 846

847**What to do:**847**What to do:**

hooks.md +9 −7

Details

1472| `status` | string | `"completed"` | `"completed"` for foreground subagents, `"async_launched"` for background subagents. {/* min-version: 2.1.198 */}As of v2.1.198, subagents run in the background by default, so an omitted `run_in_background` also produces `"async_launched"` |1472| `status` | string | `"completed"` | `"completed"` for foreground subagents, `"async_launched"` for background subagents. {/* min-version: 2.1.198 */}As of v2.1.198, subagents run in the background by default, so an omitted `run_in_background` also produces `"async_launched"` |

1474| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | The subagent's final text blocks |1474| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | The subagent's final text blocks |

1475| `resolvedModel` | string | `"claude-sonnet-4-5"` | Model the subagent ran on, which may differ from the requested model. {/* min-version: 2.1.174 */}Requires Claude Code v2.1.174 or later |1475| `resolvedModel` | string | `"claude-sonnet-4-5"` | Model the subagent started on, which may differ from the requested model. {/* min-version: 2.1.174 */}Requires Claude Code v2.1.174 or later |

1476| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Models used in order, with consecutive repeats collapsed; set only when the model was swapped mid-run. {/* min-version: 2.1.212 */}Requires Claude Code v2.1.212 or later |

1479| `usage` | object | `{"input_tokens": 8320, ...}` | Per-type token breakdown: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |1480| `usage` | object | `{"input_tokens": 8320, ...}` | Per-type token breakdown: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |

1480 1481

1481For background subagents, the tool returns immediately after launching, so `tool_response` carries no usage fields. It has `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, and `resolvedModel`.1482For background subagents, the tool returns when the task moves to the background, so `tool_response` carries no usage fields: a background launch returns immediately, and a foreground task that Claude Code backgrounds mid-run returns at that transition. It has `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, and `resolvedModel`.

1482 1483

1483The `resolvedModel` field names the model the subagent actually runs on, which can differ from the `model` value in `tool_input`, such as when `availableModels` or another override applies. It requires Claude Code v2.1.174 or later.1484On a `completed` response, `resolvedModel` names the model the subagent started on, which can differ from the `model` value in `tool_input`, such as when `availableModels` or another override applies. It requires Claude Code v2.1.174 or later. On an `async_launched` response, `resolvedModel` names the model in use when the agent moved to the background, so a swap that happened before backgrounding is reflected there. {/* min-version: 2.1.212 */}`modelsUsed` and the backgrounding-time `resolvedModel` behavior require Claude Code v2.1.212 or later.

1484 1485

1485<a id="askuserquestion" />1486<a id="askuserquestion" />

1486 1487

3113 3114

3114Hook execution details, including which hooks matched, their exit codes, and full stdout and stderr, are written to the debug log file. Start Claude Code with `claude --debug-file <path>` to write the log to a known location, or run `claude --debug` and read the log at `~/.claude/debug/<session-id>.txt`. The `--debug` flag doesn't print to the terminal.3115Hook execution details, including which hooks matched, their exit codes, and full stdout and stderr, are written to the debug log file. Start Claude Code with `claude --debug-file <path>` to write the log to a known location, or run `claude --debug` and read the log at `~/.claude/debug/<session-id>.txt`. The `--debug` flag doesn't print to the terminal.

3115 3116

3117For example, a `PostToolUse` hook on `Write` whose command prints `hook-ran` produces entries like:

3118

3116```text theme={null}3119```text theme={null}

3117[DEBUG] Executing hooks for PostToolUse:Write31202026-07-19T02:03:24.382Z [DEBUG] Hook output does not start with {, treating as plain text

3118[DEBUG] Found 1 hook commands to execute31212026-07-19T02:03:24.382Z [DEBUG] Hook PostToolUse:Write (PostToolUse) success:

3119[DEBUG] Executing hook command: <Your command> with timeout 600000ms3122hook-ran

3120[DEBUG] Hook command completed with status 0: <Your stdout>

3121```3123```

3122 3124

3123For more granular hook matching details, set `CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose` to see additional log lines such as hook matcher counts and query matching.3125For more granular hook matching details, set `CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose` to see additional log lines such as hook matcher counts and query matching.

large-codebases.md +12 −9

Details

107Database queries use Knex in src/db/. Never write raw SQL strings in route handlers.107Database queries use Knex in src/db/. Never write raw SQL strings in route handlers.

108```108```

109 109

110When you start Claude from `packages/api/`, it loads both `packages/api/CLAUDE.md` and the root `CLAUDE.md`. Claude sees the local instructions alongside the repository-wide rules, with no instructions from `packages/web/` in context. The same holds for any subdirectory in a non-monorepo tree.110When you start Claude from `packages/api/`, it loads both `packages/api/CLAUDE.md` and the root `CLAUDE.md`. Claude sees the local instructions alongside the repository-wide rules, with no instructions from `packages/web/` in context. The same holds for any subdirectory in a non-monorepo tree. To confirm which files loaded, run `/context` and check the list under **Memory files**.

111 111

112A few ways to keep the files current as the codebase and models change:112A few ways to keep the files current as the codebase and models change:

113 113

134 134

135Use this for directories you never work in, such as other teams' packages, legacy code, or vendored subtrees. The exclusion list is static, not a per-task switch. To focus on one package today and another tomorrow, [start Claude from that package's directory](#choose-where-to-start-claude) instead of editing exclusions.135Use this for directories you never work in, such as other teams' packages, legacy code, or vendored subtrees. The exclusion list is static, not a per-task switch. To focus on one package today and another tomorrow, [start Claude from that package's directory](#choose-where-to-start-claude) instead of editing exclusions.

136 136

137If you only want these exclusions for yourself, put the setting in `.claude/settings.local.json`. Claude Code gitignores that file when it creates it; since you're creating it by hand here, add it to your gitignore. Patterns use glob syntax matched against absolute file paths, so start relative-style patterns with `**/` to match anywhere in the tree. The example below excludes packages owned by other teams:137If you only want these exclusions for yourself, put the setting in `.claude/settings.local.json`. Claude Code gitignores that file when it creates it; since you're creating it by hand here, add it to your gitignore. Patterns use glob syntax matched against absolute file paths, so start relative-style patterns with `**/` to match anywhere in the tree. The example below excludes a package owned by another team:

138 138

139```json .claude/settings.local.json theme={null}139```json .claude/settings.local.json theme={null}

140{140{

141 "claudeMdExcludes": [141 "claudeMdExcludes": [

142 "**/packages/admin-dashboard/**",142 "**/packages/web/**"

143 "**/packages/legacy-*/**"

144 ]143 ]

145}144}

146```145```

147 146

148This skips every CLAUDE.md and rules file under those packages. The root CLAUDE.md and the packages you do work in still load normally.147This skips every CLAUDE.md and rules file under that package. The root CLAUDE.md and the packages you do work in still load normally.

149 148

150These patterns cover other common cases:149These patterns cover other common cases:

151 150

152* `"**/packages/*/CLAUDE.md"`: excludes every package's CLAUDE.md while keeping the root151* `"**/packages/*/CLAUDE.md"`: excludes every package's CLAUDE.md while keeping the root

153* `"**/packages/web/**"`: excludes everything under the web package, including rules152* `"**/packages/legacy-*/**"`: excludes every package whose name matches the glob, including rules

154* `"/home/user/monorepo/legacy/CLAUDE.md"`: excludes one specific file by absolute path153* `"/home/user/monorepo/legacy/CLAUDE.md"`: excludes one specific file by absolute path

155 154

156Managed policy CLAUDE.md files cannot be excluded, so organization-wide instructions always apply. You can set `claudeMdExcludes` at any [settings scope](/en/settings#configuration-scopes): user, project, local, or managed. Arrays merge across scopes, so a team can set project-level defaults while individuals add local overrides.155Managed policy CLAUDE.md files cannot be excluded, so organization-wide instructions always apply. You can set `claudeMdExcludes` at any [settings scope](/en/settings#configuration-scopes): user, project, local, or managed. Arrays merge across scopes, so a team can set project-level defaults while individuals add local overrides.

194 193

195In a large codebase, finding where a symbol is defined or used can cost many file reads and grep calls. [Code intelligence plugins](/en/discover-plugins#code-intelligence) connect Claude to a language server so it can jump to definitions, find references, and surface type errors directly instead of scanning the tree.194In a large codebase, finding where a symbol is defined or used can cost many file reads and grep calls. [Code intelligence plugins](/en/discover-plugins#code-intelligence) connect Claude to a language server so it can jump to definitions, find references, and surface type errors directly instead of scanning the tree.

196 195

197The official marketplace has plugins for TypeScript, Python, Go, Rust, and other common languages. The example below installs the TypeScript plugin:196The official marketplace has plugins for TypeScript, Python, Go, Rust, and other common languages. Run the command below inside a Claude Code session to install the TypeScript plugin:

198 197

199```shell theme={null}198```shell theme={null}

200/plugin install typescript-lsp@claude-plugins-official199/plugin install typescript-lsp@claude-plugins-official

216 215

217The `--worktree` flag starts a session in a new git worktree so changes stay isolated from your main checkout. By default it checks out the entire repository. In a large repository, the `worktree.sparsePaths` setting uses git sparse-checkout to write only the listed directories plus root-level files to disk, so worktrees start faster and use less space.216The `--worktree` flag starts a session in a new git worktree so changes stay isolated from your main checkout. By default it checks out the entire repository. In a large repository, the `worktree.sparsePaths` setting uses git sparse-checkout to write only the listed directories plus root-level files to disk, so worktrees start faster and use less space.

218 217

219If everyone working in this directory needs the same paths, commit the setting to `.claude/settings.json`. To add paths for yourself, use `.claude/settings.local.json`: the lists merge across scopes, so a local file can add paths to the committed list but not remove them. The example below shows the committed file:218If everyone working in this directory needs the same paths, commit the setting to `.claude/settings.json`. To add paths for yourself, use `.claude/settings.local.json`: the lists merge across scopes, so a local file can add paths to the committed list but not remove them.

219

220The JSON examples on this page show one setting at a time. If your `.claude/settings.json` already contains other keys, such as the `permissions.deny` rules above, add the `worktree` key alongside them rather than replacing the file. [Put it together](#put-it-together) shows the combined result.

221

222The example below shows the committed file:

220 223

221```json .claude/settings.json theme={null}224```json .claude/settings.json theme={null}

222{225{

271 274

272The `additionalDirectories` setting in `.claude/settings.json` gives Claude access to directories outside the working directory. The example below grants access to two sibling packages:275The `additionalDirectories` setting in `.claude/settings.json` gives Claude access to directories outside the working directory. The example below grants access to two sibling packages:

273 276

274```json .claude/settings.json theme={null}277```json packages/api/.claude/settings.json theme={null}

275{278{

276 "permissions": {279 "permissions": {

277 "additionalDirectories": [280 "additionalDirectories": [

memory.md +12 −8

Details

66 66

67### Set up a project CLAUDE.md67### Set up a project CLAUDE.md

68 68

69A project CLAUDE.md can be stored in either `./CLAUDE.md` or `./.claude/CLAUDE.md`. Create this file and add instructions that apply to anyone working on the project: build and test commands, coding standards, architectural decisions, naming conventions, and common workflows. These instructions are shared with your team through version control, so focus on project-level standards rather than personal preferences.69A project CLAUDE.md can be stored in either `./CLAUDE.md` or `./.claude/CLAUDE.md`. Create this file and add instructions that apply to anyone working on the project: build and test commands, coding standards, architectural decisions, naming conventions, and common workflows. These instructions are shared with your team through version control, so focus on project-level standards rather than personal preferences. To confirm the file loaded, run `/context` in a session and check the list under **Memory files**.

70 70

71<Tip>71<Tip>

72 Run `/init` to generate a starting CLAUDE.md automatically. Claude analyzes your codebase and creates a file with build commands, test instructions, and project conventions it discovers. If a CLAUDE.md already exists, `/init` suggests improvements rather than overwriting it. Refine from there with instructions Claude wouldn't discover on its own.72 Run `/init` to generate a starting CLAUDE.md automatically. Claude analyzes your codebase and creates a file with build commands, test instructions, and project conventions it discovers. If a CLAUDE.md already exists, `/init` suggests improvements rather than overwriting it. Refine from there with instructions Claude wouldn't discover on its own.

107- git workflow @docs/git-instructions.md107- git workflow @docs/git-instructions.md

108```108```

109 109

110For private per-project preferences that shouldn't be checked into version control, create a `CLAUDE.local.md` at the project root. It loads alongside `CLAUDE.md` and is treated the same way. Add `CLAUDE.local.md` to your `.gitignore` so it isn't committed; running `/init` and choosing the personal option does this for you.110For private per-project preferences that shouldn't be checked into version control, create a `CLAUDE.local.md` at the project root. It loads alongside `CLAUDE.md` and is treated the same way. Add `CLAUDE.local.md` to your `.gitignore` so it isn't committed. With `CLAUDE_CODE_NEW_INIT=1` set, running `/init` and choosing the personal option does this for you.

111 111

112If you work across multiple git worktrees of the same repository, a gitignored `CLAUDE.local.md` only exists in the worktree where you created it. To share personal instructions across worktrees, import a file from your home directory instead:112If you work across multiple git worktrees of the same repository, a gitignored `CLAUDE.local.md` only exists in the worktree where you created it. To share personal instructions across worktrees, import a file from your home directory instead:

113 113

117```117```

118 118

119<Warning>119<Warning>

120 The first time Claude Code encounters external imports in a project, it shows an approval dialog listing the files. If you decline, the imports stay disabled and the dialog does not appear again.120 An import in a project-level memory file is external when its path resolves outside your working directory, like the home directory import above. The first time Claude Code encounters external imports in a project, it shows an approval dialog listing the files. If you decline, the imports stay disabled and the dialog doesn't appear again.

121

122 The dialog protects you from files other people commit to a shared project. Imports in user-scope memory files, such as `~/.claude/CLAUDE.md` and `~/.claude/rules/`, are files you wrote yourself, so they load without the dialog and carry the same trust as the rest of your personal configuration.

121</Warning>123</Warning>

122 124

123For a more structured approach to organizing instructions, see [`.claude/rules/`](#organize-rules-with-claude/rules/).125For a more structured approach to organizing instructions, see [`.claude/rules/`](#organize-rules-with-claude/rules/).

140ln -s AGENTS.md CLAUDE.md142ln -s AGENTS.md CLAUDE.md

141```143```

142 144

145The command prints no output on success. In your next session, run `/context` and confirm `CLAUDE.md` appears under **Memory files**.

146

143On Windows, creating a symlink requires Administrator privileges or Developer Mode, so use the `@AGENTS.md` import instead.147On Windows, creating a symlink requires Administrator privileges or Developer Mode, so use the `@AGENTS.md` import instead.

144 148

145Running [`/init`](/en/commands) in a repo that already has an `AGENTS.md` reads it and incorporates the relevant parts into the generated `CLAUDE.md`. It also reads other tool configs like `.cursorrules`, `.devin/rules/`, and `.windsurfrules`.149Running [`/init`](/en/commands) reads Cursor rules, in `.cursor/rules/` or `.cursorrules`, and Copilot rules, in `.github/copilot-instructions.md`, and incorporates the relevant parts into the generated `CLAUDE.md`. With `CLAUDE_CODE_NEW_INIT=1` set, `/init` also reads `AGENTS.md`, `.devin/rules/`, `.windsurf/rules/` or `.windsurfrules`, and `.clinerules`.

146 150

147### How CLAUDE.md files load151### How CLAUDE.md files load

148 152

333 337

334### Enable or disable auto memory338### Enable or disable auto memory

335 339

336Auto memory is on by default. To toggle it, open `/memory` in a session and use the auto memory toggle, or set `autoMemoryEnabled` in your project settings:340Auto memory is on by default. To toggle it, open `/memory` in a session and use the auto memory toggle, which saves `autoMemoryEnabled` to your user settings at `~/.claude/settings.json`. To turn it off for a single project, set `autoMemoryEnabled` in that project's settings:

337 341

338```json theme={null}342```json theme={null}

339{343{

385 389

386The main conversation's auto memory isn't loaded into [subagents](/en/sub-agents#what-loads-at-startup); the exception is a [fork](/en/sub-agents#fork-the-current-conversation), which inherits the parent conversation and system prompt. A subagent's own auto memory, enabled with the subagent `memory` field, is a separate directory.390The main conversation's auto memory isn't loaded into [subagents](/en/sub-agents#what-loads-at-startup); the exception is a [fork](/en/sub-agents#fork-the-current-conversation), which inherits the parent conversation and system prompt. A subagent's own auto memory, enabled with the subagent `memory` field, is a separate directory.

387 391

388Claude reads and writes memory files during your session. When you see "Writing memory" or "Recalled memory" in the Claude Code interface, Claude is actively updating or reading from `~/.claude/projects/<project>/memory/`.392Claude reads and writes memory files during your session. When you see messages like "Saved 2 memories" or "Recalled 2 memories" in the Claude Code interface, Claude is actively updating or reading from `~/.claude/projects/<project>/memory/`.

389 393

390### Audit and edit your memory394### Audit and edit your memory

391 395

393 397

394## View and edit with `/memory`398## View and edit with `/memory`

395 399

396The `/memory` command lists your CLAUDE.md, CLAUDE.local.md, and other memory file locations across user and project scopes, lets you toggle auto memory on or off, and provides an option to open the auto memory folder. Select any file to open it in your editor. To check which files actually loaded into the current session, run `/context`.400The `/memory` command lists your CLAUDE.md, CLAUDE.local.md, and other memory file locations across user and project scopes, including user and project CLAUDE.md entries for files that don't exist yet. It also lets you toggle auto memory on or off and provides an option to open the auto memory folder. Select any file to open it in your editor; selecting one that doesn't exist yet creates it first. To check which files actually loaded into the current session, run `/context`.

397 401

398When you ask Claude to remember something, like "always use pnpm, not npm" or "remember that the API tests require a local Redis instance," Claude saves it to auto memory. To add instructions to CLAUDE.md instead, ask Claude directly, like "add this to CLAUDE.md," or edit the file yourself via `/memory`.402When you ask Claude to remember something, like "always use pnpm, not npm" or "remember that the API tests require a local Redis instance," Claude saves it to auto memory. To add instructions to CLAUDE.md instead, ask Claude directly, like "add this to CLAUDE.md," or edit the file yourself via `/memory`.

399 403

407 411

408To debug:412To debug:

409 413

410* Run `/context` to verify your CLAUDE.md and CLAUDE.local.md files loaded. If a file is missing from the breakdown, Claude can't see it. Use `/memory` to open and edit the files.414* Run `/context` and check the list under **Memory files** to verify your CLAUDE.md and CLAUDE.local.md files loaded. If a file is missing there, Claude can't see it. Use `/memory` to open and edit the files.

411* Check that the relevant CLAUDE.md is in a location that gets loaded for your session (see [Choose where to put CLAUDE.md files](#choose-where-to-put-claude-md-files)).415* Check that the relevant CLAUDE.md is in a location that gets loaded for your session (see [Choose where to put CLAUDE.md files](#choose-where-to-put-claude-md-files)).

412* Make instructions more specific. "Use 2-space indentation" works better than "format code nicely."416* Make instructions more specific. "Use 2-space indentation" works better than "format code nicely."

413* Look for conflicting instructions across CLAUDE.md files. If two files give different guidance for the same behavior, Claude may pick one arbitrarily.417* Look for conflicting instructions across CLAUDE.md files. If two files give different guidance for the same behavior, Claude may pick one arbitrarily.

monitoring-usage.md +4 −2

Details

1191 1191

1192All metrics and events are exported with the following resource attributes:1192All metrics and events are exported with the following resource attributes:

1193 1193

1194* `service.name`: `claude-code`1194* `service.name`: `claude-code` for terminal sessions, `claude-code-desktop` for sessions started from the Code tab in the [Claude Desktop app](/en/desktop)

1195* `service.version`: Current Claude Code version1195* `service.version`: Current Claude Code version, or the Desktop app version for Code tab sessions

1196* `os.type`: Operating system type (for example, `linux`, `darwin`, `windows`)1196* `os.type`: Operating system type (for example, `linux`, `darwin`, `windows`)

1197* `os.version`: Operating system version string1197* `os.version`: Operating system version string

1198* `host.arch`: Host architecture (for example, `amd64`, `arm64`)1198* `host.arch`: Host architecture (for example, `amd64`, `arm64`)

1199* `wsl.version`: WSL version number (only present when running on Windows Subsystem for Linux)1199* `wsl.version`: WSL version number (only present when running on Windows Subsystem for Linux)

1200* Meter Name: `com.anthropic.claude_code`1200* Meter Name: `com.anthropic.claude_code`

1201 1201

1202If your collector pipelines or dashboards filter on `service.name = claude-code`, add `claude-code-desktop` to the filter to also capture telemetry from Code tab sessions.

1203

1202## ROI measurement resources1204## ROI measurement resources

1203 1205

1204For a comprehensive guide on measuring return on investment for Claude Code, including telemetry setup, cost analysis, productivity metrics, and automated reporting, see the [Claude Code ROI Measurement Guide](https://github.com/anthropics/claude-code-monitoring-guide). This repository provides ready-to-use Docker Compose configurations, Prometheus and OpenTelemetry setups, and templates for generating productivity reports integrated with tools like Linear.1206For a comprehensive guide on measuring return on investment for Claude Code, including telemetry setup, cost analysis, productivity metrics, and automated reporting, see the [Claude Code ROI Measurement Guide](https://github.com/anthropics/claude-code-monitoring-guide). This repository provides ready-to-use Docker Compose configurations, Prometheus and OpenTelemetry setups, and templates for generating productivity reports integrated with tools like Linear.

network-config.md +12 −8

Details

136Claude Code requires access to the following URLs. Allowlist these in your proxy configuration and firewall rules, especially in containerized or restricted network environments.136Claude Code requires access to the following URLs. Allowlist these in your proxy configuration and firewall rules, especially in containerized or restricted network environments.

137 137

138| URL | Required for |138| URL | Required for |

139| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |139| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

142| `platform.claude.com` | Anthropic Console account authentication |142| `claude.com` | claude.ai account sign-in opens a `claude.com` page in the browser, which redirects to `claude.ai`; pre-approved WebFetch documentation lookups also reach this host from the CLI |

143| `platform.claude.com` | Anthropic Console account authentication. OAuth token exchange, refresh, and revocation also go to this host for claude.ai accounts, so both Console and claude.ai sign-ins require it |

143| `mcp-proxy.anthropic.com` | [MCP connectors from claude.ai](/en/mcp#use-mcp-servers-from-claude-ai), including connectors an organization administrator configures. Connector traffic routes through this proxy; connectors are enabled by default for claude.ai-authenticated users. To disable, set [`ENABLE_CLAUDEAI_MCP_SERVERS=false`](/en/env-vars) or the [`disableClaudeAiConnectors`](/en/settings#available-settings) setting |144| `mcp-proxy.anthropic.com` | [MCP connectors from claude.ai](/en/mcp#use-mcp-servers-from-claude-ai), including connectors an organization administrator configures. Connector traffic routes through this proxy; connectors are enabled by default for claude.ai-authenticated users. To disable, set [`ENABLE_CLAUDEAI_MCP_SERVERS=false`](/en/env-vars) or the [`disableClaudeAiConnectors`](/en/settings#available-settings) setting |

145| `storage.googleapis.com` | Install counts and plugin metadata shown in `/plugin`. Signed [artifact](/en/artifacts) uploads try this host first; publishing falls back to `api.anthropic.com` when it is blocked |146| `storage.googleapis.com` | Install counts and plugin metadata shown in `/plugin`. Signed [artifact](/en/artifacts) uploads try this host first; publishing falls back to `api.anthropic.com` when it is blocked |

146| `storage.googleapis.com` | {/* max-version: 2.1.115 */}Native installer and native auto-updater on versions prior to 2.1.116 |147| `storage.googleapis.com` | {/* max-version: 2.1.115 */}Native installer and native auto-updater on versions prior to 2.1.116 |

148| `*.claudeusercontent.com` | Viewing [artifacts](/en/artifacts) on claude.ai. The viewer loads each artifact's content from a sandboxed subdomain of this origin. Required in the viewer's browser, not by the CLI itself |

149| `raw.githubusercontent.com` | Changelog feed for [`/release-notes`](/en/commands) and the release notes shown after updating |149| `raw.githubusercontent.com` | Changelog feed for [`/release-notes`](/en/commands) and the release notes shown after updating |

150| `http-intake.logs.us5.datadoghq.com` | Operational telemetry events, sent only when the CLI uses the Anthropic API directly, never for Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry. Optional: disable with [`DISABLE_TELEMETRY`](/en/data-usage#telemetry-services) or `DO_NOT_TRACK` |

151| `browser-intake-us5-datadoghq.com` | Operational error reports, sent when the CLI uses the Anthropic API directly and a server-side rollout gate enables them. Optional: disable with `DISABLE_ERROR_REPORTING` or `DISABLE_TELEMETRY`; see [Telemetry services](/en/data-usage#telemetry-services) |

152| `formulae.brew.sh` | Update version checks on Homebrew installs. Other install methods don't contact this host |

153| `code.claude.com` | Claude Code documentation lookups by the built-in claude-code-guide agent and pre-approved WebFetch requests. Blocking this host only affects documentation lookups |

150 154

151If you install Claude Code through npm or manage your own binary distribution, end users do not need the native installer and auto-updater uses of `downloads.claude.ai`. The other uses in the table apply regardless of install method.155If you install Claude Code through npm or manage your own binary distribution, end users don't need the native installer and auto-updater uses of `downloads.claude.ai`, but npm and bun installs need their package registry, `registry.npmjs.org`, unless your organization mirrors it. The other uses in the table apply regardless of install method.

152 156

153Claude Code also sends optional operational telemetry by default, which you can disable with environment variables. See [Telemetry services](/en/data-usage#telemetry-services) for how to disable it before finalizing your allowlist.157The two Datadog intake hosts carry only optional operational telemetry, and setting [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/en/env-vars) disables both. Sessions on third-party providers never send to these hosts, even when a platform sets [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/en/env-vars) and telemetry metrics default on. See [Telemetry services](/en/data-usage#telemetry-services) for everything Claude Code sends and how to disable it before finalizing your allowlist.

154 158

155When using [Amazon Bedrock](/en/amazon-bedrock), [Google Cloud's Agent Platform](/en/google-vertex-ai), [Microsoft Foundry](/en/microsoft-foundry), or a signed-in [Claude apps gateway](/en/claude-apps-gateway) session, model traffic and authentication go to your provider or gateway instead of `api.anthropic.com`, `claude.ai`, or `platform.claude.com`. The WebFetch tool still calls `api.anthropic.com` for its [domain safety check](/en/data-usage#webfetch-domain-safety-check) unless you set `skipWebFetchPreflight: true` in [settings](/en/settings).159When using [Amazon Bedrock](/en/amazon-bedrock), [Google Cloud's Agent Platform](/en/google-vertex-ai), [Microsoft Foundry](/en/microsoft-foundry), or a signed-in [Claude apps gateway](/en/claude-apps-gateway) session, model traffic and authentication go to your provider or gateway instead of `api.anthropic.com`, `claude.ai`, or `platform.claude.com`. The WebFetch tool still calls `api.anthropic.com` for its [domain safety check](/en/data-usage#webfetch-domain-safety-check) unless you set `skipWebFetchPreflight: true` in [settings](/en/settings).

156 160

162 166

163### Desktop and claude.ai167### Desktop and claude.ai

164 168

165The preceding table primarily covers the standalone CLI. The Claude Desktop app and claude.ai in a browser load their application code from additional Anthropic CDN hosts, including `assets-proxy.anthropic.com`. Allowing `claude.ai` while blocking those hosts produces a blank page rather than an error. See [network access requirements](/en/desktop#network-access-requirements) on the Desktop page.169The preceding table covers the standalone CLI. The Claude Desktop app and claude.ai in a browser load their application code and user content from additional Anthropic CDN hosts, including `assets-proxy.anthropic.com` and the `*.claudeusercontent.com` origins that serve [artifacts](/en/artifacts). Allowing `claude.ai` while blocking those hosts produces a blank page rather than an error. See [network access requirements](/en/desktop#network-access-requirements) on the Desktop page.

166 170

167## Additional resources171## Additional resources

168 172

permissions.md +6 −2

Details

181 181

182When you approve a compound command with "Yes, don't ask again", Claude Code saves a separate rule for each subcommand that requires approval, rather than a single rule for the full compound string. For example, approving `git status && npm test` saves a rule for `npm test`, so future `npm test` invocations are recognized regardless of what precedes the `&&`. Subcommands like `cd` into a subdirectory generate their own Read rule for that path. Up to 5 rules may be saved for a single compound command.182When you approve a compound command with "Yes, don't ask again", Claude Code saves a separate rule for each subcommand that requires approval, rather than a single rule for the full compound string. For example, approving `git status && npm test` saves a rule for `npm test`, so future `npm test` invocations are recognized regardless of what precedes the `&&`. Subcommands like `cd` into a subdirectory generate their own Read rule for that path. Up to 5 rules may be saved for a single compound command.

183 183

184#### Process wrappers184<h4 id="process-wrappers">

185 Wrappers

186</h4>

185 187

186Before matching Bash rules, Claude Code strips a fixed set of process wrappers so a rule like `Bash(npm test *)` also matches `timeout 30 npm test`. The recognized wrappers are `timeout`, `time`, `nice`, `nohup`, and `stdbuf`.188Before matching Bash rules, Claude Code strips a fixed set of wrappers, so a rule like `Bash(npm test *)` also matches `timeout 30 npm test`. The stripped wrappers are `timeout`, `time`, `nice`, `nohup`, and `stdbuf`, plus the shell builtins `command` and `builtin`, and zsh's `noglob`. Each runs its argument as the actual command. Two related forms aren't stripped: the query form `command -v`, which looks up a command rather than running one, and zsh's `nocorrect`.

189

190Claude Code also strips a leading assignment of certain known-safe environment variables, so `Bash(npm test *)` matches `NODE_ENV=test npm test`. An allow rule won't match past an assignment of any other variable. A deny or ask rule matches past any leading assignment, so `Bash(rm *)` in deny still matches `FOO=bar rm -rf tmp/`.

187 191

188Bare `xargs` is also stripped, so `Bash(grep *)` matches `xargs grep pattern`. Stripping applies only when `xargs` has no flags: an invocation like `xargs -n1 grep pattern` is matched as an `xargs` command, so rules written for the inner command do not cover it.192Bare `xargs` is also stripped, so `Bash(grep *)` matches `xargs grep pattern`. Stripping applies only when `xargs` has no flags: an invocation like `xargs -n1 grep pattern` is matched as an `xargs` command, so rules written for the inner command do not cover it.

189 193

plugins-reference.md +2 −2

Details

688}688}

689```689```

690 690

691`${CLAUDE_PLUGIN_ROOT}` changes when the plugin updates. The previous version's directory remains on disk for about seven days after an update before cleanup, but treat it as ephemeral and don't write state there.691`${CLAUDE_PLUGIN_ROOT}` changes when the plugin updates. The previous version's directory remains on disk for about two weeks after an update before cleanup, but treat it as ephemeral and don't write state there.

692 692

693When a plugin updates mid-session, hook commands, monitors, MCP servers, and LSP servers keep using the previous version's path. Run `/reload-plugins` to switch hooks, MCP servers, and LSP servers to the new path; monitors require a session restart.693When a plugin updates mid-session, hook commands, monitors, MCP servers, and LSP servers keep using the previous version's path. Run `/reload-plugins` to switch hooks, MCP servers, and LSP servers to the new path; monitors require a session restart.

694 694

750 750

751For security and verification purposes, Claude Code copies *marketplace* plugins to the user's local **plugin cache** (`~/.claude/plugins/cache`) rather than using them in-place. Understanding this behavior is important when developing plugins that reference external files.751For security and verification purposes, Claude Code copies *marketplace* plugins to the user's local **plugin cache** (`~/.claude/plugins/cache`) rather than using them in-place. Understanding this behavior is important when developing plugins that reference external files.

752 752

753Each installed version is a separate directory in the cache. When you update or uninstall a plugin, the previous version directory is marked as orphaned and removed automatically 7 days later. The grace period lets concurrent Claude Code sessions that already loaded the old version keep running without errors.753Each installed version is a separate directory in the cache. When you update or uninstall a plugin, the previous version directory is marked as orphaned and removed automatically 14 days later. The grace period lets concurrent Claude Code sessions that already loaded the old version keep running without errors.

754 754

755Claude's Glob and Grep tools skip orphaned version directories during searches, so file results don't include outdated plugin code.755Claude's Glob and Grep tools skip orphaned version directories during searches, so file results don't include outdated plugin code.

756 756

security-guidance.md +3 −3

Details

15## Prerequisites15## Prerequisites

16 16

17* Claude Code CLI version 2.1.144 or later17* Claude Code CLI version 2.1.144 or later

~~18* Python 3.8 or later on your `PATH`. The plugin tries `python3`, `python`, and `py -3` in that order~~18* Python 3.7 or later on your `PATH`. The agentic commit review needs Python 3.10 or later, as do all model-backed reviews when Claude Code uses a third-party provider such as Amazon Bedrock or Google Cloud's Agent Platform. The plugin prefers the versioned interpreters `python3.13` through `python3.10`, then falls back to `python3`, `python`, and `py -3`

19* A git repository for the directory you work in. The end-of-turn and commit reviews diff against git state and skip silently outside a repository. The per-edit pattern check works anywhere19* A git repository for the directory you work in. The end-of-turn and commit reviews diff against git state and skip silently outside a repository. The per-edit pattern check works anywhere

20 20

21On first run the plugin creates a virtual environment under `~/.claude/security/` and installs the Claude Agent SDK into it, which requires `pip` and network access. If that install fails, the commit review falls back to a single-shot review instead of the agentic one. On Windows the virtual environment step is skipped, so the agentic commit review runs only if `claude-agent-sdk` is already importable and otherwise falls back the same way.21On first run the plugin creates a virtual environment under `~/.claude/security/` and installs the Claude Agent SDK into it, which requires `pip` and network access. If that install fails, or the available Python is older than 3.10, the commit review on first-party authentication falls back to a single-shot review instead of the agentic one; on a third-party provider such as Amazon Bedrock or Google Cloud's Agent Platform the model-backed reviews need the SDK themselves, so they skip. The plugin shows a one-time notice when an older Python is the cause.

22 22

23## Install the plugin23## Install the plugin

24 24

232Common reasons a review layer skips without a message in the conversation:232Common reasons a review layer skips without a message in the conversation:

233 233

234* The directory is not a git repository: the end-of-turn and commit reviews require git state and skip outside a repository234* The directory is not a git repository: the end-of-turn and commit reviews require git state and skip outside a repository

235* The session has no Anthropic authentication: the model-backed reviews skip and only the per-edit pattern check runs235* The session has no Anthropic authentication and no third-party provider configured: the model-backed reviews skip and only the per-edit pattern check runs

236* A `security-patterns.yaml` file is present but PyYAML is not importable: the file is ignored. Use `security-patterns.json` instead236* A `security-patterns.yaml` file is present but PyYAML is not importable: the file is ignored. Use `security-patterns.json` instead

237 237

238## Related resources238## Related resources

skills.md +17 −1

Details

289| `${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. |289| `${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. |

290| `${CLAUDE_PROJECT_DIR}` | The project root directory. This is the same path [hooks](/en/hooks#reference-scripts-by-path) and MCP servers receive as `CLAUDE_PROJECT_DIR`. Use this to reference project-local scripts or files, such as `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`, independent of where the skill is installed. |290| `${CLAUDE_PROJECT_DIR}` | The project root directory. This is the same path [hooks](/en/hooks#reference-scripts-by-path) and MCP servers receive as `CLAUDE_PROJECT_DIR`. Use this to reference project-local scripts or files, such as `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`, independent of where the skill is installed. |

291 291

292The `${CLAUDE_PROJECT_DIR}` substitution requires Claude Code v2.1.196 or later. It applies to both the skill body and the [`allowed-tools`](#frontmatter-reference) frontmatter, so a permission rule like `Bash(${CLAUDE_PROJECT_DIR}/scripts/lint.sh *)` resolves to the same path the skill body uses.292Claude Code substitutes `${CLAUDE_SKILL_DIR}` and `${CLAUDE_PROJECT_DIR}` in two places: the skill's markdown content, and Bash rules in the [`allowed-tools`](#frontmatter-reference) frontmatter. Using the same variable in both places lets a skill run a bundled script without a permission prompt. The following skill shows the pattern:

293

294```yaml theme={null}

295---

296name: render-chart

297description: Render a chart from a CSV file

298allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)

299---

300

301Run `${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` to render the chart.

302```

303

304If this skill is installed at `~/.claude/skills/render-chart/`, both occurrences of `${CLAUDE_SKILL_DIR}` expand to that directory. The `allowed-tools` rule then matches the exact command the skill body tells Claude to run, so the script runs without prompting.

305

306The `allowed-tools` substitution for `${CLAUDE_SKILL_DIR}` requires Claude Code v2.1.129 or later. On earlier versions the rule stays a literal `${CLAUDE_SKILL_DIR}` string and never matches, so the command still prompts for permission.

307

308The `${CLAUDE_PROJECT_DIR}` substitution requires Claude Code v2.1.196 or later.

293 309

294Indexed arguments use shell-style quoting, so wrap multi-word values in quotes to pass them as a single argument. For example, `/my-skill "hello world" second` makes `$0` expand to `hello world` and `$1` to `second`. The `$ARGUMENTS` placeholder always expands to the full argument string as typed.310Indexed arguments use shell-style quoting, so wrap multi-word values in quotes to pass them as a single argument. For example, `/my-skill "hello world" second` makes `$0` expand to `hello world` and `$1` to `second`. The `$ARGUMENTS` placeholder always expands to the full argument string as typed.

295 311

troubleshoot-install.md +13 −0

Details

34| PowerShell installer completes but `claude` is not found or shows an old version | [Add the install directory to your PATH](#verify-your-path), then open a new terminal |34| PowerShell installer completes but `claude` is not found or shows an old version | [Add the install directory to your PATH](#verify-your-path), then open a new terminal |

35| `dyld: cannot load`, `dyld: Symbol not found`, or `Abort trap` on macOS | [Binary incompatibility](#dyld-cannot-load-on-macos) |35| `dyld: cannot load`, `dyld: Symbol not found`, or `Abort trap` on macOS | [Binary incompatibility](#dyld-cannot-load-on-macos) |

36| `claude update` hangs after `Checking for updates`, or `claude doctor` hangs with no output | [Move the directory at a shell config path](#claude-update-or-claude-doctor-hangs) |

36| `Invoke-Expression: Missing argument in parameter list` | [Install script returns HTML](#install-script-returns-html-instead-of-a-shell-script) |37| `Invoke-Expression: Missing argument in parameter list` | [Install script returns HTML](#install-script-returns-html-instead-of-a-shell-script) |

37| `App unavailable in region` | Claude Code is not available in your country. See [supported countries](https://www.anthropic.com/supported-countries). |38| `App unavailable in region` | Claude Code is not available in your country. See [supported countries](https://www.anthropic.com/supported-countries). |

576 docker build --memory=4g .577 docker build --memory=4g .

577 ```578 ```

578 579

580### `claude update` or `claude doctor` hangs

581

582`claude update` and `claude doctor` scan your shell configuration files for an outdated `claude` alias: `~/.zshrc`, `~/.bashrc`, and `~/.config/fish/config.fish`, plus on macOS the first of `~/.bash_profile`, `~/.bash_login`, or `~/.profile` that exists. If you set `ZDOTDIR`, the Zsh file is `$ZDOTDIR/.zshrc` instead. {/* min-version: 2.1.214 */}When one of those paths is a directory, Claude Code skips it and both commands complete normally. Before v2.1.214, a directory at one of those paths made both commands hang and left the System diagnostics section of `/status` blank. `claude doctor` hung with no output; `claude update` hung right after printing `Checking for updates`.

583

584If you hit the hang on an earlier version, find the directory. In this command's output, a line starting with `d` marks that path as a directory. A `No such file or directory` line means nothing exists at that path and isn't the cause:

585

586```bash theme={null}

587ls -ld ~/.zshrc ~/.bashrc ~/.bash_profile ~/.bash_login ~/.profile ~/.config/fish/config.fish

588```

589

590Move the directory aside, or update to v2.1.214 or later. Since `claude update` hangs on the affected versions, update by rerunning the [install script](/en/setup#install-claude-code) instead.

591

579### Claude Desktop overrides the `claude` command on Windows592### Claude Desktop overrides the `claude` command on Windows

580 593

581If you installed an older version of Claude Desktop, it may register a `Claude.exe` in the `WindowsApps` directory that takes PATH priority over Claude Code CLI. Running `claude` opens the Desktop app instead of the CLI.594If you installed an older version of Claude Desktop, it may register a `Claude.exe` in the `WindowsApps` directory that takes PATH priority over Claude Code CLI. Running `claude` opens the Desktop app instead of the CLI.

ultrareview.md +3 −1

Details

30 30

31Without arguments, ultrareview reviews the diff between your current branch and the default branch, including any uncommitted and staged changes in your working tree. Claude Code bundles the repository state and uploads it to a remote sandbox for the review. To compare against a different base, such as on a repository whose integration branch is `develop` or `trunk`, pass the branch name instead: `/code-review ultra develop`. {/* min-version: 2.1.212 */}A base branch that exists only on `origin` is fetched, and a name with a typo gets a closest-branch suggestion. Both behaviors require Claude Code v2.1.212 or later.31Without arguments, ultrareview reviews the diff between your current branch and the default branch, including any uncommitted and staged changes in your working tree. Claude Code bundles the repository state and uploads it to a remote sandbox for the review. To compare against a different base, such as on a repository whose integration branch is `develop` or `trunk`, pass the branch name instead: `/code-review ultra develop`. {/* min-version: 2.1.212 */}A base branch that exists only on `origin` is fetched, and a name with a typo gets a closest-branch suggestion. Both behaviors require Claude Code v2.1.212 or later.

32 32

33If your branch shares no merge base with the base branch, for example when the two histories are unrelated, Claude Code offers to review every tracked file in the repository instead. The whole-repository fallback requires a full clone and applies the same size limits as a branch review. Before v2.1.214, `/code-review ultra` refused to run without a merge base.

33To review a GitHub pull request instead, pass the PR number.35To review a GitHub pull request instead, pass the PR number.

34 36

35```text theme={null}37```text theme={null}

87claude ultrareview origin/main89claude ultrareview origin/main

88```90```

89 91

90Without arguments, the subcommand reviews the diff between your current branch and the default branch. Pass a PR number to review a pull request, or pass a base branch to review the diff against that branch instead. Invoking the subcommand counts as consent for the billing and terms prompt that the interactive command shows.92Without arguments, the subcommand reviews the diff between your current branch and the default branch, with the same [whole-repository fallback](#run-ultrareview-from-the-cli) as `/code-review ultra` when no merge base exists. Pass a PR number to review a pull request, or pass a base branch to review the diff against that branch instead. Invoking the subcommand counts as consent for the whole-repository fallback and for the billing and terms prompt that the interactive command shows, so the run starts without waiting for input.

91 93

92If the base branch you pass exists on `origin` but not in your local clone, Claude Code fetches it and continues. If the name matches no branch, the error message suggests the closest branch name. Before v2.1.212, both cases failed with a not-a-branch error.94If the base branch you pass exists on `origin` but not in your local clone, Claude Code fetches it and continues. If the name matches no branch, the error message suggests the closest branch name. Before v2.1.212, both cases failed with a not-a-branch error.

93 95

Documentation 2026-07-18 16:02 UTC to 2026-07-20 23:01 UTC