Documentation 2026-07-31 22:02 UTC to 2026-08-02 19:00 UTC

159 159 

160* **`allowed_tools` / `allowedTools`** auto-approves listed tools. A read-only agent with `["Read", "Glob", "Grep"]` in its allowed tools list runs those tools without prompting. Tools not listed are still available but require permission.160* **`allowed_tools` / `allowedTools`** auto-approves listed tools. A read-only agent with `["Read", "Glob", "Grep"]` in its allowed tools list runs those tools without prompting. Tools not listed are still available but require permission.

161* **`disallowed_tools` / `disallowedTools`** blocks listed tools, regardless of other settings. See [Permissions](/docs/en/agent-sdk/permissions) for the order that rules are checked before a tool runs.161* **`disallowed_tools` / `disallowedTools`** blocks listed tools, regardless of other settings. See [Permissions](/docs/en/agent-sdk/permissions) for the order that rules are checked before a tool runs.

162* **`permission_mode` / `permissionMode`** controls what happens to tools that aren't covered by allow or deny rules. See [Permission mode](#permission-mode) for available modes.162* **`permission_mode` / `permissionMode`** controls how much human oversight you want. The SDK evaluates the active mode together with your allow and deny rules in a fixed order, described in [How permissions are evaluated](/docs/en/agent-sdk/permissions#how-permissions-are-evaluated). See [Permission mode](#permission-mode) for available modes.

163 163 

164You can also scope individual tools with rules like `"Bash(npm *)"` to allow only specific commands. See [Permissions](/docs/en/agent-sdk/permissions) for the full rule syntax.164You can also scope individual tools with rules like `"Bash(npm *)"` to allow only specific commands. See [Permissions](/docs/en/agent-sdk/permissions) for the full rule syntax.

165 165 

359 from typing import Any359 from typing import Any

360 from claude_agent_sdk import tool360 from claude_agent_sdk import tool

361 361 

362 from claude_agent_sdk import tool

363 

364 362 

