claude-code-20261007T073702Z / documentation capture

agent-sdk/hooks Changed · +4 / -4 lines

from line 134

134134 ```

135135</CodeGroup>

136136

137When you run either script, Claude attempts to create the `.env` file, the hook denies the tool call, and Claude's final response explains that it can't create `.env` files.

137When you run either script, Claude attempts to create the `.env` file and the hook denies the tool call.

138138

139139## Available hooks

140140

from line 171

171171| `ConfigChange` | No | Yes | Configuration file changes | Reload settings dynamically |

172172| `InstructionsLoaded` | No | Yes | A `CLAUDE.md` or rules file is loaded into context | Audit which instruction files load |

173173| `WorktreeCreate` | No | Yes | Git worktree created | Track isolated workspaces |

174| `WorktreeRemove` | No | Yes | Git worktree removed | Clean up workspace resources |

174| `WorktreeRemove` | No | Yes | A worktree created by a `WorktreeCreate` hook is being removed | Clean up workspace resources |

175175| `CwdChanged` | No | Yes | The working directory changes during a session | Reload environment variables per directory |

176176| `FileChanged` | No | Yes | A watched file is modified, created, or deleted | Reload configuration when project files change |

177177| `DirectoryAdded` | No | Yes | A working directory is added during a session | Install dependencies for a repository added mid-session |

from line 244

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

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

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

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

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

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

249249

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

from line 826

826826

827827### Session hooks not available in Python

828828

829`SessionStart` and `SessionEnd` can be registered as SDK callback hooks in TypeScript, but aren't available in the Python SDK because its `HookEvent` type omits them. In Python, they are only available as [shell command hooks](/docs/en/hooks#hook-events) defined in settings files such as `.claude/settings.json`. To load shell command hooks from your SDK application, include the appropriate setting source with [`setting_sources`](/docs/en/agent-sdk/python#settingsource) or [`settingSources`](/docs/en/agent-sdk/typescript#settingsource):

829`SessionStart` and `SessionEnd` can be registered as SDK callback hooks in TypeScript, but aren't available in the Python SDK because its `HookEvent` type omits them. In Python, they are only available as [shell command hooks](/docs/en/hooks#hook-events) defined in settings files such as `.claude/settings.json`. Which settings files your SDK application loads depends on [`setting_sources`](/docs/en/agent-sdk/python#settingsource) or [`settingSources`](/docs/en/agent-sdk/typescript#settingsource). If you set that option, include the source that holds the hooks:

830830

831831<CodeGroup>

832832 ```python Python theme={null}

agent-sdk/python Changed · +7 / -6 lines

from line 164

164164

165165#### `ToolAnnotations`

166166

