Documentation 2026-05-14 17:02 UTC to 2026-05-15 22:58 UTC

46 46 

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

48 import asyncio48 import asyncio

49 from claude_agent_sdk import query49 from claude_agent_sdk import query, ClaudeAgentOptions

50 50 

51 51 

52 async def main():52 async def main():

53 async for message in query(53 async for message in query(

54 prompt="Hello",54 prompt="Hello",

55 options={55 options=ClaudeAgentOptions(

56 "plugins": [56 plugins=[

57 {"type": "local", "path": "./my-plugin"},57 {"type": "local", "path": "./my-plugin"},

58 {"type": "local", "path": "/absolute/path/to/another-plugin"},58 {"type": "local", "path": "/absolute/path/to/another-plugin"},

59 ]59 ]

60 },60 ),

61 ):61 ):

62 # Plugin commands, agents, and other features are now available62 # Plugin commands, agents, and other features are now available

63 pass63 pass

106 106 

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

108 import asyncio108 import asyncio

109 from claude_agent_sdk import query109 from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage

110 110 

111 111 

112 async def main():112 async def main():

113 async for message in query(113 async for message in query(

114 prompt="Hello", options={"plugins": [{"type": "local", "path": "./my-plugin"}]}114 prompt="Hello",

115 options=ClaudeAgentOptions(

116 plugins=[{"type": "local", "path": "./my-plugin"}]

117 ),

115 ):118 ):

116 if message.type == "system" and message.subtype == "init":119 if isinstance(message, SystemMessage) and message.subtype == "init":

117 # Check loaded plugins120 # Check loaded plugins

118 print("Plugins:", message.data.get("plugins"))121 print("Plugins:", message.data.get("plugins"))

119 # Example: [{"name": "my-plugin", "path": "./my-plugin"}]122 # Example: [{"name": "my-plugin", "path": "./my-plugin"}]

151 154 

152 ```python Python theme={null}155 ```python Python theme={null}

153 import asyncio156 import asyncio

154 from claude_agent_sdk import query, AssistantMessage, TextBlock157 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock

155 158 

156 159 

157 async def main():160 async def main():

158 # Load a plugin with a custom /greet skill161 # Load a plugin with a custom /greet skill

159 async for message in query(162 async for message in query(

160 prompt="/demo-plugin:greet", # Use plugin skill with namespace163 prompt="/demo-plugin:greet", # Use plugin skill with namespace

161 options={"plugins": [{"type": "local", "path": "./plugins/demo-plugin"}]},164 options=ClaudeAgentOptions(

165 plugins=[{"type": "local", "path": "./plugins/demo-plugin"}]

166 ),

162 ):167 ):

163 # Claude executes the custom greeting skill from the plugin168 # Claude executes the custom greeting skill from the plugin

164 if isinstance(message, AssistantMessage):169 if isinstance(message, AssistantMessage):

219 from claude_agent_sdk import (224 from claude_agent_sdk import (

220 AssistantMessage,225 AssistantMessage,

221 ClaudeAgentOptions,226 ClaudeAgentOptions,

227 SystemMessage,

222 TextBlock,228 TextBlock,

223 query,229 query,

224 )230 )

238 async for message in query(244 async for message in query(

239 prompt="What custom commands do you have available?", options=options245 prompt="What custom commands do you have available?", options=options

240 ):246 ):

241 if message.type == "system" and message.subtype == "init":247 if isinstance(message, SystemMessage) and message.subtype == "init":

242 print(f"Loaded plugins: {message.data.get('plugins')}")248 print(f"Loaded plugins: {message.data.get('plugins')}")

243 print(f"Available commands: {message.data.get('slash_commands')}")249 print(f"Available commands: {message.data.get('slash_commands')}")

244 250 

56 prompt: "/compact",56 prompt: "/compact",

57 options: { maxTurns: 1 }57 options: { maxTurns: 1 }

58 })) {58 })) {

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

60 console.log("Command executed:", message.result);60 console.log("Command executed:", message.result);

61 }61 }

62 }62 }

261 options: { maxTurns: 5 }261 options: { maxTurns: 5 }

262 })) {262 })) {

263 // Command will process with $1="123" and $2="high"263 // Command will process with $1="123" and $2="high"

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

265 console.log("Issue fixed:", message.result);265 console.log("Issue fixed:", message.result);

266 }266 }

267 }267 }

91 91 

92<CodeGroup>92<CodeGroup>

93 ```typescript TypeScript theme={null}93 ```typescript TypeScript theme={null}

94 import { query } from "@anthropic-ai/claude-agent-sdk";94 import { query, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";

95 import { readFile } from "fs/promises";95 import { readFile } from "fs/promises";

96 96 

97 async function* generateMessages() {97 async function* generateMessages(): AsyncGenerator<SDKUserMessage> {

98 // First message98 // First message

99 yield {99 yield {

100 type: "user" as const,100 type: "user",

101 message: {101 message: {

102 role: "user" as const,102 role: "user",

103 content: "Analyze this codebase for security issues"103 content: "Analyze this codebase for security issues"

104 }104 },

105 parent_tool_use_id: null

105 };106 };

106 107 

107 // Wait for conditions or user input108 // Wait for conditions or user input

109 110 

110 // Follow-up with image111 // Follow-up with image

111 yield {112 yield {

112 type: "user" as const,113 type: "user",

113 message: {114 message: {

114 role: "user" as const,115 role: "user",

115 content: [116 content: [

116 {117 {

117 type: "text",118 type: "text",

126 }127 }

127 }128 }

128 ]129 ]

129 }130 },

131 parent_tool_use_id: null

130 };132 };

131 }133 }