365 @tool(363 @tool(

366 "fetch_data",364 "fetch_data",

470 import httpx468 import httpx

471 from claude_agent_sdk import tool469 from claude_agent_sdk import tool

472 470 

473 from claude_agent_sdk import tool

474 

475 471 

476 # Define a tool that fetches an image from a URL and returns it to Claude472 # Define a tool that fetches an image from a URL and returns it to Claude

477 @tool("fetch_image", "Fetch an image from a URL and return it to Claude", {"url": str})473 @tool("fetch_image", "Fetch an image from a URL and return it to Claude", {"url": str})

13## What's Changed13## What's Changed

14 14 

15| Aspect | Old | New |15| Aspect | Old | New |

16| :------------------------- | :-------------------------- | :------------------------------- |16| :------------------------- | :-------------------------- | :----------------------------------------------------------------------- |

17| **Package Name (TS/JS)** | `@anthropic-ai/claude-code` | `@anthropic-ai/claude-agent-sdk` |17| **Package Name (TS/JS)** | `@anthropic-ai/claude-code` | `@anthropic-ai/claude-agent-sdk` |

18| **Python Package** | `claude-code-sdk` | `claude-agent-sdk` |18| **Python Package** | `claude-code-sdk` | `claude-agent-sdk` |

19| **Documentation Location** | Claude Code docs | API Guide → Agent SDK section |19| **Documentation Location** | Claude Code docs | Claude Code docs → dedicated [Agent SDK](/docs/en/agent-sdk/overview) section |

20 

21<Note>

22 **Documentation Changes:** The Agent SDK documentation has moved from the Claude Code docs to the API Guide under a dedicated [Agent SDK](/en/agent-sdk/overview) section. The Claude Code docs now focus on the CLI tool and automation features.

23</Note>

24 20 

25## Migration Steps21## Migration Steps

26 22 

274Isolation is especially important for CI/CD pipelines, deployed applications, test environments, and multi-tenant systems where local customizations should not leak in.270Isolation is especially important for CI/CD pipelines, deployed applications, test environments, and multi-tenant systems where local customizations should not leak in.

275 271 

276<Note>272<Note>

277 SDK v0.1.0 briefly defaulted to no settings loaded; this was reverted in subsequent releases. Python SDK 0.1.59 and earlier treated an empty list the same as omitting the option, so upgrade before relying on `setting_sources=[]`. See [What settingSources does not control](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) for inputs that are read even when `settingSources` is `[]`.273 SDK v0.1.0 briefly defaulted to no settings loaded; this was reverted in subsequent releases. Python SDK 0.1.59 and earlier treated an empty list the same as omitting the option, so upgrade before relying on `setting_sources=[]`. See [What settingSources does not control](/docs/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) for inputs that are read even when `settingSources` is `[]`.

278</Note>274</Note>

279 275 

280## Why the Rename?276## Why the Rename?

303 299 

304## Next Steps300## Next Steps

305 301 

306* Explore the [Agent SDK Overview](/en/agent-sdk/overview) to learn about available features302* Explore the [Agent SDK Overview](/docs/en/agent-sdk/overview) to learn about available features

307* Check out the [TypeScript SDK Reference](/en/agent-sdk/typescript) for detailed API documentation303* Check out the [TypeScript SDK Reference](/docs/en/agent-sdk/typescript) for detailed API documentation

308* Review the [Python SDK Reference](/en/agent-sdk/python) for Python-specific documentation304* Review the [Python SDK Reference](/docs/en/agent-sdk/python) for Python-specific documentation

309* Learn about [Custom Tools](/en/agent-sdk/custom-tools) and [MCP Integration](/en/agent-sdk/mcp)305* Learn about [Custom Tools](/docs/en/agent-sdk/custom-tools) and [MCP Integration](/docs/en/agent-sdk/mcp)

349| `Read`, `Edit`, `Glob` | Analyze and modify code |349| `Read`, `Edit`, `Glob` | Analyze and modify code |

350| `Read`, `Edit`, `Bash`, `Glob`, `Grep` | Full automation |350| `Read`, `Edit`, `Bash`, `Glob`, `Grep` | Full automation |

351 351 

352**Permission modes** control how much human oversight you want: the mode decides what happens when the agent calls a tool that isn't already pre-approved by your allow rules. For the full list of modes, their behavior, and when to use each, see [Permission mode in How the agent loop works](/docs/en/agent-sdk/agent-loop#permission-mode).352**Permission modes** control how much human oversight you want. The SDK evaluates the active mode together with your allow and deny rules in a fixed order, described in [How permissions are evaluated](/docs/en/agent-sdk/permissions#how-permissions-are-evaluated). For the full list of modes, their behavior, and when to use each, see [Permission mode in How the agent loop works](/docs/en/agent-sdk/agent-loop#permission-mode).

353 353 

354## Next steps354## Next steps

355 355 

10 10 

11The Claude Agent SDK supports two distinct input modes for interacting with agents:11The Claude Agent SDK supports two distinct input modes for interacting with agents:

12 12 

13* **Streaming Input Mode** (Default & Recommended) - A persistent, interactive session13* **Streaming Input Mode**: a persistent, interactive session

14* **Single Message Input** - One-shot queries that use session state and resuming14* **Single Message Input**: one-shot queries that use session state and resuming

15 15 

16This guide explains the differences, benefits, and use cases for each mode to help you choose the right approach for your application.16This guide explains the differences, benefits, and use cases for each mode to help you choose the right approach for your application.

17 17 

210 ```210 ```

211</CodeGroup>211</CodeGroup>

212 212 

213When you run the example, the TypeScript version prints each response as it completes. The Python version's `receive_response()` loop ends at the first result message, so it prints the security analysis; to read both responses, use one `query()` and `receive_response()` pair per message as shown in the [Python reference's example of continuing a conversation](/en/agent-sdk/python#example-continuing-a-conversation).213When you run the example, the TypeScript version prints each response as it completes. The Python version's `receive_response()` loop ends at the first result message, so it prints the security analysis; to read both responses, use one `query()` and `receive_response()` pair per message as shown in the [Python reference's example of continuing a conversation](/docs/en/agent-sdk/python#example-continuing-a-conversation).

214 214 

215<Note>215<Note>

216 In the TypeScript SDK, if your message generator throws, for example when a file it reads is missing, the stream ends with an error that reads `Claude Code process aborted by user` instead of the original error, so check the code inside your generator first when you see that message. The error may also be preceded by a long minified line of bundled SDK source, so read to the end of the output for the error text.216 In the TypeScript SDK, if your message generator throws, for example when a file it reads is missing, the stream ends with an error that reads `Claude Code process aborted by user` instead of the original error, so check the code inside your generator first when you see that message. The error may also be preceded by a long minified line of bundled SDK source, so read to the end of the output for the error text.

241 * Natural multi-turn conversations241 * Natural multi-turn conversations

242</Warning>242</Warning>

243 243 

244If a query ends with an error result, such as `error_max_turns`, a single message `query()` call raises an error that includes the failure text after yielding the final result message, so wrap the loop in a try block if your code needs to continue. See [Handle the result](/en/agent-sdk/agent-loop#handle-the-result) for the result subtypes.244If a query ends with an error result, such as `error_max_turns`, a single message `query()` call raises an error that includes the failure text after yielding the final result message, so wrap the loop in a try block if your code needs to continue. See [Handle the result](/docs/en/agent-sdk/agent-loop#handle-the-result) for the result subtypes.

245 245 

246### Implementation Example246### Implementation Example

247 247 

340 340 

341A side chat lets you ask Claude a question that uses your session's context but doesn't add anything back to the main conversation. Use it when you want to understand a piece of code, check an assumption, or explore an idea without steering the session off course.341A side chat lets you ask Claude a question that uses your session's context but doesn't add anything back to the main conversation. Use it when you want to understand a piece of code, check an assumption, or explore an idea without steering the session off course.

342 342 

343Press **Cmd+;** on macOS or **Ctrl+;** on Windows to open a side chat, or type `/btw` in the prompt box. The side chat can read everything in the main thread up to that point. When you're done, close the side chat and continue the main session where you left off. Side chats are available in local, SSH, and WSL sessions.343Press **Cmd+;** on macOS or **Ctrl+;** on Windows to open a side chat, or type `/btw` in the prompt box. The side chat can read everything in the main thread up to that point. When you're done, close the side chat and continue the main session where you left off.

344 

345Side chats are available in local, SSH, and WSL sessions. The desktop app doesn't save side chats to disk, so you can't return to one after you close the app.

344 346 

345### Watch background tasks347### Watch background tasks

346 348 

28 28 

29## Official Anthropic marketplace29## Official Anthropic marketplace

30 30 

31Claude Code adds the official Anthropic marketplace (`claude-plugins-official`) automatically when you start it. If Claude Code can't add it, for example because your network blocks the download, add it yourself with `/plugin marketplace add anthropics/claude-plugins-official`.31Claude Code adds the official Anthropic marketplace (`claude-plugins-official`) automatically the first time you start it interactively. If Claude Code can't add it, for example because your network blocks the download or a [marketplace policy](/docs/en/plugin-marketplaces#managed-marketplace-restrictions) blocked an earlier attempt, add it yourself with `/plugin marketplace add anthropics/claude-plugins-official`.

32 32 

33To browse what's available, run `/plugin` and go to the **Discover** tab, or view the catalog at [claude.com/plugins](https://claude.com/plugins).33To browse what's available, run `/plugin` and go to the **Discover** tab, or view the catalog at [claude.com/plugins](https://claude.com/plugins).

34 34 

237| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Set to any non-empty value, such as `1`, to disable nonessential network traffic: auto-updates, telemetry, error reporting, the `/feedback` command, release notes, [gateway model discovery](/docs/en/llm-gateway-connect#add-gateway-models-to-the-model-picker) refreshes, and availability checks such as the [fast mode](/docs/en/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) check. **Setting it to `0` or `false` still disables this traffic**, unlike most on/off variables; unset the variable to allow it again. Also disables feature-flag fetching, which makes [Remote Control](/docs/en/remote-control#requirements) unavailable. Official plugin marketplace auto-install isn't covered; disable it with `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` |237| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Set to any non-empty value, such as `1`, to disable nonessential network traffic: auto-updates, telemetry, error reporting, the `/feedback` command, release notes, [gateway model discovery](/docs/en/llm-gateway-connect#add-gateway-models-to-the-model-picker) refreshes, and availability checks such as the [fast mode](/docs/en/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) check. **Setting it to `0` or `false` still disables this traffic**, unlike most on/off variables; unset the variable to allow it again. Also disables feature-flag fetching, which makes [Remote Control](/docs/en/remote-control#requirements) unavailable. Official plugin marketplace auto-install isn't covered; disable it with `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` |

238| `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK` | Set to `1` to disable the non-streaming fallback when a streaming request fails mid-stream. Streaming errors propagate to the retry layer instead. Useful when a proxy or gateway causes the fallback to produce duplicate tool execution |238| `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK` | Set to `1` to disable the non-streaming fallback when a streaming request fails mid-stream. Streaming errors propagate to the retry layer instead. Useful when a proxy or gateway causes the fallback to produce duplicate tool execution |

239| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | {/* min-version: 2.1.193 */}Set to `1` to send the `PushNotification` tool's desktop notification even while you are typing in or focused on the terminal. By default the tool skips both the desktop notification and the [mobile push](/docs/en/remote-control#mobile-push-notifications) when it detects recent keyboard activity or terminal focus. This variable disables only that local check, so the server can still suppress the mobile push when it detects that you are active. Requires Claude Code v2.1.193 or later |239| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | {/* min-version: 2.1.193 */}Set to `1` to send the `PushNotification` tool's desktop notification even while you are typing in or focused on the terminal. By default the tool skips both the desktop notification and the [mobile push](/docs/en/remote-control#mobile-push-notifications) when it detects recent keyboard activity or terminal focus. This variable disables only that local check, so the server can still suppress the mobile push when it detects that you are active. Requires Claude Code v2.1.193 or later |

240| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | Set to `1` to skip automatic addition of the official plugin marketplace on first run |240| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | Set to `1` to disable automatic registration of the official plugin marketplace. Claude Code reads the variable when it is about to register the marketplace, usually during a machine's first interactive launch. If the variable is set at that point, Claude Code skips the registration permanently. Unsetting the variable later doesn't undo the skip. Run `claude plugin marketplace add anthropics/claude-plugins-official` to register the marketplace at any time |

241| `CLAUDE_CODE_DISABLE_POLICY_SKILLS` | Set to `1` to skip loading skills from the system-wide managed skills directory. Useful for container or CI sessions that should not load operator-provisioned skills |241| `CLAUDE_CODE_DISABLE_POLICY_SKILLS` | Set to `1` to skip loading skills from the system-wide managed skills directory. Useful for container or CI sessions that should not load operator-provisioned skills |

242| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates based on conversation context. In Agent SDK and `claude -p` sessions, this also skips the background small/fast-model request that generates the session title |242| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates based on conversation context. In Agent SDK and `claude -p` sessions, this also skips the background small/fast-model request that generates the session title |

243| `CLAUDE_CODE_DISABLE_THINKING` | Set to `1` to omit the `thinking` parameter from API requests entirely. This is a compatibility option for proxies and gateways that reject the parameter. The variable's behavior is unchanged from earlier versions; on models that think by default, omitting the parameter means the model may still think. To explicitly disable [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) on the Anthropic API, use `MAX_THINKING_TOKENS=0` instead, which is also ineffective on Fable 5 since it cannot have thinking turned off. On [third-party providers](/docs/en/third-party-integrations), `0` likewise omits the parameter, so the two variables behave the same there |243| `CLAUDE_CODE_DISABLE_THINKING` | Set to `1` to omit the `thinking` parameter from API requests entirely. This is a compatibility option for proxies and gateways that reject the parameter. The variable's behavior is unchanged from earlier versions; on models that think by default, omitting the parameter means the model may still think. To explicitly disable [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) on the Anthropic API, use `MAX_THINKING_TOKENS=0` instead, which is also ineffective on Fable 5 since it cannot have thinking turned off. On [third-party providers](/docs/en/third-party-integrations), `0` likewise omits the parameter, so the two variables behave the same there |

7> Enable a smoother, flicker-free rendering mode with mouse support and stable memory usage in long conversations.7> Enable a smoother, flicker-free rendering mode with mouse support and stable memory usage in long conversations.

8 8 

9<Note>9<Note>

10 Fullscreen rendering is an opt-in [research preview](#research-preview). Run `/tui fullscreen` to switch in your current conversation. Behavior may change based on feedback.10 Fullscreen rendering is a [research preview](#research-preview). If you first used Claude Code on or after May 6, 2026, Claude Code renders fullscreen by default; run `/tui default` to switch back. If you started earlier, you keep the classic renderer; run `/tui fullscreen` to switch in your current conversation. Behavior may change based on feedback.

11</Note>11</Note>

12 12 

13Fullscreen rendering is an alternative rendering path for the Claude Code CLI that eliminates flicker, keeps memory usage flat in long conversations, and adds mouse support. It draws the interface on the terminal's alternate screen buffer, like `vim` or `htop`, and only renders messages that are currently visible. This reduces the amount of data sent to your terminal on each update.13Fullscreen rendering is an alternative rendering path for the Claude Code CLI that eliminates flicker, keeps memory usage flat in long conversations, and adds mouse support. It draws the interface on the terminal's alternate screen buffer, like `vim` or `htop`, and only renders messages that are currently visible. This reduces the amount of data sent to your terminal on each update.

30claude -p "What does the auth module do?"30claude -p "What does the auth module do?"

31```31```

32 32 

33Claude Code exits with code 0 on success and a non-zero code when the run fails, so your scripts can branch on the exit status. If you pass an invalid flag, Claude Code reports the error to stderr before the run starts. When a failure happens inside the run, such as missing authentication, Claude Code prints the failure as the result on stdout.

34 

33### Start faster with bare mode35### Start faster with bare mode

34 36 

35Add `--bare` to reduce startup time by skipping auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md. Without it, `claude -p` loads the same [context](/docs/en/how-claude-code-works#the-context-window) an interactive session would, including anything configured in the working directory or `~/.claude`.37Add `--bare` to reduce startup time by skipping auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md. Without it, `claude -p` loads the same [context](/docs/en/how-claude-code-works#the-context-window) an interactive session would, including anything configured in the working directory or `~/.claude`.

36 38 

37Bare mode is useful for CI and scripts where you need the same result on every machine. A hook in a teammate's `~/.claude` or an MCP server in the project's `.mcp.json` won't run, because bare mode never reads them. Only flags you pass explicitly take effect.39Bare mode is useful for CI and scripts where you need the same result on every machine. A hook in a teammate's `~/.claude` or an MCP server in the project's `.mcp.json` won't run, because bare mode never reads them. Only flags you pass explicitly take effect.

38 40 

39This example runs a one-off summarize task in bare mode and pre-approves the Read tool so the call completes without a permission prompt:41This example runs a one-off summarize task in bare mode and pre-approves the Read tool so the call completes without a permission prompt. Set `ANTHROPIC_API_KEY` before running it, because bare mode doesn't use your subscription login:

40 42 

41```bash theme={null}43```bash theme={null}

42claude --bare -p "Summarize this file" --allowedTools "Read"44claude --bare -p "Summarize README.md" --allowedTools "Read"

43```45```

44 46 

47Bare mode skips OAuth and the system keychain, so Claude Code only sees credentials you pass explicitly. For the Anthropic API, set `ANTHROPIC_API_KEY` in the environment, with a key created in the [Claude Console](https://platform.claude.com), or supply an `apiKeyHelper` in the `--settings` JSON. Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry continue to read their own provider credentials as usual.

48 

45In bare mode Claude has access to the Bash, file read, and file edit tools. Pass any context you need with a flag:49In bare mode Claude has access to the Bash, file read, and file edit tools. Pass any context you need with a flag:

46 50 

47| To load | Use |51| To load | Use |

52| Custom agents | `--agents <json>` |56| Custom agents | `--agents <json>` |

53| A plugin | `--plugin-dir <path>`, `--plugin-url <url>` |57| A plugin | `--plugin-dir <path>`, `--plugin-url <url>` |

54 58 

55Bare mode skips OAuth and keychain reads. For Anthropic authentication, set `ANTHROPIC_API_KEY` or configure an `apiKeyHelper` in the JSON you pass to `--settings`. Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry use their usual provider credentials.

56 

57<Note>59<Note>

58 `--bare` is the recommended mode for scripted and SDK calls, and will become the default for `-p` in a future release.60 `--bare` is the recommended mode for scripted and SDK calls, and will become the default for `-p` in a future release.

59</Note>61</Note>

68 70 

69## Examples71## Examples

70 72 

71These examples highlight common CLI patterns. For CI and other scripted calls, add [`--bare`](#start-faster-with-bare-mode) so they don't pick up whatever happens to be configured locally.73These examples highlight common CLI patterns. Where a command names a file such as `auth.py` or `build-error.txt`, substitute a file from your own project. In CI or other scripted environments, add [`--bare`](#start-faster-with-bare-mode) so Claude Code ignores any local configuration on the host.

72 74 

73### Pipe data through Claude75### Pipe data through Claude

74 76 

102}104}

103```105```

104 106 

107Run it with `npm run lint:claude`.

108 

105### Get structured output109### Get structured output

106 110 

107Use `--output-format` to control how responses are returned:111Use `--output-format` to control how responses are returned:

263 267 

264### Customize the system prompt268### Customize the system prompt

265 269 

266Use `--append-system-prompt` to add instructions while keeping Claude Code's default behavior. This example pipes a PR diff to Claude and instructs it to review for security vulnerabilities:270Use `--append-system-prompt` to add instructions while keeping Claude Code's default behavior. This example pipes a PR diff to Claude and instructs it to review for security vulnerabilities. Save it as a shell script, for example `review.sh`:

267 271 

268```bash theme={null}272```bash theme={null}

269gh pr diff "$1" | claude -p \273gh pr diff "$1" | claude -p \

271 --output-format json275 --output-format json

272```276```

273 277 

278In the script, `"$1"` stands for the first argument you pass on the command line. Run `bash review.sh 123` and the shell replaces `"$1"` with `123`, so the script fetches the diff for PR 123. Claude Code prints the review as JSON, with the text in the `result` field.

279 

274See [system prompt flags](/docs/en/cli-reference#system-prompt-flags) for more options including `--system-prompt` to fully replace the default prompt.280See [system prompt flags](/docs/en/cli-reference#system-prompt-flags) for more options including `--system-prompt` to fully replace the default prompt.

275 281 

276### Continue conversations282### Continue conversations

24 24 

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

26 <Frame>26 <Frame>

27 <img src="https://mintcdn.com/claude-code/uLsR38F1U_5zPppm/images/hooks-lifecycle.svg?fit=max&auto=format&n=uLsR38F1U_5zPppm&q=85&s=fbdbd78ad9f474da7d344879341341f0" className="dark:hidden" alt="Hook lifecycle diagram showing optional Setup feeding into SessionStart, then a per-turn loop containing UserPromptSubmit, UserPromptExpansion for slash commands, the nested agentic loop (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, PostToolBatch, 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, WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged, and FileChanged as standalone async events, and MessageDisplay as a display-only event that runs while assistant message text streams" width="520" height="1228" data-path="images/hooks-lifecycle.svg" />27 <img src="https://mintcdn.com/claude-code/jhXrDR5TrSZ5hgXM/images/hooks-lifecycle.svg?fit=max&auto=format&n=jhXrDR5TrSZ5hgXM&q=85&s=3ca47113d5956460e6e4611b8dbc63b7" className="dark:hidden" alt="Hook lifecycle diagram showing optional Setup feeding into SessionStart, then a per-turn loop containing UserPromptSubmit, UserPromptExpansion for slash commands, the nested agentic loop (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, PostToolBatch, 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, WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged, FileChanged, and DirectoryAdded as standalone async events, and MessageDisplay as a display-only event that runs while assistant message text streams" width="520" height="1228" data-path="images/hooks-lifecycle.svg" />

28 28 

29 <img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/hooks-lifecycle-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=1499b14a84a22ccff55daddf870d6c3c" className="hidden dark:block" alt="Hook lifecycle diagram showing optional Setup feeding into SessionStart, then a per-turn loop containing UserPromptSubmit, UserPromptExpansion for slash commands, the nested agentic loop (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, PostToolBatch, 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, WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged, and FileChanged as standalone async events, and MessageDisplay as a display-only event that runs while assistant message text streams" width="520" height="1228" data-path="images/hooks-lifecycle-dark.svg" />29 <img src="https://mintcdn.com/claude-code/jhXrDR5TrSZ5hgXM/images/hooks-lifecycle-dark.svg?fit=max&auto=format&n=jhXrDR5TrSZ5hgXM&q=85&s=0ffe95014d33411538778a66e4173973" className="hidden dark:block" alt="Hook lifecycle diagram showing optional Setup feeding into SessionStart, then a per-turn loop containing UserPromptSubmit, UserPromptExpansion for slash commands, the nested agentic loop (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, PostToolBatch, 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, WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged, FileChanged, and DirectoryAdded as standalone async events, and MessageDisplay as a display-only event that runs while assistant message text streams" width="520" height="1228" data-path="images/hooks-lifecycle-dark.svg" />

30 </Frame>30 </Frame>

31</div>31</div>

32 32 

56| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |56| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |

57| `ConfigChange` | When a configuration file changes during a session |57| `ConfigChange` | When a configuration file changes during a session |

58| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |58| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |

59| `DirectoryAdded` | When a working directory is added mid-session via `/add-dir` or the SDK `register_repo_root` control request |

59| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |60| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |

60| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |61| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |

61| `WorktreeRemove` | When a worktree is being removed at session exit, when a subagent finishes, or when you delete a background session |62| `WorktreeRemove` | When a worktree is being removed at session exit, when a subagent finishes, or when you delete a background session |

235| `SubagentStop` | agent type | same values as `SubagentStart` |236| `SubagentStop` | agent type | same values as `SubagentStart` |

236| `ConfigChange` | configuration source | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` |237| `ConfigChange` | configuration source | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` |

237| `CwdChanged` | no matcher support | always fires on every directory change |238| `CwdChanged` | no matcher support | always fires on every directory change |

239| `DirectoryAdded` | how the directory was added | `slash_command`, `register_repo_root` |

238| `FileChanged` | literal filenames to watch (see [FileChanged](#filechanged)) | `.envrc\|.env` |240| `FileChanged` | literal filenames to watch (see [FileChanged](#filechanged)) | `.envrc\|.env` |

239| `StopFailure` | error type | `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `unknown` |241| `StopFailure` | error type | `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `unknown` |

240| `InstructionsLoaded` | load reason | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` |242| `InstructionsLoaded` | load reason | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` |

726| `Setup` | No | Shows stderr to user only |728| `Setup` | No | Shows stderr to user only |

727| `SessionEnd` | No | Shows stderr to user only |729| `SessionEnd` | No | Shows stderr to user only |

728| `CwdChanged` | No | Shows stderr to user only |730| `CwdChanged` | No | Shows stderr to user only |

731| `DirectoryAdded` | No | Stderr goes to the debug log; the directory is already added |

729| `FileChanged` | No | Shows stderr to user only |732| `FileChanged` | No | Shows stderr to user only |

730| `PreCompact` | Yes | Blocks compaction |733| `PreCompact` | Yes | Blocks compaction |

731| `PostCompact` | No | Shows stderr to user only |734| `PostCompact` | No | Shows stderr to user only |

872| ElicitationResult | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (form field values override) |875| ElicitationResult | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (form field values override) |

873| MessageDisplay | `hookSpecificOutput` | `displayContent` replaces the displayed text on screen. Display-only: the transcript and what Claude sees keep the original |876| MessageDisplay | `hookSpecificOutput` | `displayContent` replaces the displayed text on screen. Display-only: the transcript and what Claude sees keep the original |

874| SessionStart, Setup, SubagentStart | Context only | `hookSpecificOutput.additionalContext` adds context for Claude. SessionStart also accepts [`initialUserMessage`, `watchPaths`, `sessionTitle`, and `reloadSkills`](#sessionstart-decision-control). No blocking or decision control |877| SessionStart, Setup, SubagentStart | Context only | `hookSpecificOutput.additionalContext` adds context for Claude. SessionStart also accepts [`initialUserMessage`, `watchPaths`, `sessionTitle`, and `reloadSkills`](#sessionstart-decision-control). No blocking or decision control |

875| WorktreeRemove, Notification, SessionEnd, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, FileChanged | None | No decision control. Used for side effects like logging or cleanup |878| WorktreeRemove, Notification, SessionEnd, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, DirectoryAdded, FileChanged | None | No decision control. Used for side effects like logging or cleanup |

876 879 

877A few events can also rewrite content rather than only allow or block it:880A few events can also rewrite content rather than only allow or block it:

878 881 

2456 2459 

2457CwdChanged hooks have no decision control. They can't block the directory change.2460CwdChanged hooks have no decision control. They can't block the directory change.

2458 2461 

2462### DirectoryAdded

2463 

2464Runs after a working directory is added mid-session, with the `/add-dir` command or the SDK `register_repo_root` control request. Use this to prepare a newly added repository, for example by installing its dependencies. Claude Code doesn't fire this event for directories you pass with the `--add-dir` startup flag; [SessionStart](#sessionstart) covers those.

2465 

2466DirectoryAdded fires after Claude Code has refreshed sandbox and permission state, so sandboxed tools already see the new directory when your hook runs. Hook commands themselves run unsandboxed.

2467 

2468The matcher filters on how the directory was added:

2469 

2470| Matcher | When it fires |

2471| :------------------- | :--------------------------------------------------------------------------- |

2472| `slash_command` | You add a directory with `/add-dir` |

2473| `register_repo_root` | An SDK client adds a directory with the `register_repo_root` control request |

2474 

2475#### DirectoryAdded input

2476 

2477In addition to the [common input fields](#common-input-fields), DirectoryAdded hooks receive `directory` and `source`.

2478 

2479| Field | Description |

2480| :---------- | :------------------------------------------------------------------------------------------------------------------ |

2481| `directory` | Absolute path of the directory that was added |

2482| `source` | How the directory was added, `"slash_command"` for `/add-dir` or `"register_repo_root"` for the SDK control request |

2483 

2484```json theme={null}

2485{

2486 "session_id": "abc123",

2487 "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",

2488 "cwd": "/Users/my-project",

2489 "hook_event_name": "DirectoryAdded",

2490 "directory": "/Users/my-other-repo",

2491 "source": "slash_command"

2492}

2493```

2494 

2495DirectoryAdded hooks have no decision control. They can't block the add, which has already completed when the hook runs. Claude Code surfaces hook output differently per source:

2496 

2497* `slash_command`: unlike on every other event, where you see the `systemMessage` and Claude doesn't, Claude Code delivers the hook's `systemMessage` to Claude as context on the next conversation turn. A count of failed hooks appears in the transcript; full failure output goes to the debug log

2498* `register_repo_root`: Claude Code writes `systemMessage` output and failure output to the debug log only

2499 

2459### FileChanged2500### FileChanged

2460 2501 

2461Runs when a watched file changes on disk. Useful for reloading environment variables when project configuration files are modified.2502Runs when a watched file changes on disk. Useful for reloading environment variables when project configuration files are modified.

2836 2877 

2837* `ConfigChange`2878* `ConfigChange`

2838* `CwdChanged`2879* `CwdChanged`

2880* `DirectoryAdded`

2839* `Elicitation`2881* `Elicitation`

2840* `ElicitationResult`2882* `ElicitationResult`

2841* `FileChanged`2883* `FileChanged`

470| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |470| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |

471| `ConfigChange` | When a configuration file changes during a session |471| `ConfigChange` | When a configuration file changes during a session |

472| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |472| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |

473| `DirectoryAdded` | When a working directory is added mid-session via `/add-dir` or the SDK `register_repo_root` control request |

473| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |474| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |

474| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |475| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |

475| `WorktreeRemove` | When a worktree is being removed at session exit, when a subagent finishes, or when you delete a background session |476| `WorktreeRemove` | When a worktree is being removed at session exit, when a subagent finishes, or when you delete a background session |

524 525 

525#### Hook input526#### Hook input

526 527 

527Every event includes common fields like `session_id` and `cwd`, but each event type adds different data. For example, when Claude runs a Bash command, a `PreToolUse` hook receives something like this on stdin:528Every event includes common fields like `session_id`, a unique ID for the session, and `cwd`, the working directory when the event fired, but each event type adds different data. When Claude runs a Bash command, a `PreToolUse` hook receives these fields on stdin:

529 

530* `hook_event_name`: the event that triggered the hook

531* `tool_name`: the tool Claude is about to use

532* `tool_input`: the arguments Claude passed to the tool. For Bash, its `command` field holds the shell command.

533 

534For example, the hook input for an `npm test` command looks like this:

528 535 

529```json theme={null}536```json theme={null}

530{537{

531 "session_id": "abc123", // unique ID for this session538 "session_id": "abc123",

532 "cwd": "/Users/sarah/myproject", // working directory when the event fired539 "cwd": "/Users/sarah/myproject",

533 "hook_event_name": "PreToolUse", // which event triggered this hook540 "hook_event_name": "PreToolUse",

534 "tool_name": "Bash", // the tool Claude is about to use541 "tool_name": "Bash",

535 "tool_input": { // the arguments Claude passed to the tool542 "tool_input": {

536 "command": "npm test" // for Bash, this is the shell command543 "command": "npm test"

537 }544 }

538}545}

539```546```

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

99| `?` | Toggle the keyboard shortcut help panel. Requires [fullscreen rendering](/docs/en/fullscreen) |99| `?` | Toggle the keyboard shortcut help panel. Requires [fullscreen rendering](/docs/en/fullscreen) |

100| `{` / `}` | Jump to the previous or next user prompt, like vim paragraph motion. Requires [fullscreen rendering](/docs/en/fullscreen) |100| `{` / `}` | Jump to the previous or next user prompt, like vim paragraph motion. Requires [fullscreen rendering](/docs/en/fullscreen) |

101| `Ctrl+E` | Toggle show all content. Available in the default renderer only, not in [fullscreen rendering](/docs/en/fullscreen) |101| `Ctrl+E` | Toggle show all content. Available in the classic renderer only, not in [fullscreen rendering](/docs/en/fullscreen) |

102| `[` | Write the full conversation to your terminal's native scrollback so `Cmd+F`, tmux copy mode, and other native tools can search it. Requires [fullscreen rendering](/docs/en/fullscreen#search-and-review-the-conversation) |102| `[` | Write the full conversation to your terminal's native scrollback so `Cmd+F`, tmux copy mode, and other native tools can search it. Requires [fullscreen rendering](/docs/en/fullscreen#search-and-review-the-conversation) |

103| `v` | Write the conversation to a temporary file and open it in `$VISUAL` or `$EDITOR`. Requires [fullscreen rendering](/docs/en/fullscreen) |103| `v` | Write the conversation to a temporary file and open it in `$VISUAL` or `$EDITOR`. Requires [fullscreen rendering](/docs/en/fullscreen) |

104| `q`, `Ctrl+C`, `Esc` | Exit transcript view. All three can be rebound via [`transcript:exit`](/docs/en/keybindings) |104| `q`, `Ctrl+C`, `Esc` | Exit transcript view. All three can be rebound via [`transcript:exit`](/docs/en/keybindings) |

249 249 

250### Reverse search with Ctrl+R250### Reverse search with Ctrl+R

251 251 

252Press `Ctrl+R` to interactively search through your command history. In [fullscreen rendering](/docs/en/fullscreen), `Ctrl+R` opens a search dialog instead: type to filter, press `Up` and `Down` to move through matches, and press `Ctrl+S` to cycle the scope through this session, this project, and all projects. Press `Enter` or `Tab` to place a match in the prompt input, or `Esc` to cancel. The steps below describe the default inline search:252Press `Ctrl+R` to interactively search through your command history. In [fullscreen rendering](/docs/en/fullscreen), `Ctrl+R` opens a search dialog instead: type to filter, press `Up` and `Down` to move through matches, and press `Ctrl+S` to cycle the scope through this session, this project, and all projects. Press `Enter` or `Tab` to place a match in the prompt input, or `Esc` to cancel. The steps below describe the classic renderer's inline search:

253 253 

2541. **Start search**: press `Ctrl+R` to activate reverse history search2541. **Start search**: press `Ctrl+R` to activate reverse history search

2552. **Type query**: enter text to search for in previous commands. The search term is highlighted in matching results2552. **Type query**: enter text to search for in previous commands. The search term is highlighted in matching results

159| `transcript:toggleShowAll` | Ctrl+E | Toggle show all content |159| `transcript:toggleShowAll` | Ctrl+E | Toggle show all content |

160| `transcript:exit` | q, Ctrl+C, Escape | Exit transcript view |160| `transcript:exit` | q, Ctrl+C, Escape | Exit transcript view |

161 161 

162`transcript:toggleShowAll` applies in the default renderer only; in [fullscreen rendering](/docs/en/fullscreen), the transcript viewer doesn't offer a show-all toggle.162`transcript:toggleShowAll` applies in the classic renderer only; in [fullscreen rendering](/docs/en/fullscreen), the transcript viewer doesn't offer a show-all toggle.

163 163 

164### History search actions164### History search actions

165 165 

173| `historySearch:execute` | Enter | Execute selected command |173| `historySearch:execute` | Enter | Execute selected command |

174| `historySearch:cycleScope` | Ctrl+S | Cycle scope: session, project, everywhere |174| `historySearch:cycleScope` | Ctrl+S | Cycle scope: session, project, everywhere |

175 175 

176The `historySearch:next`, `historySearch:accept`, `historySearch:cancel`, and `historySearch:execute` defaults apply to the inline history search in the default renderer, which always searches prompts from all projects. `historySearch:cycleScope` takes effect only in [fullscreen rendering](/docs/en/fullscreen), where `Ctrl+R` opens a search dialog instead and `Ctrl+S` cycles its scope. The dialog's other keys are fixed and can't be rebound: `Enter` or `Tab` places the highlighted match in the prompt input and `Esc` cancels.176The `historySearch:next`, `historySearch:accept`, `historySearch:cancel`, and `historySearch:execute` defaults apply to the inline history search in the classic renderer, which always searches prompts from all projects. `historySearch:cycleScope` takes effect only in [fullscreen rendering](/docs/en/fullscreen), where `Ctrl+R` opens a search dialog instead and `Ctrl+S` cycles its scope. The dialog's other keys are fixed and can't be rebound: `Enter` or `Tab` places the highlighted match in the prompt input and `Esc` cancels.

177 177 

178### Task actions178### Task actions

179 179 

701}701}

702```702```

703 703 

704With this entry, the official marketplace registers itself automatically the first time you start Claude Code interactively, so you don't need to pair it with `extraKnownMarketplaces`. In a non-interactive environment that runs before that first interactive launch, add it explicitly with `claude plugin marketplace add anthropics/claude-plugins-official` or include it in `extraKnownMarketplaces`.704With this entry, Claude Code keeps an already-registered official marketplace available and, on a fresh machine, registers the marketplace automatically the first time you start Claude Code interactively.

705 

706Automatic registration doesn't cover every machine. It most commonly misses:

707 

708* Non-interactive environments that run before the machine's first interactive launch.

709* Machines where Claude Code already ran interactively under a policy that blocked the marketplace, such as the empty-array lockdown. Claude Code records the blocked attempt and doesn't retry after the policy changes.

710 

711On these machines, add the marketplace to [`extraKnownMarketplaces`](/docs/en/settings#extraknownmarketplaces) in the same `managed-settings.json` so Claude Code registers it automatically, or run `claude plugin marketplace add anthropics/claude-plugins-official`.

705 712 

706Allow specific marketplaces only:713Allow specific marketplaces only:

707 714 

754Use `".*"` as the `pathPattern` to allow any filesystem path while still controlling network sources with `hostPattern`.761Use `".*"` as the `pathPattern` to allow any filesystem path while still controlling network sources with `hostPattern`.

755 762 

756<Note>763<Note>

757 `strictKnownMarketplaces` restricts what users can add, but doesn't register marketplaces on its own. To make allowed marketplaces available automatically without users running `/plugin marketplace add`, pair it with [`extraKnownMarketplaces`](/docs/en/settings#extraknownmarketplaces) in the same `managed-settings.json`. See [Using both together](/docs/en/settings#strictknownmarketplaces).764 `strictKnownMarketplaces` restricts what users can add, but doesn't register marketplaces on its own. To register an allowed marketplace for users automatically, add it to [`extraKnownMarketplaces`](/docs/en/settings#extraknownmarketplaces) in the same `managed-settings.json`.

765 

766 The official Anthropic marketplace is the only one Claude Code registers on its own, and only when the allowlist allows it. Automatic registration also misses some machines, such as non-interactive environments and machines where an earlier policy blocked it. To cover those machines, add the official marketplace to `extraKnownMarketplaces` as well. For the two settings side by side, see the [`strictKnownMarketplaces` reference](/docs/en/settings#strictknownmarketplaces).

758</Note>767</Note>

759 768 

760#### How restrictions work769#### How restrictions work

378 378 

379Anthropic maintains two public marketplaces for Claude Code plugins:379Anthropic maintains two public marketplaces for Claude Code plugins:

380 380 

381* **`claude-plugins-official`**: a curated set of plugins maintained by Anthropic. Registered automatically the first time you start Claude Code interactively. A non-interactive script that runs before that first launch must add it explicitly with `claude plugin marketplace add anthropics/claude-plugins-official`.381* **`claude-plugins-official`**: a curated set of plugins maintained by Anthropic. Claude Code registers it automatically the first time you start Claude Code interactively. If you run Claude Code non-interactively before that first interactive launch, or a [marketplace policy](/docs/en/plugin-marketplaces#managed-marketplace-restrictions) blocked an earlier attempt, register it yourself with `claude plugin marketplace add anthropics/claude-plugins-official`.

382* **`claude-community`**: the public community marketplace where third-party submissions land after review. Users add it with `/plugin marketplace add anthropics/claude-plugins-community` and install from it as `@claude-community`.382* **`claude-community`**: the public community marketplace where third-party submissions land after review. Users add it with `/plugin marketplace add anthropics/claude-plugins-community` and install from it as `@claude-community`.

383 383 

384To submit your plugin for community-marketplace review, use one of the in-app forms:384To submit your plugin for community-marketplace review, use one of the in-app forms:

136| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |136| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |

137| `ConfigChange` | When a configuration file changes during a session |137| `ConfigChange` | When a configuration file changes during a session |

138| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |138| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |

139| `DirectoryAdded` | When a working directory is added mid-session via `/add-dir` or the SDK `register_repo_root` control request |

139| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |140| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |

140| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |141| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |

141| `WorktreeRemove` | When a worktree is being removed at session exit, when a subagent finishes, or when you delete a background session |142| `WorktreeRemove` | When a worktree is being removed at session exit, when a subagent finishes, or when you delete a background session |

382 382 

383### `/schedule` returns "Unknown command"383### `/schedule` returns "Unknown command"

384 384 

385The CLI hides `/schedule` when one of its requirements isn't met: the command menu shows `No commands match "/schedule"` while you type, and submitting it returns `Unknown command: /schedule`. The cause is usually one of the following:385The CLI hides `/schedule` when one of its requirements isn't met: the command menu shows `No commands match "/schedule"` while you type, and submitting it returns `Unknown command: /schedule` in every case below except a Console API key with feature-flag fetching enabled. The cause is usually one of the following:

386 386 

387* You are authenticated with a Console API key or a cloud provider such as Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry. `/schedule` requires a claude.ai subscription login. If `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` is set in your shell, or `apiKeyHelper` is set in `settings.json`, remove it first, since these take precedence over a claude.ai login387* You are authenticated with a Console API key or a cloud provider such as Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry. `/schedule` requires a claude.ai subscription login. With a Console API key, submitting `/schedule` instead shows `/schedule is available with Claude for Enterprise — ask your admin about migrating from API-key access`. With a cloud-provider login, you still see `Unknown command: /schedule`. If `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` is set in your shell, or `apiKeyHelper` is set in `settings.json`, remove it first, since these take precedence over a claude.ai login

388* `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, or `DISABLE_GROWTHBOOK` is set in your shell environment or in the `env` block of a [`settings.json` file](/docs/en/settings#available-settings). These disable feature-flag fetching, which `/schedule` depends on388* `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, or `DISABLE_GROWTHBOOK` is set in your shell environment or in the `env` block of a [`settings.json` file](/docs/en/settings#available-settings). These disable feature-flag fetching, which `/schedule` depends on

389* You are inside a Claude Code on the web session. Manage routines from the [web UI](https://claude.ai/code/routines) instead389* You are inside a Claude Code on the web session. Manage routines from the [web UI](https://claude.ai/code/routines) instead

390 390 

1067}1067}

1068```1068```

1069 1069 

1070With this entry, the official marketplace registers itself automatically the first time you start Claude Code interactively, so you don't need to pair it with `extraKnownMarketplaces`. In a non-interactive environment that runs before that first interactive launch, add it explicitly with `claude plugin marketplace add anthropics/claude-plugins-official` or include it in `extraKnownMarketplaces`.1070With this entry, Claude Code keeps an already-registered official marketplace available and, on a fresh machine, registers the marketplace automatically the first time you start Claude Code interactively.

1071 

1072Automatic registration doesn't cover every machine. It most commonly misses:

1073 

1074* Non-interactive environments that run before the machine's first interactive launch.

1075* Machines where Claude Code already ran interactively under a policy that blocked the marketplace, such as the empty-array lockdown. Claude Code records the blocked attempt and doesn't retry after the policy changes.

1076 

1077On these machines, add the marketplace to [`extraKnownMarketplaces`](#extraknownmarketplaces) in the same `managed-settings.json` so Claude Code registers it automatically, or run `claude plugin marketplace add anthropics/claude-plugins-official`.

1071 1078 

1072Example: allow all marketplaces from an internal git server:1079Example: allow all marketplaces from an internal git server:

1073 1080 

1148}1155}

1149```1156```

1150 1157 

1151With only `strictKnownMarketplaces` set, users can still add the allowed marketplace manually via `/plugin marketplace add`, but it is not available automatically.1158With only `strictKnownMarketplaces` set, users can still add an allowed marketplace manually via `/plugin marketplace add`. The official Anthropic marketplace is the only one Claude Code registers automatically, and only when the allowlist allows it. Automatic registration also misses some machines, most commonly non-interactive environments and machines where an earlier policy blocked the marketplace. To cover those machines, add the official marketplace to [`extraKnownMarketplaces`](#extraknownmarketplaces) too.

1152 1159 

1153**Important notes**:1160**Important notes**:

1154 1161 

73 Claude Code includes additional helper agents for specific tasks. These are typically invoked automatically, so you don't need to use them directly.73 Claude Code includes additional helper agents for specific tasks. These are typically invoked automatically, so you don't need to use them directly.

74 74 

75 | Agent | Model | When Claude uses it |75 | Agent | Model | When Claude uses it |

76 | :---------------- | :----- | :------------------------------------------------------- |76 | :---------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

77 | statusline-setup | Sonnet | When you run `/statusline` to configure your status line |77 | statusline-setup | Sonnet | When you run `/statusline` to configure your status line |

78 | claude-code-guide | Haiku | When you ask questions about Claude Code features |78 | claude-code-guide | Haiku | When you ask questions about Claude Code features |

79 | claude | Inherits | When you dispatch a [background session](/docs/en/agent-view) from `claude agents` or `claude --bg` without naming an agent. Claude can also delegate to it like any other subagent |

79 </Tab>80 </Tab>

80</Tabs>81</Tabs>

81 82 

56 56 

57The installer downloads from `downloads.claude.ai`. Verify you can reach it:57The installer downloads from `downloads.claude.ai`. Verify you can reach it:

58 58 

59```bash theme={null}59<Tabs>

60curl -sI https://downloads.claude.ai/claude-code-releases/latest60 <Tab title="macOS/Linux">

61```61 ```bash theme={null}

62 curl -sI https://downloads.claude.ai/claude-code-releases/latest

63 ```

64 </Tab>

62 65 

63In PowerShell, run `curl.exe -sI` instead. PowerShell aliases `curl` to `Invoke-WebRequest`, which rejects the `-sI` flags.66 <Tab title="Windows PowerShell">

67 ```powershell theme={null}

68 curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest

69 ```

70 

71 PowerShell aliases `curl` to `Invoke-WebRequest`, which rejects the `-sI` flags, so call `curl.exe` explicitly.

72 </Tab>

73</Tabs>

64 74 

65An `HTTP/2 200` line means you reached the server. Other results point to the cause:75You reached the server if the first line shows a `200` status. You see `HTTP/2 200` on macOS and Linux, and `HTTP/1.1 200 OK` from the `curl.exe` included with Windows. Other results point to the cause:

66 76 

67* `403`: usually a proxy or network filter blocking the host, or Claude Code is [not available in your region](https://www.anthropic.com/supported-countries)77* `403`: usually a proxy or network filter blocking the host, or Claude Code is [not available in your region](https://www.anthropic.com/supported-countries)

68* `5xx`: usually a temporary service issue; wait a few minutes and retry78* `5xx`: usually a temporary service issue; wait a few minutes and retry