167Behavioral hints for a tool, passed as the `annotations` argument of [`tool()`](#tool). `ToolAnnotations` extends the MCP SDK's `mcp.types.ToolAnnotations` with a `maxResultSizeChars` field, and you can write each hint in camelCase or snake\_case: `ToolAnnotations(readOnlyHint=True)` and `ToolAnnotations(read_only_hint=True)` are equivalent. You can also pass a plain `mcp.types.ToolAnnotations` wherever the SDK accepts annotations.

167Behavioral hints for a tool, passed as the `annotations` argument of [`tool()`](#tool). `ToolAnnotations` extends the MCP SDK's `mcp.types.ToolAnnotations` with a `maxResultSizeChars` field, and you can write each hint in camelCase or snake\_case: `ToolAnnotations(readOnlyHint=True)` and `ToolAnnotations(read_only_hint=True)` are equivalent. To read a hint back from the object, use the spelling your installed `mcp` package declares: `.readOnlyHint` on `mcp` 1.x and `.read_only_hint` on 2.x, while `.maxResultSizeChars` works on both. You can also pass a plain `mcp.types.ToolAnnotations` wherever the SDK accepts annotations.

168168

169169The snake\_case names and the typed `maxResultSizeChars` field require Python Agent SDK 0.2.140 or later. Versions 0.1.31 through 0.2.139 re-export `mcp.types.ToolAnnotations` unchanged. On versions 0.1.55 through 0.2.139 you can still pass `maxResultSizeChars` as a keyword argument: the MCP class accepts extra fields, and the SDK forwards the value to Claude Code.

170170

from line 1327

13271327| `enabled` | `type`, `budget_tokens`, `display` | Enable thinking with a specific token budget |

13281328| `disabled` | `type` | Disable thinking |

13291329

1330The optional `display` field controls whether thinking text is returned `"summarized"` or `"omitted"`. On Claude Opus 4.7 and later, the API default is `"omitted"`, so set `"summarized"` to receive thinking content in [`ThinkingBlock`](#thinkingblock) outputs. Claude Code doesn't send `display` to Amazon Bedrock or Google Cloud's Agent Platform, so on those providers Opus 4.7 and later return empty `ThinkingBlock` outputs even when you set `display` to `"summarized"`.

1330The optional `display` field controls whether thinking text is returned `"summarized"` or `"omitted"`. On Claude Opus 4.7 and later, the API default is `"omitted"`, so set `"summarized"` to receive thinking content in [`ThinkingBlock`](#thinkingblock) outputs. Claude Code leaves `display` out of requests to some providers, such as Amazon Bedrock and Google Cloud's Agent Platform. On those providers, Opus 4.7 and later return empty `ThinkingBlock` outputs even when you set `display` to `"summarized"`.

13311331

13321332Because these are `TypedDict` classes, they're plain dicts at runtime. Either construct them as dict literals or call the class like a constructor; both produce a `dict`. Access fields with `config["budget_tokens"]`, not `config.budget_tokens`:

13331333

from line 1699

16991699| `maxOutputTokens` | `int` | Maximum output token limit for this model. |

17001700| `canonicalModel` | `str` | Canonical model ID used for the pricing lookup. May differ from the raw model string the entry is keyed by, such as a provider-specific ID or alias. Not always present. |

17011701| `provider` | `str` | API provider that served this model, such as `firstParty`, `bedrock`, `vertex`, `foundry`, `anthropicAws`, `mantle`, or `gateway`. Not always present. |

1702| `costBasis` | `str` | Price table that priced this model's latest request: `list` for list price, `managed` for a [`modelPricing`](/docs/en/settings-reference#modelpricing) table, or `unknown` when neither matched the model ID. Not always present, and not declared on the TypedDict, so read it with `.get()`. Requires Claude Code v2.1.246 or later. |

17021703

17031704### `StreamEvent`

17041705

from line 1959

19581959 """Base error for Claude SDK."""

19591960```

19601961

1961When a single-shot `query()` ends with an error result, for example a turn-limit error, the SDK raises a [`ResultError`](#resulterror) after yielding the final result message. Python Agent SDK versions before 0.2.140 raised a plain `Exception` that wasn't a `ClaudeSDKError` subclass.

1962When a single-shot `query()` ends with an error result, for example a turn-limit error, the SDK raises a [`ResultError`](#resulterror).

19621963

19631964### `CLINotFoundError`

19641965

from line 2001

20002001

20012002### `ResultError`

20022003

2003Raised after the final [`ResultMessage`](#resultmessage) when the Claude Code process exits because the run ended with an error result, such as a turn-limit error or an API error. `ResultError` subclasses `ProcessError`, so an existing `except ProcessError` handler also catches it. Its attributes carry the fields of that result message, so you can branch on why the run failed without parsing the message text. Requires Python Agent SDK 0.2.140 or later.

2004Raised when the Claude Code process exits because the run ended with an error [result message](#resultmessage), such as a turn-limit error or an API error. `ResultError` subclasses `ProcessError`, so an existing `except ProcessError` handler also catches it. Its attributes carry the fields of that result message, so you can branch on why the run failed without parsing the message text. Requires Python Agent SDK 0.2.140 or later.

20042005

20052006```python theme={null}

20062007class ResultError(ProcessError):

from line 2392

23912392 hookEventName: Literal["PostToolUse"]

23922393 additionalContext: NotRequired[str]

23932394 updatedToolOutput: NotRequired[Any]

2394 updatedMCPToolOutput: NotRequired[Any] # Deprecated: use updatedToolOutput, which works for all tools

2395 updatedMCPToolOutput: NotRequired[Any] # MCP tools only. Prefer updatedToolOutput, which works for all tools

23952396

23962397

23972398class PostToolUseFailureHookSpecificOutput(TypedDict):

from line 2504

25032504

25042505## Tool Input/Output Types

25052506

2506Documentation of input/output schemas for all built-in Claude Code tools. While the Python SDK doesn't export these as types, they represent the structure of tool inputs and outputs in messages.

2507Documentation of input/output schemas for built-in Claude Code tools. While the Python SDK doesn't export these as types, they represent the structure of tool inputs and outputs in messages.

25072508

25082509Each output shown is the value you read from [`UserMessage.tool_use_result`](#usermessage) for that tool. Key names appear exactly as Claude Code emits them. A key annotated `| None` with a "present when" or "optional" comment is omitted when it doesn't apply.

25092510

agent-sdk/typescript Changed · +9 / -4 lines

This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.

from line 156

156156 console.error("Claim failed:", error.message);

157157});

158158

159for await (const message of claimedQuery) {

160 console.log(message);

159try {

160 for await (const message of claimedQuery) {

161 console.log(message);

162 }

163} catch (error) {

164 // After a refused claim, the claimed query throws once it has yielded the error result

165 console.error(`Session ended with an error: ${error}`);

161166}

162167```

163168

from line 749

744749

745750`options.cwd` is required. A claim can also set `additionalDirectories`, `model`, `permissionMode`, `maxThinkingTokens`, a flag-settings overlay in `settings`, `appendSystemPrompt`, `title`, `agents`, and per-session tokens in `env`.

746751

747Claude Code can refuse a claim, for example for a folder that doesn't exist or one whose project settings set `env`, `agent`, or `model`. When `claimed` rejects with a message that starts with `option_not_applied`, the session is running without the `model` or `maxThinkingTokens` you asked for. After any other rejection your prompt hasn't run, so start the session with `query()` instead.

752Claude Code can refuse a claim, for example for a folder that doesn't exist or one whose project settings set `env`, `agent`, or `model`. After a refusal, a prompt that `claim()` already sent gets an error result whose text starts with `not_claimed`, and the returned query then throws. Wrap the query's loop in a try block to continue past the throw. When `claimed` rejects with a message that starts with `option_not_applied`, the session is running without the `model` or `maxThinkingTokens` you asked for. After any other rejection your prompt hasn't run, so start the session with `query()` instead.

748753

749754### `SDKControlInitializeResponse`

750755

from line 4974

49694974 | { type: "disabled" }; // No extended thinking

49704975```

49714976

4972The optional `display` field controls whether thinking text is returned `"summarized"` or `"omitted"`. On Claude Opus 4.7 and later, the API default is `"omitted"`, so set `"summarized"` to receive thinking content in `thinking` blocks. Claude Code doesn't send `display` to Amazon Bedrock or Google Cloud's Agent Platform, so on those providers Opus 4.7 and later return empty `thinking` blocks even when you set `display` to `"summarized"`.

4977The optional `display` field controls whether thinking text is returned `"summarized"` or `"omitted"`. On Claude Opus 4.7 and later, the API default is `"omitted"`, so set `"summarized"` to receive thinking content in `thinking` blocks. Claude Code leaves `display` out of requests to some providers, such as Amazon Bedrock and Google Cloud's Agent Platform. On those providers, Opus 4.7 and later return empty `thinking` blocks even when you set `display` to `"summarized"`.

49734978

49744979### `SpawnedProcess`

49754980

from line 5374

53695374

53705375A turn's `idle` message and its `result` message can arrive in either order. To change whether `idle` waits for background work such as a background subagent or a [workflow](/docs/en/workflows) run, see [`CLAUDE_CODE_BG_TASKS_REPORT_RUNNING`](/docs/en/env-vars#variables).

53715376

5372```typescript theme={null}

5373type SDKSessionStateChangedMessage = {

5374 type: "system";

5375 subtype: "session_state_changed";

5376 state: "idle" | "running" | "requires_action";

5377 uuid: UUID;

5378 session_id: string;

5379};

5380```

5381

5382### `SDKFilesPersistedEvent`

5383

5384Emitted when file checkpoints are persisted to disk.

5385

5386```typescript theme={null}

5387type SDKFilesPersistedEvent = {

5388 type: "system";

5389 subtype: "files_persisted";

5390 files: { filename: string; file_id: string }

5377```typescript theme={nu

claude-directory Changed · +3 / -3 lines

from line 30

3030 oneLiner: 'Project instructions Claude reads every session',

3131 when: 'Loaded into context at the start of every session',

3232 description: 'Project-specific instructions that shape how Claude works in this repository. Put your conventions, common commands, and architectural context here so Claude operates with the same assumptions your team does.',

33 tips: ['Target under 200 lines. Longer files still load in full but may reduce adherence', <>CLAUDE.md loads into every session. If something only matters for specific tasks, move it to a <A href="/docs/en/skills">skill</A> or a path-scoped <A href="/docs/en/memory#organize-rules-with-claude/rules/">rule</A> so it loads only when needed</>, 'List the commands you run most, like build, test, and format, so Claude knows them without you spelling them out each time', <>Run <C>/memory</C> to open and edit CLAUDE.md from within a session</>, <>Also works at <C>.claude/CLAUDE.md</C> if you prefer to keep the project root clean</>, <>If your repo already has an <C>AGENTS.md</C> for other coding agents, Claude Code <A href="/docs/en/memory#agents-md">can read that</A> on its own or alongside CLAUDE.md</>],

33 tips: ['Target under 200 lines. Longer files still load in full but may reduce adherence', <>CLAUDE.md loads into every session. If something only matters for specific tasks, move it to a <A href="/docs/en/skills">skill</A> or a path-scoped <A href="/docs/en/memory#organize-rules-with-claude/rules/">rule</A> so it loads only when needed</>, 'List the commands you run most, like build, test, and format, so Claude knows them without you spelling them out each time', <>Run <C>/memory</C> to open and edit CLAUDE.md from within a session</>, <>Also works at <C>.claude/CLAUDE.md</C> if you prefer to keep the project root clean</>, <>If your repo already has an <C>AGENTS.md</C> for other coding agents, Claude Code <A href="/docs/en/memory#agents-md">can read that</A> in place of a <C>CLAUDE.md</C></>],

3434 exampleIntro: 'This example is for a TypeScript and React project. It lists the build and test commands, the framework conventions Claude should follow, and project-specific rules like export style and file layout.',

3535 example: `# Project conventions

3636

from line 1430

14301430

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

14321432

1433Most users only edit `CLAUDE.md` and `settings.json`. If your repository already has an `AGENTS.md` for other coding agents, Claude Code [can read that](/docs/en/memory#agents-md) on its own or alongside `CLAUDE.md`. The rest of the directory is optional: add skills, rules, or subagents as you need them.

1433Most users only edit `CLAUDE.md` and `settings.json`. If your repository already has an `AGENTS.md` for other coding agents, Claude Code [can read that](/docs/en/memory#agents-md) in place of a `CLAUDE.md`. The rest of the directory is optional: add skills, rules, or subagents as you need them.

14341434

14351435## Explore the directory

14361436

from line 1446

14461446| - | - | - |

14471447| `managed-settings.json` | System-level, varies by OS | Enterprise-enforced settings that you can't override, apart from [narrow exceptions](/docs/en/settings#security-keys-where-the-stricter-value-applies). See [where to save the file](/docs/en/managed-settings#deploy-a-managed-settings-file) and [which managed source Claude Code uses](/docs/en/managed-settings#precedence-within-the-managed-tier). |

14481448| `CLAUDE.local.md` | Project root | Your private preferences for this project, loaded alongside CLAUDE.md. Create it manually and add it to `.gitignore`. |

1449| `AGENTS.md` | Project root, `.claude/`, or any directory | Project instructions you write for AI coding agents. Claude Code can [load it](/docs/en/memory#agents-md) on its own or alongside `CLAUDE.md`. |

1449| `AGENTS.md` | Project root, `.claude/`, or any directory | Project instructions you write for AI coding agents. Claude Code can [load it](/docs/en/memory#agents-md) in place of a `CLAUDE.md`. |

14501450| Installed plugins | `~/.claude/plugins` | Cloned marketplaces, installed plugin versions, the `installed_plugins.json` install record, and per-plugin data, managed by `claude plugin` commands. Plugins [synced from your claude.ai account](/docs/en/plugins/loading#synced-plugins) download into `~/.claude/plugins/synced/`. For a plugin installed from a marketplace [`command` source](/docs/en/plugins/marketplace-reference#command-plugin-source) in link mode, Claude Code stores links here instead of a copy, and the plugin's files stay in the directory the command prints. A `command` source requires Claude Code v2.1.229 or later. A plugin listed by relative path in a marketplace you added from a local path also [loads in place](/docs/en/plugins/loading#find-plugins-on-disk) from its source directory rather than from a cache copy. See [plugin caching](/docs/en/plugins/loading#find-plugins-on-disk) for how orphaned versions are cleaned up. |

14511451

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

hooks Changed · +5 / -6 lines

from line 57

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

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

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

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

60| `WorktreeRemove` | When a worktree that a `WorktreeCreate` hook created is being removed |

6161| `PreCompact` | Before context compaction |

6262| `PostCompact` | After context compaction completes |

6363| `PreModelSwitch` | Before Claude Code applies a model switch that you or a client requested. Can block the switch |

from line 3026

30263026

30273027### WorktreeRemove

30283028

3029Runs when a worktree is being removed. This is the cleanup counterpart to [WorktreeCreate](#worktreecreate). The event fires when:

3029Runs when Claude Code cleans up a worktree that your [`WorktreeCreate`](#worktreecreate) hook created. The event fires when:

30303030

3031* you exit a `--worktree` session and choose to remove it

3032* a subagent with `isolation: "worktree"` finishes

3033* you delete a [background session](/docs/en/agent-view#what-deleting-a-session-removes) whose worktree the hook created

3031* You exit a `--worktree` session and choose to remove the worktree

3032* You delete a [background session](/docs/en/agent-view#what-deleting-a-session-removes) that runs in the worktree

30343033

30353034For git-based worktrees, Claude Code handles cleanup automatically with `git worktree remove`. If you configured a WorktreeCreate hook, pair it with a WorktreeRemove hook to control cleanup of the worktrees it creates:

30363035

quickstart Changed · +5 / -5 lines

from line 25

2525 <Tab title="Native Install (Recommended)">

2626 **macOS, Linux, WSL:**

2727

28 ```bash theme={null} theme={null} theme={null} theme={null}

28 ```bash theme={null}

2929 curl -fsSL https://claude.ai/install.sh | bash

3030 ```

3131

3232 **Windows PowerShell:**

3333

34 ```powershell theme={null} theme={null} theme={null} theme={null}

34 ```powershell theme={null}

3535 irm https://claude.ai/install.ps1 | iex

3636 ```

3737

3838 **Windows CMD:**

3939

40 ```batch theme={null} theme={null} theme={null} theme={null}

40 ```batch theme={null}

4141 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

4242 ```

4343

from line 55

5555 </Tab>

5656

5757 <Tab title="Homebrew">

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

58 ```bash theme={null}

5959 brew install --cask claude-code

6060 ```

6161

from line 67

6767 </Tab>

6868

6969 <Tab title="WinGet">

70 ```powershell theme={null} theme={null} theme={null} theme={null}

70 ```powershell theme={null}

7171 winget install Anthropic.ClaudeCode

7272 ```

7373

agent-sdk/structured-outputs Changed · +2 / -2 lines

from line 52

5252

5353To use structured outputs, define a [JSON Schema](https://json-schema.org/understanding-json-schema/about) describing the shape of data you want, then pass it to `query()` via the `outputFormat` option (TypeScript) or `output_format` option (Python). When the agent finishes, the result message includes a `structured_output` field with validated data matching your schema.

5454

55The example below asks the agent to research Anthropic and return the company name, year founded, and headquarters as structured output.

55Before running the examples on this page, install the Claude Agent SDK by following the [quickstart](/docs/en/agent-sdk/quickstart#setup). The example below asks the agent to research Anthropic and return the company name, year founded, and headquarters as structured output.

5656

5757<CodeGroup>

5858 ```typescript TypeScript theme={null}

from line 374

374374

375375## Error handling

376376

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

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

378378

379379When an error occurs, the result message has a `subtype` indicating what went wrong:

380380

amazon-bedrock Changed · +1 / -1 lines

from line 615

615615

616616Amazon Bedrock streams `InvokeModelWithResponseStream` responses in a binary event-stream format with the header `Content-Type: application/vnd.amazon.eventstream`. A gateway or proxy between Claude Code and Amazon Bedrock must forward the response body and its headers, including `Content-Type`, as Amazon Bedrock sent them.

617617

618If the gateway rewrites `Content-Type` to another value, Claude Code rejects the response with an error that begins `Bedrock streaming response has content-type`, naming the value it received. The common rewrite is `text/event-stream`, from an integration that re-emits the stream as server-sent events.

618If the gateway rewrites `Content-Type` to another value, Claude Code rejects the response with an error that begins `Bedrock streaming response has content-type`, naming the value it received. The common rewrite is `text/event-stream`, from an integration that re-emits the stream as server-sent events. For the `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` variable that the error message names, see [Bedrock streaming response has an unexpected content-type](/docs/en/errors#bedrock-streaming-response-has-an-unexpected-content-type).

619619

620620If the gateway drops or blanks the header instead, Claude Code assumes the body is Amazon Bedrock's event stream and decodes it, so a body the gateway passed through unmodified keeps streaming.

621621

auto-mode-config Changed · +1 / -1 lines

from line 331

331331}

332332```

333333

334Get AI feedback on your custom `allow`, `soft_deny`, and `hard_deny` rules:

334Get AI feedback on your custom `allow`, `soft_deny`, `hard_deny`, and `environment` entries:

335335

336336```bash theme={null}

337337claude auto-mode critique

chrome Changed · +1 / -1 lines

from line 291

291291

292292| Error | Cause | Fix |

293293| - | - | - |

294| "Browser extension is not connected" | Native messaging host cannot reach the extension, or your organization's IP allowlist rejects the connection to `bridge.claudeusercontent.com` | Restart Chrome and Claude Code, then run `/chrome` to reconnect. If your organization uses IP allowlisting and the error persists, see [Organization IP allowlists and proxy egress](/docs/en/network-config#organization-ip-allowlists-and-proxy-egress) |

294| "Browser extension is not connected" | Native messaging host cannot reach the extension, or your organization's IP allowlist rejects the connection to `bridge.claudeusercontent.com` | Check that the extension is signed in to the same claude.ai account as Claude Code, restart Chrome and Claude Code, then run `/chrome` to reconnect. If your organization uses IP allowlisting and the error persists, see [Organization IP allowlists and proxy egress](/docs/en/network-config#organization-ip-allowlists-and-proxy-egress) |

295295| Extension shows "Not detected" in `/chrome` | Chrome extension is not installed or is disabled | Install or enable the extension in `chrome://extensions` |

296296| "No tab available" | Claude tried to act before a tab was ready | Ask Claude to create a new tab and retry |

297297| "Receiving end does not exist" | Extension service worker went idle | Run `/chrome` and select "Reconnect extension" |

context-window Changed · +1 / -1 lines

from line 1580

15801580

15811581The session walks through a realistic flow with representative token counts:

15821582

1583* **Before you type anything**: CLAUDE.md, auto memory, MCP tool names, and skill descriptions all load into context. [AGENTS.md files](/docs/en/memory#agents-md) can load too, on their own or alongside CLAUDE.md. Your own setup may add more here, like an [output style](/docs/en/output-styles) or text from [`--append-system-prompt`](/docs/en/cli-reference).

1583* **Before you type anything**: CLAUDE.md, auto memory, MCP tool names, and skill descriptions all load into context. [AGENTS.md files](/docs/en/memory#agents-md) can load in place of CLAUDE.md. Your own setup may add more here, like an [output style](/docs/en/output-styles) or text from [`--append-system-prompt`](/docs/en/cli-reference).

15841584* **As Claude works**: each file read adds to context, [path-scoped rules](/docs/en/memory#path-specific-rules) load automatically alongside matching files, and a [PostToolUse hook](/docs/en/hooks-guide) fires after each edit.

15851585* **The follow-up prompt**: a [subagent](/docs/en/sub-agents) handles the research in its own separate context window, so the large file reads stay out of yours. Only the summary and a small metadata trailer come back.

15861586* **At the end of the walkthrough**: you run `/compact`, which replaces the conversation with a structured summary. Most startup content reloads automatically; the table below shows what happens to each mechanism.

glossary Changed · +1 / -1 lines

from line 92

9292

9393A markdown file of persistent instructions you write for Claude, loaded at the start of every session as a user message after the system prompt. Put project conventions, architecture notes, and "always do X" rules here. Project-root CLAUDE.md survives [compaction](#compaction) and is re-read fresh from disk afterward.

9494

95You can place CLAUDE.md at project scope in `./CLAUDE.md` or `./.claude/CLAUDE.md`, at user scope in `~/.claude/CLAUDE.md`, or as [managed policy](#managed-settings) for your organization. All discovered files are concatenated into context rather than overriding each other, ordered from broadest scope to most specific. Claude Code can also load a project's [AGENTS.md](#agents-md) files, on their own or alongside CLAUDE.md.

95You can place CLAUDE.md at project scope in `./CLAUDE.md` or `./.claude/CLAUDE.md`, at user scope in `~/.claude/CLAUDE.md`, or as [managed policy](#managed-settings) for your organization. All discovered files are concatenated into context rather than overriding each other, ordered from broadest scope to most specific. Claude Code can also load a project's [AGENTS.md](#agents-md) files in place of CLAUDE.md.

9696

9797Learn more: [CLAUDE.md files](/docs/en/memory#claude-md-files)

9898

google-vertex-ai Changed · +2 / -2 lines

from line 188

188188export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

189189```

190190

191Most model versions have a corresponding `VERTEX_REGION_CLAUDE_*` variable. See the [Environment variables reference](/docs/en/env-vars) for the full list. Check [Google Cloud's Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) to determine which models support global endpoints versus regional only.

191Most model versions have a corresponding `VERTEX_REGION_CLAUDE_*` variable. See the [Environment variables reference](/docs/en/env-vars#variables) for the full list. Check [Google Cloud's Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) to determine which models support global endpoints versus regional only.

192192

193193If a region value isn't shaped like a region or location name, Claude Code treats it as unset. For example, Claude Code treats a value containing a slash, dot, or space as unset. Claude Code falls back to a different source for each variable:

194194

from line 328

328328* Verify the model is available in the location you specified. Some models are offered only on `global` or multi-region locations such as `eu` and `us`, not in specific regions

329329* If using `CLOUD_ML_REGION=global`, check that your models support global endpoints in [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) under "Supported features". For models that don't support global endpoints, either:

330330 * Specify a supported model via `ANTHROPIC_MODEL` or `ANTHROPIC_DEFAULT_HAIKU_MODEL`, or

331 * Set a region or multi-region location using `VERTEX_REGION_<MODEL_NAME>` environment variables

331 * Set a region or multi-region location using the model's `VERTEX_REGION_CLAUDE_*` variable, listed in the [environment variables reference](/docs/en/env-vars#variables)

332332

333333If you encounter 429 errors:

334334

hooks-guide Changed · +1 / -1 lines

from line 502

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

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

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

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

505| `WorktreeRemove` | When a worktree that a `WorktreeCreate` hook created is being removed |

506506| `PreCompact` | Before context compaction |

507507| `PostCompact` | After context compaction completes |

508508| `PreModelSwitch` | Before Claude Code applies a model switch that you or a client requested. Can block the switch |

how-claude-code-works Changed · +1 / -1 lines

from line 64

6464* **Your project.** Files in your directory and subdirectories, plus files elsewhere with your permission.

6565* **Your terminal.** Any command you could run: build tools, git, package managers, system utilities, scripts. If you can do it from the command line, Claude can too.

6666* **Your git state.** Current branch, uncommitted changes, and recent commit history.

67* **Your [CLAUDE.md](/docs/en/memory).** A markdown file where you store project-specific instructions, conventions, and context that Claude should know every session. If your repository has an AGENTS.md for other coding agents, Claude [can read that](/docs/en/memory#agents-md) on its own or alongside CLAUDE.md.

67* **Your [CLAUDE.md](/docs/en/memory).** A markdown file where you store project-specific instructions, conventions, and context that Claude should know every session. If your repository has an AGENTS.md for other coding agents, Claude [can read that](/docs/en/memory#agents-md) in place of a CLAUDE.md.

6868* **[Auto memory](/docs/en/memory#auto-memory).** Learnings Claude saves automatically as you work, like your preferences. The first 200 lines or 25KB of MEMORY.md, whichever comes first, load at the start of each session.

6969* **Extensions you configure.** [MCP servers](/docs/en/mcp) for external services, [skills](/docs/en/skills) for workflows, [subagents](/docs/en/sub-agents) for delegated work, and [Claude in Chrome](/docs/en/chrome) for browser interaction.

7070

memory Changed · +2 / -2 lines

from line 4

44

55Each Claude Code session begins with a fresh context window. Two mechanisms carry knowledge across sessions:

66

7* **CLAUDE.md files**: instructions you write to give Claude persistent context. Claude can also read a repository's [`AGENTS.md` files](#agents-md), on their own or alongside CLAUDE.md

7* **CLAUDE.md files**: instructions you write to give Claude persistent context. Claude can also read a repository's [`AGENTS.md` files](#agents-md) in place of CLAUDE.md

88* **Auto memory**: notes Claude writes itself based on your corrections and preferences

99

1010This page covers how to:

1111

1212* [Write and organize CLAUDE.md files](#claude-md-files)

13* [Use an existing AGENTS.md](#agents-md) as your project instructions, on its own or alongside CLAUDE.md

13* [Use an existing AGENTS.md](#agents-md) as your project instructions

1414* [Scope rules to specific file types](#organize-rules-with-claude/rules/) with `.claude/rules/`

1515* [Configure auto memory](#auto-memory) so Claude takes notes automatically

1616* [Troubleshoot](#troubleshoot-memory-issues) when instructions aren't being followed

overview Changed · +1 / -1 lines

from line 163

163163 </Accordion>

164164

165165 <Accordion title="Customize with instructions, skills, and hooks" icon="sliders">

166 [`CLAUDE.md`](/docs/en/memory) is a markdown file you add to your project root that Claude Code reads at the start of every session. Use it to set coding standards, architecture decisions, preferred libraries, and review checklists. If your repository already has an `AGENTS.md` for other coding agents, Claude Code [can read that](/docs/en/memory#agents-md) on its own or alongside `CLAUDE.md`. Claude also builds [auto memory](/docs/en/memory#auto-memory) as it works, saving learnings across sessions without you writing anything.

166 [`CLAUDE.md`](/docs/en/memory) is a markdown file you add to your project root that Claude Code reads at the start of every session. Use it to set coding standards, architecture decisions, preferred libraries, and review checklists. If your repository already has an `AGENTS.md` for other coding agents, Claude Code [can read that](/docs/en/memory#agents-md) in place of a `CLAUDE.md`. Claude also builds [auto memory](/docs/en/memory#auto-memory) as it works, saving learnings across sessions without you writing anything.

167167

168168 Create [skills](/docs/en/skills) to package repeatable workflows your team can share, like `/review-pr` or `/deploy-staging`.

169169

self-hosted-environments-testing Changed · +1 / -1 lines

from line 88

8888

8989## Example script

9090

91The script below runs the full loop against `$CLAUDE_TEST_ENVIRONMENT_ID`, your test environment's `ccpool_...` ID, shown in the environment's detail dialog on the admin page or returned by the [create-environment call](#create-a-dedicated-test-environment), and asserts on a sentinel phrase in each reply. Run it from a git checkout of the repository you want the session to work in, after starting a runner on this host with the capture hook installed and `E2E_REPLY_DIR` exported.

91The script below runs the full loop against `$CLAUDE_TEST_ENVIRONMENT_ID`, your test environment's `ccpool_...` ID, shown in the environment's detail dialog on the admin page or returned by the [create-environment call](#create-a-dedicated-test-environment), and asserts on a sentinel phrase in each reply. Run it from a git checkout of the repository you want the session to work in, after starting a runner on this host with the capture hook installed and `E2E_REPLY_DIR` exported. First sign in with a claude.ai account on the machine that runs the script, as [Authenticate from CI](#authenticate-from-ci) describes. Without that sign-in, the first dispatch fails with an error such as `Unable to get organization UUID for cloud session creation`.