132 134 

138 allowedTools: ["Read", "Grep"]140 allowedTools: ["Read", "Grep"]

139 }141 }

140 })) {142 })) {

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

142 console.log(message.result);144 console.log(message.result);

143 }145 }

144 }146 }

248 allowedTools: ["Read", "Grep"]250 allowedTools: ["Read", "Grep"]

249 }251 }

250 })) {252 })) {

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

252 console.log(message.result);254 console.log(message.result);

253 }255 }

254 }256 }

261 maxTurns: 1263 maxTurns: 1

262 }264 }

263 })) {265 })) {

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

265 console.log(message.result);267 console.log(message.result);

266 }268 }

267 }269 }

313<CodeGroup>313<CodeGroup>

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

315 import asyncio315 import asyncio

316 from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition316 from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ToolUseBlock

317 317 

318 318 

319 async def main():319 async def main():

334 # versions emitted "Task", current versions emit "Agent".334 # versions emitted "Task", current versions emit "Agent".

335 if hasattr(message, "content") and message.content:335 if hasattr(message, "content") and message.content:

336 for block in message.content:336 for block in message.content:

337 if getattr(block, "type", None) == "tool_use" and block.name in (337 if isinstance(block, ToolUseBlock) and block.name in (

338 "Task",338 "Task",

339 "Agent",339 "Agent",

340 ):340 ):

414 // Helper to extract agentId from message content414 // Helper to extract agentId from message content

415 // Stringify to avoid traversing different block types (TextBlock, ToolResultBlock, etc.)415 // Stringify to avoid traversing different block types (TextBlock, ToolResultBlock, etc.)

416 function extractAgentId(message: SDKMessage): string | undefined {416 function extractAgentId(message: SDKMessage): string | undefined {

417 if (!("message" in message)) return undefined;417 if (message.type !== "assistant" && message.type !== "user") return undefined;

418 // Stringify the content so we can search it without traversing nested blocks418 // Stringify the content so we can search it without traversing nested blocks

419 const content = JSON.stringify(message.message.content);419 const content = JSON.stringify(message.message.content);

420 const match = content.match(/agentId:\s*([a-f0-9-]+)/);420 const match = content.match(/agentId:\s*([a-f0-9-]+)/);

29 29 

30## Configure tool search30## Configure tool search

31 31 

32Tool search is on by default. It is disabled by default on Vertex AI, which does not accept the tool search beta header, and when `ANTHROPIC_BASE_URL` points to a non-first-party host, since most proxies do not forward `tool_reference` blocks. You can override this with the `ENABLE_TOOL_SEARCH` environment variable:32Tool search is on by default. It is disabled by default on Vertex AI, where it is supported for Claude Sonnet 4.5 and later and Claude Opus 4.5 and later. It is also disabled when `ANTHROPIC_BASE_URL` points to a non-first-party host, since most proxies do not forward `tool_reference` blocks. You can override either default with the `ENABLE_TOOL_SEARCH` environment variable:

33 33 

34| Value | Behavior |34| Value | Behavior |

35| :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |35| :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

36| (unset) | Tool search is on. Tool definitions are deferred and discovered on demand. Falls back to loading upfront on Vertex AI or a non-first-party `ANTHROPIC_BASE_URL`. |36| (unset) | Tool search is on. Tool definitions are deferred and discovered on demand. Falls back to loading upfront on Vertex AI or a non-first-party `ANTHROPIC_BASE_URL`. |

37| `true` | Tool search is always on. The SDK sends the beta header even on Vertex AI and through proxies. Requests fail if the backend or proxy does not support `tool_reference` blocks. |37| `true` | Tool search is always on. The SDK sends the beta header even on Vertex AI and through proxies. Requests fail on Vertex AI models earlier than Sonnet 4.5 or Opus 4.5, or on proxies that do not support `tool_reference` blocks. |

38| `auto` | Checks the combined token count of all tool definitions against the model's context window. If they exceed 10%, tool search activates. If they're under 10%, all tools are loaded into context normally. |38| `auto` | Checks the combined token count of all tool definitions against the model's context window. If they exceed 10%, tool search activates. If they're under 10%, all tools are loaded into context normally. |

39| `auto:N` | Same as `auto` with a custom percentage. `auto:5` activates when tool definitions exceed 5% of the context window. Lower values activate sooner. |39| `auto:N` | Same as `auto` with a custom percentage. `auto:5` activates when tool definitions exceed 5% of the context window. Lower values activate sooner. |

40| `false` | Tool search is off. All tool definitions are loaded into context on every turn. |40| `false` | Tool search is off. All tool definitions are loaded into context on every turn. |

948type SDKUserMessage = {948type SDKUserMessage = {

949 type: "user";949 type: "user";

950 uuid?: UUID;950 uuid?: UUID;

951 session_id: string;951 session_id?: string;

952 message: MessageParam; // From Anthropic SDK952 message: MessageParam; // From Anthropic SDK

953 parent_tool_use_id: string | null;953 parent_tool_use_id: string | null;

954 isSynthetic?: boolean;954 isSynthetic?: boolean;

265claude --agent code-reviewer --bg "address review comments on PR 1234"265claude --agent code-reviewer --bg "address review comments on PR 1234"

266```266```

267 267 

268Pass `--name` to set the session's display name in agent view instead of the auto-generated one:

269 

270```bash theme={null}

271claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"

272```

273 

268After backgrounding, Claude prints the session's short ID and the commands for managing it:274After backgrounding, Claude prints the session's short ID and the commands for managing it:

269 275 

270```text theme={null}276```text theme={null}

211export CLAUDE_CODE_USE_BEDROCK=1211export CLAUDE_CODE_USE_BEDROCK=1

212export AWS_REGION=us-east-1 # or your preferred region212export AWS_REGION=us-east-1 # or your preferred region

213 213 

214# Optional: Override the region for the small/fast model (Haiku).214# Optional: Override the AWS region for the small/fast model (Bedrock and Mantle).

215# Also applies to Bedrock Mantle.215# On Bedrock, has no effect without ANTHROPIC_DEFAULT_HAIKU_MODEL

216# or the deprecated ANTHROPIC_SMALL_FAST_MODEL set.

216export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2217export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2

217 218 

218# Optional: Override the Bedrock endpoint URL for custom endpoints or gateways219# Optional: Override the Bedrock endpoint URL for custom endpoints or gateways

248| Model type | Default value |249| Model type | Default value |

249| :--------------- | :--------------------------------------------- |250| :--------------- | :--------------------------------------------- |

250| Primary model | `us.anthropic.claude-sonnet-4-5-20250929-v1:0` |251| Primary model | `us.anthropic.claude-sonnet-4-5-20250929-v1:0` |

251| Small/fast model | `us.anthropic.claude-haiku-4-5-20251001-v1:0` |252| Small/fast model | Same as primary model |

253 

254Background tasks such as session title generation use the small/fast model, normally a Haiku-class model. On Bedrock, Claude Code defaults this to the primary model because Haiku may not be enabled in every account or region. To use Haiku for background tasks, set `ANTHROPIC_DEFAULT_HAIKU_MODEL` to a model ID that is available in your account.

252 255 

253To customize models further, use one of these methods:256To customize models further, use one of these methods:

254 257 

1495Files in the paths below are deleted on startup once they're older than [`cleanupPeriodDays`](/en/settings#available-settings). The default is 30 days.1495Files in the paths below are deleted on startup once they're older than [`cleanupPeriodDays`](/en/settings#available-settings). The default is 30 days.

1496 1496 

1497| Path under `~/.claude/` | Contents |1497| Path under `~/.claude/` | Contents |

1498| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |1498| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |

1499| `projects/<project>/<session>.jsonl` | Full conversation transcript: every message, tool call, and tool result |1499| `projects/<project>/<session>.jsonl` | Full conversation transcript: every message, tool call, and tool result |

1500| `projects/<project>/<session>/subagents/` | [Subagent](/en/sub-agents) conversation transcripts, removed with the parent session transcript when it ages out |1500| `projects/<project>/<session>/subagents/` | [Subagent](/en/sub-agents) conversation transcripts, removed with the parent session transcript when it ages out |

1501| `projects/<project>/<session>/tool-results/` | Large tool outputs spilled to separate files |1501| `projects/<project>/<session>/tool-results/` | Large tool outputs spilled to separate files |

1507| `tasks/` | Per-session task lists written by the task tools |1507| `tasks/` | Per-session task lists written by the task tools |

1508| `shell-snapshots/` | Captured shell environment used by the Bash tool. Removed on clean exit. The sweep clears any left after a crash. |1508| `shell-snapshots/` | Captured shell environment used by the Bash tool. Removed on clean exit. The sweep clears any left after a crash. |

1509| `backups/` | Timestamped copies of `~/.claude.json` taken before config migrations |1509| `backups/` | Timestamped copies of `~/.claude.json` taken before config migrations |

1510| `feedback-bundles/` | Redacted transcript archives written by `/feedback` on third-party providers, for sending to your Anthropic account team |

1510 1511 

1511### Kept until you delete them1512### Kept until you delete them

1512 1513 

99 99 

100Claude Code connects from users' machines to Sentry for operational error logging. The data is encrypted in transit using TLS and at rest using 256-bit AES encryption. Read more in the [Sentry security documentation](https://sentry.io/security/). To opt out of error logging, set the `DISABLE_ERROR_REPORTING` environment variable.100Claude Code connects from users' machines to Sentry for operational error logging. The data is encrypted in transit using TLS and at rest using 256-bit AES encryption. Read more in the [Sentry security documentation](https://sentry.io/security/). To opt out of error logging, set the `DISABLE_ERROR_REPORTING` environment variable.

101 101 

102When users run the `/feedback` command, a copy of their full conversation history including code is sent to Anthropic. The data is encrypted in transit via TLS. Optionally, a GitHub issue is created in the public repository. To opt out, set the `DISABLE_FEEDBACK_COMMAND` environment variable to `1`.102When you run the `/feedback` command, a copy of your conversation history including code is sent to Anthropic. Before submitting, you choose how much history to include: the current session only, which is the default, or also other sessions from the same project over the last 24 hours or 7 days. The data is encrypted in transit via TLS. Optionally, a GitHub issue is created in the public repository. To opt out, set the `DISABLE_FEEDBACK_COMMAND` environment variable to `1`.

103 

104When you use a third-party provider such as Bedrock or Vertex, or have no Anthropic credentials configured, `/feedback` writes the report to a local archive under `~/.claude/feedback-bundles/` instead of sending it to Anthropic. Known API key and token patterns are redacted before the archive is written. Nothing leaves your machine until you send that file to your Anthropic account representative or attach it to a support request.

103 105 

104## Default behaviors by API provider106## Default behaviors by API provider

105 107 

42| `ANTHROPIC_FOUNDRY_RESOURCE` | Foundry resource name (for example, `my-resource`). Required if `ANTHROPIC_FOUNDRY_BASE_URL` is not set (see [Microsoft Foundry](/en/microsoft-foundry)) |42| `ANTHROPIC_FOUNDRY_RESOURCE` | Foundry resource name (for example, `my-resource`). Required if `ANTHROPIC_FOUNDRY_BASE_URL` is not set (see [Microsoft Foundry](/en/microsoft-foundry)) |

43| `ANTHROPIC_MODEL` | Name of the model setting to use (see [Model Configuration](/en/model-config#environment-variables)) |43| `ANTHROPIC_MODEL` | Name of the model setting to use (see [Model Configuration](/en/model-config#environment-variables)) |

44| `ANTHROPIC_SMALL_FAST_MODEL` | \[DEPRECATED] Name of [Haiku-class model for background tasks](/en/costs) |44| `ANTHROPIC_SMALL_FAST_MODEL` | \[DEPRECATED] Name of [Haiku-class model for background tasks](/en/costs) |

45| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | Override AWS region for the Haiku-class model when using Bedrock or Bedrock Mantle |45| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | Override AWS region for the Haiku-class model when using Bedrock or Bedrock Mantle. On Bedrock, this only takes effect when `ANTHROPIC_DEFAULT_HAIKU_MODEL` or the deprecated `ANTHROPIC_SMALL_FAST_MODEL` is also set, since Bedrock otherwise uses the primary model for background tasks |

46| `ANTHROPIC_VERTEX_BASE_URL` | Override the Vertex AI endpoint URL. Use for custom Vertex endpoints or when routing through an [LLM gateway](/en/llm-gateway). See [Google Vertex AI](/en/google-vertex-ai) |46| `ANTHROPIC_VERTEX_BASE_URL` | Override the Vertex AI endpoint URL. Use for custom Vertex endpoints or when routing through an [LLM gateway](/en/llm-gateway). See [Google Vertex AI](/en/google-vertex-ai) |

47| `ANTHROPIC_VERTEX_PROJECT_ID` | GCP project ID for Vertex AI requests. Overridden by `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT`, or the project in your `GOOGLE_APPLICATION_CREDENTIALS` credential file. See [Google Vertex AI](/en/google-vertex-ai) |47| `ANTHROPIC_VERTEX_PROJECT_ID` | GCP project ID for Vertex AI requests. Overridden by `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT`, or the project in your `GOOGLE_APPLICATION_CREDENTIALS` credential file. See [Google Vertex AI](/en/google-vertex-ai) |

48| `ANTHROPIC_WORKSPACE_ID` | Workspace ID for [workload identity federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation). Set this when your federation rule is scoped to more than one workspace so the token exchange knows which workspace to target |48| `ANTHROPIC_WORKSPACE_ID` | Workspace ID for [workload identity federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation). Set this when your federation rule is scoped to more than one workspace so the token exchange knows which workspace to target |

69| `CLAUDE_CODE_CLIENT_CERT` | Path to client certificate file for mTLS authentication |69| `CLAUDE_CODE_CLIENT_CERT` | Path to client certificate file for mTLS authentication |

70| `CLAUDE_CODE_CLIENT_KEY` | Path to client private key file for mTLS authentication |70| `CLAUDE_CODE_CLIENT_KEY` | Path to client private key file for mTLS authentication |

71| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | Passphrase for encrypted CLAUDE\_CODE\_CLIENT\_KEY (optional) |71| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | Passphrase for encrypted CLAUDE\_CODE\_CLIENT\_KEY (optional) |

72| `CLAUDE_CODE_DEBUG_LOGS_DIR` | Override the debug log file path. Despite the name, this is a file path, not a directory. Requires debug mode to be enabled separately via `--debug` or `/debug`: setting this variable alone does not enable logging. The [`--debug-file`](/en/cli-reference#cli-flags) flag does both at once. Defaults to `~/.claude/debug/<session-id>.txt` |72| `CLAUDE_CODE_DEBUG_LOGS_DIR` | Override the debug log file path. Despite the name, this is a file path, not a directory. Requires debug mode to be enabled separately via `--debug`, `/debug`, or the `DEBUG` environment variable: setting this variable alone does not enable logging. The [`--debug-file`](/en/cli-reference#cli-flags) flag does both at once. Defaults to `~/.claude/debug/<session-id>.txt` |

73| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | Minimum log level written to the debug log file. Values: `verbose`, `debug` (default), `info`, `warn`, `error`. Set to `verbose` to include high-volume diagnostics like full status line command output, or raise to `error` to reduce noise |73| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | Minimum log level written to the debug log file. Values: `verbose`, `debug` (default), `info`, `warn`, `error`. Set to `verbose` to include high-volume diagnostics like full status line command output, or raise to `error` to reduce noise |

74| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Set to `1` to disable [1M context window](/en/model-config#extended-context) support. When set, 1M model variants are unavailable in the model picker. Useful for enterprise environments with compliance requirements |74| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Set to `1` to disable [1M context window](/en/model-config#extended-context) support. When set, 1M model variants are unavailable in the model picker. Useful for enterprise environments with compliance requirements |

75| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | Set to `1` to disable [adaptive reasoning](/en/model-config#adjust-effort-level) on Opus 4.6 and Sonnet 4.6 and fall back to the fixed thinking budget controlled by `MAX_THINKING_TOKENS`. {/* min-version: 2.1.111 */}Has no effect on Opus 4.7, which always uses adaptive reasoning |75| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | Set to `1` to disable [adaptive reasoning](/en/model-config#adjust-effort-level) on Opus 4.6 and Sonnet 4.6 and fall back to the fixed thinking budget controlled by `MAX_THINKING_TOKENS`. {/* min-version: 2.1.111 */}Has no effect on Opus 4.7, which always uses adaptive reasoning |

184| `CLAUDE_ENV_FILE` | Path to a shell script whose contents Claude Code runs before each Bash command in the same shell process, so exports in the file are visible to the command. Use to persist virtualenv or conda activation across commands. Also populated dynamically by [SessionStart](/en/hooks#persist-environment-variables), [Setup](/en/hooks#setup), [CwdChanged](/en/hooks#cwdchanged), and [FileChanged](/en/hooks#filechanged) hooks |184| `CLAUDE_ENV_FILE` | Path to a shell script whose contents Claude Code runs before each Bash command in the same shell process, so exports in the file are visible to the command. Use to persist virtualenv or conda activation across commands. Also populated dynamically by [SessionStart](/en/hooks#persist-environment-variables), [Setup](/en/hooks#setup), [CwdChanged](/en/hooks#cwdchanged), and [FileChanged](/en/hooks#filechanged) hooks |

185| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | Prefix for auto-generated [Remote Control](/en/remote-control) session names when no explicit name is provided. Defaults to your machine's hostname, producing names like `myhost-graceful-unicorn`. The `--remote-control-session-name-prefix` CLI flag sets the same value for a single invocation |185| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | Prefix for auto-generated [Remote Control](/en/remote-control) session names when no explicit name is provided. Defaults to your machine's hostname, producing names like `myhost-graceful-unicorn`. The `--remote-control-session-name-prefix` CLI flag sets the same value for a single invocation |

186| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | Timeout in milliseconds before the streaming idle watchdog closes a stalled connection. Default and minimum `300000` (5 minutes) for both the byte-level and event-level watchdogs; lower values are silently clamped to absorb extended thinking pauses and proxy buffering. For third-party providers, requires `CLAUDE_ENABLE_STREAM_WATCHDOG=1` |186| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | Timeout in milliseconds before the streaming idle watchdog closes a stalled connection. Default and minimum `300000` (5 minutes) for both the byte-level and event-level watchdogs; lower values are silently clamped to absorb extended thinking pauses and proxy buffering. For third-party providers, requires `CLAUDE_ENABLE_STREAM_WATCHDOG=1` |

187| `DEBUG` | Set to `1` to enable debug mode, equivalent to launching with [`--debug`](/en/cli-reference#cli-flags). Debug logs are written to `~/.claude/debug/<session-id>.txt`, or to the path set by `CLAUDE_CODE_DEBUG_LOGS_DIR`. Only the truthy values `1`, `true`, `yes`, and `on` enable debug mode, so namespace patterns like `DEBUG=express:*` set for other tools do not trigger it |

187| `DISABLE_AUTOUPDATER` | Set to `1` to disable automatic background updates. Manual `claude update` still works. Use `DISABLE_UPDATES` to block both |188| `DISABLE_AUTOUPDATER` | Set to `1` to disable automatic background updates. Manual `claude update` still works. Use `DISABLE_UPDATES` to block both |

188| `DISABLE_AUTO_COMPACT` | Set to `1` to disable automatic compaction when approaching the context limit. The manual `/compact` command remains available. Use when you want explicit control over when compaction occurs |189| `DISABLE_AUTO_COMPACT` | Set to `1` to disable automatic compaction when approaching the context limit. The manual `/compact` command remains available. Use when you want explicit control over when compaction occurs |

189| `DISABLE_COMPACT` | Set to `1` to disable all compaction: both automatic compaction and the manual `/compact` command |190| `DISABLE_COMPACT` | Set to `1` to disable all compaction: both automatic compaction and the manual `/compact` command |

209| `ENABLE_CLAUDEAI_MCP_SERVERS` | Set to `false` to disable [claude.ai MCP servers](/en/mcp#use-mcp-servers-from-claude-ai) in Claude Code. Enabled by default for logged-in users |210| `ENABLE_CLAUDEAI_MCP_SERVERS` | Set to `false` to disable [claude.ai MCP servers](/en/mcp#use-mcp-servers-from-claude-ai) in Claude Code. Enabled by default for logged-in users |

210| `ENABLE_PROMPT_CACHING_1H` | Set to `1` to request a 1-hour prompt cache TTL instead of the default 5 minutes. Intended for API key, [Bedrock](/en/amazon-bedrock), [Vertex](/en/google-vertex-ai), [Foundry](/en/microsoft-foundry), and [Claude Platform on AWS](/en/claude-platform-on-aws) users. Subscription users receive 1-hour TTL automatically. 1-hour cache writes are billed at a higher rate |211| `ENABLE_PROMPT_CACHING_1H` | Set to `1` to request a 1-hour prompt cache TTL instead of the default 5 minutes. Intended for API key, [Bedrock](/en/amazon-bedrock), [Vertex](/en/google-vertex-ai), [Foundry](/en/microsoft-foundry), and [Claude Platform on AWS](/en/claude-platform-on-aws) users. Subscription users receive 1-hour TTL automatically. 1-hour cache writes are billed at a higher rate |

211| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | Deprecated. Use `ENABLE_PROMPT_CACHING_1H` instead |212| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | Deprecated. Use `ENABLE_PROMPT_CACHING_1H` instead |

212| `ENABLE_TOOL_SEARCH` | Controls [MCP tool search](/en/mcp#scale-with-mcp-tool-search). Unset: all MCP tools deferred by default, but loaded upfront on Vertex AI or when `ANTHROPIC_BASE_URL` points to a non-first-party host. Values: `true` (always defer and send the beta header, requests fail on Vertex AI or proxies that do not support `tool_reference`), `auto` (threshold mode: load upfront if tools fit within 10% of context), `auto:N` (custom threshold, e.g., `auto:5` for 5%), `false` (load all upfront) |213| `ENABLE_TOOL_SEARCH` | Controls [MCP tool search](/en/mcp#scale-with-mcp-tool-search). Unset: all MCP tools deferred by default, but loaded upfront on Vertex AI or when `ANTHROPIC_BASE_URL` points to a non-first-party host. Values: `true` (always defer and send the beta header; supported on Vertex AI with Sonnet 4.5 and later or Opus 4.5 and later; requests fail on earlier Vertex AI models or on proxies that do not support `tool_reference`), `auto` (threshold mode: load upfront if tools fit within 10% of context), `auto:N` (custom threshold, e.g., `auto:5` for 5%), `false` (load all upfront) |

213| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | Set to any non-empty value to trigger fallback to [`--fallback-model`](/en/cli-reference#cli-flags) after repeated overload errors on any primary model. By default, only Opus models trigger the fallback |214| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | Set to any non-empty value to trigger fallback to [`--fallback-model`](/en/cli-reference#cli-flags) after repeated overload errors on any primary model. By default, only Opus models trigger the fallback |

214| `FORCE_AUTOUPDATE_PLUGINS` | Set to `1` to force plugin auto-updates even when the main auto-updater is disabled via `DISABLE_AUTOUPDATER` |215| `FORCE_AUTOUPDATE_PLUGINS` | Set to `1` to force plugin auto-updates even when the main auto-updater is disabled via `DISABLE_AUTOUPDATER` |

215| `FORCE_PROMPT_CACHING_5M` | Set to `1` to force the 5-minute prompt cache TTL even when 1-hour TTL would otherwise apply. Overrides `ENABLE_PROMPT_CACHING_1H` |216| `FORCE_PROMPT_CACHING_5M` | Set to `1` to force the 5-minute prompt cache TTL even when 1-hour TTL would otherwise apply. Overrides `ENABLE_PROMPT_CACHING_1H` |

81 81 

82* Check [status.claude.com](https://status.claude.com) for active incidents82* Check [status.claude.com](https://status.claude.com) for active incidents

83* Wait a minute, then send your message again. Your original message is still in the conversation, so for a long prompt you can type `try again` instead of pasting the whole thing.83* Wait a minute, then send your message again. Your original message is still in the conversation, so for a long prompt you can type `try again` instead of pasting the whole thing.

84* If the error persists with no posted incident, run `/feedback` so Anthropic can investigate with your request details. See [Report an error](#report-an-error) if `/feedback` is unavailable on your provider.84* If the error persists with no posted incident, run `/feedback` so Anthropic can investigate with your request details. See [Report an error](#report-an-error) if `/feedback` is unavailable in your environment.

85 85 

86### API Error: Repeated 529 Overloaded errors86### API Error: Repeated 529 Overloaded errors

87 87 

584 584 

585When a response goes wrong, rewinding usually works better than replying with corrections. Press Esc twice or run `/rewind` to step back to before the bad turn, then rephrase the prompt with more specifics. Correcting in-thread keeps the wrong attempt in context, which can anchor later answers to it. See [Checkpointing](/en/checkpointing).585When a response goes wrong, rewinding usually works better than replying with corrections. Press Esc twice or run `/rewind` to step back to before the bad turn, then rephrase the prompt with more specifics. Correcting in-thread keeps the wrong attempt in context, which can anchor later answers to it. See [Checkpointing](/en/checkpointing).

586 586 

587If quality still seems off after checking the above, run `/feedback` and describe what you expected versus what you got. Feedback submitted this way includes the conversation transcript, which is the fastest way for Anthropic to diagnose a real regression. See [Report an error](#report-an-error) if `/feedback` is unavailable on your provider.587If quality still seems off after checking the above, run `/feedback` and describe what you expected versus what you got. Feedback submitted this way includes the conversation transcript, which is the fastest way for Anthropic to diagnose a real regression. See [Report an error](#report-an-error) if `/feedback` is unavailable in your environment.

588 588 

589## Report an error589## Report an error

590 590 

596 596 

597If an error is not listed here or the suggested fix does not help:597If an error is not listed here or the suggested fix does not help:

598 598 

599* Run `/feedback` inside Claude Code to send the transcript and a description to Anthropic. The command also offers to open a prefilled GitHub issue. Feedback is unavailable on Bedrock, Vertex AI, and Foundry deployments.599* Run `/feedback` inside Claude Code to send the transcript and a description to Anthropic. The command also offers to open a prefilled GitHub issue. On Bedrock, Vertex AI, Foundry, and other third-party providers, `/feedback` saves a local archive you can send to your Anthropic account representative instead.

600* Run `/doctor` to check for local configuration problems600* Run `/doctor` to check for local configuration problems

601* Check [status.claude.com](https://status.claude.com) for active incidents601* Check [status.claude.com](https://status.claude.com) for active incidents

602* Search [existing issues](https://github.com/anthropics/claude-code/issues) on GitHub602* Search [existing issues](https://github.com/anthropics/claude-code/issues) on GitHub

6 6 

7> Set a completion condition with /goal and Claude keeps working across turns until the condition is met.7> Set a completion condition with /goal and Claude keeps working across turns until the condition is met.

8 8 

9<Note>

10 `/goal` requires Claude Code v2.1.139 or later.

11</Note>

12 

9The `/goal` command sets a completion condition and Claude keeps working toward it without you prompting each step. After each turn, a small fast model checks whether the condition holds. If not, Claude starts another turn instead of returning control to you. The goal clears automatically once the condition is met.13The `/goal` command sets a completion condition and Claude keeps working toward it without you prompting each step. After each turn, a small fast model checks whether the condition holds. If not, Claude starts another turn instead of returning control to you. The goal clears automatically once the condition is met.

10 14 

11Use a goal for substantial work with a verifiable end state:15Use a goal for substantial work with a verifiable end state:

202 202 

203[Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) is enabled automatically. To disable it, set `DISABLE_PROMPT_CACHING=1`. To request a 1-hour cache TTL instead of the 5-minute default, set `ENABLE_PROMPT_CACHING_1H=1`; cache writes with a 1-hour TTL are billed at a higher rate. For heightened rate limits, contact Google Cloud support. When using Vertex AI, the `/login` and `/logout` commands are disabled since authentication is handled through Google Cloud credentials.203[Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) is enabled automatically. To disable it, set `DISABLE_PROMPT_CACHING=1`. To request a 1-hour cache TTL instead of the 5-minute default, set `ENABLE_PROMPT_CACHING_1H=1`; cache writes with a 1-hour TTL are billed at a higher rate. For heightened rate limits, contact Google Cloud support. When using Vertex AI, the `/login` and `/logout` commands are disabled since authentication is handled through Google Cloud credentials.

204 204 

205[MCP tool search](/en/mcp#scale-with-mcp-tool-search) is disabled by default on Vertex AI because the endpoint does not accept the required beta header. All MCP tool definitions load upfront instead. Setting `ENABLE_TOOL_SEARCH=true` forces Claude Code to send the header anyway, which causes Vertex AI to reject requests.205Claude Code disables [MCP tool search](/en/mcp#scale-with-mcp-tool-search) by default on Vertex AI, so MCP tool definitions load upfront. Vertex AI supports tool search for Claude Sonnet 4.5 and later and Claude Opus 4.5 and later. Set `ENABLE_TOOL_SEARCH=true` to enable it on those models. Earlier models on Vertex AI do not accept the required beta header, and requests fail if you enable tool search with them.

206 206 

207### 5. Pin model versions207### 5. Pin model versions

208 208 

227| Model type | Default value |227| Model type | Default value |

228| :--------------- | :--------------------------- |228| :--------------- | :--------------------------- |

229| Primary model | `claude-sonnet-4-5@20250929` |229| Primary model | `claude-sonnet-4-5@20250929` |

230| Small/fast model | `claude-haiku-4-5@20251001` |230| Small/fast model | Same as primary model |

231 

232Background tasks such as session title generation use the small/fast model, normally a Haiku-class model. On Vertex AI, Claude Code defaults this to the primary model because Haiku may not be enabled in every project or region. To use Haiku for background tasks, set `ANTHROPIC_DEFAULT_HAIKU_MODEL` to a model ID that is available in your project.

231 233 

232To customize models further:234To customize models further:

233 235 

1233| `subagent_type` | string | `"Explore"` | Type of specialized agent to use |1233| `subagent_type` | string | `"Explore"` | Type of specialized agent to use |

1234| `model` | string | `"sonnet"` | Optional model alias to override the default |1234| `model` | string | `"sonnet"` | Optional model alias to override the default |

1235 1235 

1236In `PostToolUse`, `tool_response` for a completed Agent call carries the subagent's final text along with usage telemetry. Read these fields to record per-subagent cost from a hook:

1237 

1238| Field | Type | Example | Description |

1239| :------------------ | :----- | :---------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ |

1240| `status` | string | `"completed"` | `"completed"` for synchronous calls, `"async_launched"` for `run_in_background: true` |

1241| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identifier for the subagent run |

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

1243| `totalTokens` | number | `12450` | Total tokens billed across the subagent's turns |

1244| `totalDurationMs` | number | `48211` | Wall-clock duration of the subagent run |

1245| `totalToolUseCount` | number | `7` | Count of tool calls the subagent made |

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

1247 

1248For `run_in_background: true` calls, the tool returns immediately after launching the subagent, so `tool_response` carries no usage fields. It has `status: "async_launched"`, `agentId`, `description`, `prompt`, and `outputFile` instead.

1249 

1236##### AskUserQuestion1250##### AskUserQuestion

1237 1251 

1238Asks the user one to four multiple-choice questions.1252Asks the user one to four multiple-choice questions.

953 953 

954### Configure tool search954### Configure tool search

955 955 

956Tool search is enabled by default: MCP tools are deferred and discovered on demand. It is disabled by default on Vertex AI, which does not accept the tool search beta header, and when `ANTHROPIC_BASE_URL` points to a non-first-party host, since most proxies do not forward `tool_reference` blocks. If your proxy forwards `tool_reference` blocks, set `ENABLE_TOOL_SEARCH` explicitly to override the fallback. This feature requires models that support `tool_reference` blocks: Sonnet 4 and later, or Opus 4 and later. Haiku models do not support tool search.956Tool search is enabled by default: MCP tools are deferred and discovered on demand. Claude Code disables it by default on Vertex AI. It is also disabled when `ANTHROPIC_BASE_URL` points to a non-first-party host, since most proxies do not forward `tool_reference` blocks. Set `ENABLE_TOOL_SEARCH` explicitly to override either fallback.

957 

958Tool search requires a model that supports `tool_reference` blocks: Sonnet 4 and later, or Opus 4 and later. Haiku models do not support it. On Vertex AI, tool search is supported for Claude Sonnet 4.5 and later and Claude Opus 4.5 and later.

957 959 

958Control tool search behavior with the `ENABLE_TOOL_SEARCH` environment variable:960Control tool search behavior with the `ENABLE_TOOL_SEARCH` environment variable:

959 961 

960| Value | Behavior |962| Value | Behavior |

961| :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |963| :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

962| (unset) | All MCP tools deferred and loaded on demand. Falls back to loading upfront on Vertex AI or when `ANTHROPIC_BASE_URL` is a non-first-party host |964| (unset) | All MCP tools deferred and loaded on demand. Falls back to loading upfront on Vertex AI or when `ANTHROPIC_BASE_URL` is a non-first-party host |

963| `true` | All MCP tools deferred. Claude Code sends the beta header even on Vertex AI and through proxies. Requests fail if the backend does not support `tool_reference` blocks |965| `true` | All MCP tools deferred. Claude Code sends the beta header even on Vertex AI and through proxies. Requests fail on Vertex AI models earlier than Sonnet 4.5 or Opus 4.5, or on proxies that do not support `tool_reference` blocks |

964| `auto` | Threshold mode: tools load upfront if they fit within 10% of the context window, deferred otherwise |966| `auto` | Threshold mode: tools load upfront if they fit within 10% of the context window, deferred otherwise |

965| `auto:<N>` | Threshold mode with a custom percentage, where `<N>` is 0-100 (e.g., `auto:5` for 5%) |967| `auto:N` | Threshold mode with a custom percentage, where `N` is 0-100. For example, `auto:5` for 5% |

966| `false` | All MCP tools loaded upfront, no deferral |968| `false` | All MCP tools loaded upfront, no deferral |

967 969 

968```bash theme={null}970```bash theme={null}

163export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'163export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'

164```164```

165 165 

166Background tasks such as session title generation use the small/fast model, normally a Haiku-class model. On Foundry, Claude Code defaults this to the primary model because not every account has a Haiku deployment. To use Haiku for background tasks, set `ANTHROPIC_DEFAULT_HAIKU_MODEL` to a Haiku deployment that is available in your account, as shown above.

167 

166For current and legacy model IDs, see [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). See [Model configuration](/en/model-config#pin-models-for-third-party-deployments) for the full list of environment variables.168For current and legacy model IDs, see [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). See [Model configuration](/en/model-config#pin-models-for-third-party-deployments) for the full list of environment variables.

167 169 

168[Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) is enabled automatically. To request a 1-hour cache TTL instead of the 5-minute default, set the following variable; cache writes with a 1-hour TTL are billed at a higher rate:170[Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) is enabled automatically. To request a 1-hour cache TTL instead of the 5-minute default, set the following variable; cache writes with a 1-hour TTL are billed at a higher rate:

537 537 

538### Verify active settings538### Verify active settings

539 539 

540Run `/status` inside Claude Code to see which settings sources are active and where they come from. The output shows each configuration layer (managed, user, project) along with its origin, such as `Enterprise managed settings (remote)`, `Enterprise managed settings (plist)`, `Enterprise managed settings (HKLM)`, `Enterprise managed settings (HKCU)`, or `Enterprise managed settings (file)`. If a settings file contains errors, `/status` reports the issue so you can fix it.540Run `/status` inside Claude Code to see which settings sources are active. The Status tab includes a `Setting sources` line that lists each layer Claude Code loaded for the current session, such as `User settings` or `Project local settings`. When [managed settings](/en/managed-settings) are in effect, the entry shows the delivery channel in parentheses, for example `Enterprise managed settings (remote)`, `(plist)`, `(HKLM)`, `(HKCU)`, or `(file)`. A layer appears in the list only when that source is loaded with at least one key, so an empty list means no settings sources were found.

541 

542The `Setting sources` line confirms which sources are being read. It does not show which layer supplied each individual key. The Config tab in the same dialog is an editor for a fixed set of toggles such as theme and verbose output, not a view of your `settings.json` contents. If a settings file contains errors, such as invalid JSON or a value that fails validation, `/status` reports the issue so you can fix it.

541 543 

542### Key points about the configuration system544### Key points about the configuration system

543 545