Documentation 2026-06-04 06:52 UTC to 2026-06-05 06:45 UTC

1534 uuid: str | None = None1534 uuid: str | None = None

1535```1535```

1536 1536 

1537The `subtype` field determines which other fields are populated. It is one of `"success"`, `"error_during_execution"`, `"error_max_turns"`, `"error_max_budget_usd"`, or `"error_max_structured_output_retries"`. The Python dataclass flattens all variants into one shape, so fields that don't apply to the returned subtype are `None`.

1538 

1539Several fields carry diagnostic detail when the conversation ends on an error:

1540 

1541* `is_error`: `True` when the conversation ended in an error state. Always `True` on the `error_*` subtypes. On `subtype="success"` it is `True` when the final model request failed, meaning the agent loop completed but the last API call returned an error.

1542* `api_error_status`: the HTTP status code of the terminating API error. `None` when the turn ended without one. Populated only on `subtype="success"`.

1543* `result`: text of the final assistant message on `subtype="success"`, or `None` on the `error_*` subtypes. When `subtype="success"` and `is_error=True`, this holds the API error string if one is available but can be empty, so check `api_error_status` and the preceding `AssistantMessage` content for detail.

1544* `errors`: loop-level error strings such as the max-turns message. Populated only on the `error_*` subtypes.

1545 

1537The `usage` dict contains the following keys when present:1546The `usage` dict contains the following keys when present:

1538 1547 

1539| Key | Type | Description |1548| Key | Type | Description |

443| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |443| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

444| `claude agents` | Open agent view |444| `claude agents` | Open agent view |

445| `claude agents --cwd <path>` | Open agent view scoped to sessions started under `<path>` |445| `claude agents --cwd <path>` | Open agent view scoped to sessions started under `<path>` |

446| `claude agents --json` | Print live sessions as a JSON array and exit. Each entry has `pid`, `cwd`, `kind`, and `startedAt`, plus `sessionId`, `name`, and `status` when set. Combine with `--cwd <path>` to filter |446| `claude agents --json` | Print live sessions as a JSON array and exit. Each entry has `pid`, `cwd`, `kind`, and `startedAt`, plus `sessionId`, `name`, and `status` when set. When `status` is `waiting`, `waitingFor` says what the session is blocked on, such as `permission prompt` or `input needed`. Combine with `--cwd <path>` to filter |

447| `claude attach <id>` | Attach to a session in this terminal |447| `claude attach <id>` | Attach to a session in this terminal |

448| `claude logs <id>` | Print the session's recent output |448| `claude logs <id>` | Print the session's recent output |

449| `claude stop <id>` | Stop a session. Also accepts `claude kill` |449| `claude stop <id>` | Stop a session. Also accepts `claude kill` |

42 42 

43A deep link never executes anything on its own. The link only chooses a directory and fills the prompt box. If you click a link from a page you do not trust, the prompt is still inert: nothing reaches the model until you read what was filled in and press Enter.43A deep link never executes anything on its own. The link only chooses a directory and fills the prompt box. If you click a link from a page you do not trust, the prompt is still inert: nothing reaches the model until you read what was filled in and press Enter.

44 44 

45When the session opens, a banner above the input shows that an external link launched it and which directory it selected. For prompts over 1,000 characters, the banner tells you to scroll and review the full text before pressing Enter, since long prompts can push instructions off screen. Permission rules, `CLAUDE.md`, and trust prompts for the selected directory apply the same way as for any other session.45When the session opens, a warning line below the input box reads `Prompt from an external link` and stays visible until you send or clear the prompt. For prompts over 1,000 characters, the warning includes the character count and tells you to scroll and review the full text before pressing Enter, since long prompts can push instructions off screen. Permission rules, `CLAUDE.md`, and trust prompts for the selected directory apply the same way as for any other session.

46 46 

47## Build a link47## Build a link

48 48 

88* The lookup only finds paths where you have already run Claude Code at least once.88* The lookup only finds paths where you have already run Claude Code at least once.

89* The link does not change which branch is checked out. The session opens in whatever state that directory is currently in.89* The link does not change which branch is checked out. The session opens in whatever state that directory is currently in.

90 90 

91The launched session shows which path it picked and when that clone last fetched from the remote, so you can tell if you are looking at stale code.91The welcome header shows which path it picked so you can confirm the right clone opened.

92 92 

93## Examples93## Examples

94 94 

313| `MCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE` | Maximum number of remote MCP servers (HTTP/SSE) to connect in parallel during startup (default: 20) |313| `MCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE` | Maximum number of remote MCP servers (HTTP/SSE) to connect in parallel during startup (default: 20) |

314| `MCP_SERVER_CONNECTION_BATCH_SIZE` | Maximum number of local MCP servers (stdio) to connect in parallel during startup (default: 3) |314| `MCP_SERVER_CONNECTION_BATCH_SIZE` | Maximum number of local MCP servers (stdio) to connect in parallel during startup (default: 3) |

315| `MCP_TIMEOUT` | Timeout in milliseconds for MCP server startup (default: 30000, or 30 seconds) |315| `MCP_TIMEOUT` | Timeout in milliseconds for MCP server startup (default: 30000, or 30 seconds) |

316| `MCP_TOOL_TIMEOUT` | Timeout in milliseconds for MCP tool execution (default: 100000000, about 28 hours). A per-server `timeout` field in `.mcp.json` overrides this for that server. Values below 1000 are floored to one second |316| `MCP_TOOL_TIMEOUT` | Timeout in milliseconds for MCP tool execution (default: 100000000, about 28 hours). A per-server `timeout` field in `.mcp.json` overrides this for that server. For the env variable, values below 1000 are floored to one second; for the per-server field, values below 1000 are ignored |

317| `NO_PROXY` | List of domains and IPs to which requests will be directly issued, bypassing proxy |317| `NO_PROXY` | List of domains and IPs to which requests will be directly issued, bypassing proxy |

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

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

108claude mcp add [options] <name> -- <command> [args...]108claude mcp add [options] <name> -- <command> [args...]

109 109 

110# Real example: Add Airtable server110# Real example: Add Airtable server

111claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \111claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \

112 -- npx -y airtable-mcp-server112 -- npx -y airtable-mcp-server

113```113```

114 114 

115<Note>115<Note>

116 **Important: Option ordering**116 **Important: Separate server arguments with `--`**

117 117 

118 All options (`--transport`, `--env`, `--scope`, `--header`) must come **before** the server name. The `--` (double dash) then separates the server name from the command and arguments that get passed to the MCP server.118 For stdio servers, the `--` (double dash) separates Claude's own options, such as `--transport`, `--env`, and `--scope`, from the command and arguments that run the server. Everything after `--` is passed to the server untouched.

119 119 

120 For example:120 For example:

121 121 

122 * `claude mcp add --transport stdio myserver -- npx server` → runs `npx server`122 * `claude mcp add --transport stdio myserver -- npx server` → runs `npx server`

123 * `claude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080` → runs `python server.py --port 8080` with `KEY=value` in environment123 * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → runs `python server.py --port 8080` with `KEY=value` in environment

124 124 

125 This prevents conflicts between Claude's flags and the server's flags.125 Without `--`, Claude Code would try to parse the server's flags, like `--port` above, as its own options.

126 

127 `--env` accepts multiple `KEY=value` pairs. If the server name comes directly after `--env`, the CLI reads the name as another pair and rejects it, so place at least one other option between `--env` and the server name, as in the examples above.

126</Note>128</Note>

127 129 

128### Option 4: Add a remote WebSocket server130### Option 4: Add a remote WebSocket server

192 * Use `/mcp` to authenticate with remote servers that require OAuth 2.0 authentication194 * Use `/mcp` to authenticate with remote servers that require OAuth 2.0 authentication

193</Tip>195</Tip>

194 196 

195The per-server `timeout` is a hard wall-clock limit per tool call, and progress notifications from the server do not extend it. Values below 1000 are floored to one second. For HTTP and SSE servers, the per-request fetch first-byte budget has a 60-second minimum regardless of this value, so only the tool-call watchdog honors smaller values.197The per-server `timeout` is a hard wall-clock limit per tool call, and progress notifications from the server do not extend it. Values below 1000 are ignored and fall through to `MCP_TOOL_TIMEOUT`, or to its default of about 28 hours when that variable is unset. {/* min-version: 2.1.162 */}Before v2.1.162, values below 1000 were floored to one second instead. For HTTP and SSE servers, the per-request fetch first-byte budget has a 60-second minimum.

196 198 

197### Plugin-provided MCP servers199### Plugin-provided MCP servers

198 200 

794 796 

795A server you've added in Claude Code takes [precedence](#scope-hierarchy-and-precedence) over a claude.ai connector that points at the same URL. When this happens, `/mcp` lists the connector as hidden and shows how to remove the duplicate if you'd rather use the connector.797A server you've added in Claude Code takes [precedence](#scope-hierarchy-and-precedence) over a claude.ai connector that points at the same URL. When this happens, `/mcp` lists the connector as hidden and shows how to remove the duplicate if you'd rather use the connector.

796 798 

799Some Anthropic-hosted connectors, such as Microsoft 365, Gmail, and Google Calendar, do not support local OAuth from Claude Code because the upstream identity provider only accepts the redirect URL that claude.ai registered. From v2.1.162, authenticating one of these hosts in `/mcp` shows a message directing you to connect it at Settings → Connectors on claude.ai instead. Once connected there, the connector appears in Claude Code automatically.

800 

797To disable claude.ai MCP servers in Claude Code, set the `ENABLE_CLAUDEAI_MCP_SERVERS` environment variable to `false`:801To disable claude.ai MCP servers in Claude Code, set the `ENABLE_CLAUDEAI_MCP_SERVERS` environment variable to `false`:

798 802 

799```bash theme={null}803```bash theme={null}

140 140 

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

142 142 

143Running [`/init`](/en/commands) in a repo that already has an `AGENTS.md` reads it and incorporates the relevant parts into the generated `CLAUDE.md`. It also reads other tool configs like `.cursorrules` and `.windsurfrules`.143Running [`/init`](/en/commands) in a repo that already has an `AGENTS.md` reads it and incorporates the relevant parts into the generated `CLAUDE.md`. It also reads other tool configs like `.cursorrules`, `.devin/rules/`, and `.windsurfrules`.

144 144 

145### How CLAUDE.md files load145### How CLAUDE.md files load

146 146 

203**`claude_code.tool`**203**`claude_code.tool`**

204 204 

205| Attribute | Description | Gated by |205| Attribute | Description | Gated by |

206| ----------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------- |206| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- |

207| `tool_name` | Tool name | |207| `tool_name` | Tool name | |

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

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

210| `agent_id` | Identifier of the subagent or teammate that ran the tool. Absent on the main session | |210| `agent_id` | Identifier of the subagent or teammate that ran the tool. Absent on the main session | |

211| `parent_agent_id` | Identifier of the agent that spawned this one. Absent for the main session and for agents spawned directly from it | |211| `parent_agent_id` | Identifier of the agent that spawned this one. Absent for the main session and for agents spawned directly from it | |

212| `tool_use_id` | The model's `tool_use` block id for this call. Matches the `tool_use_id` on the [tool\_result](#tool-result-event) and [tool\_decision](#tool-decision-event) events and in hook payloads, so you can join the span to those records | |

213| `gen_ai.tool.call.id` | Same value as `tool_use_id`. OpenTelemetry GenAI semantic convention | |

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

213| `full_command` | Command string for the Bash tool | `OTEL_LOG_TOOL_DETAILS` |215| `full_command` | Command string for the Bash tool | `OTEL_LOG_TOOL_DETAILS` |

214| `skill_name` | Skill name for the Skill tool | `OTEL_LOG_TOOL_DETAILS` |216| `skill_name` | Skill name for the Skill tool | `OTEL_LOG_TOOL_DETAILS` |

227**`claude_code.tool.execution`**229**`claude_code.tool.execution`**

228 230 

229| Attribute | Description | Gated by |231| Attribute | Description | Gated by |

230| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |232| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |

231| `duration_ms` | Time spent running the tool body | |233| `duration_ms` | Time spent running the tool body | |

234| `tool_use_id` | Same value as on the parent `claude_code.tool` span | |

235| `gen_ai.tool.call.id` | Same value as `tool_use_id`. OpenTelemetry GenAI semantic convention | |

232| `success` | `true` or `false` | |236| `success` | `true` or `false` | |

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

234 238 

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

821* `invocation_trigger`: How the skill was triggered (`"user-slash"`, `"claude-proactive"`, or `"nested-skill"`)825* `invocation_trigger`: How the skill was triggered (`"user-slash"`, `"claude-proactive"`, or `"nested-skill"`)

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

827* `skill.kind`: `"workflow"` when the skill is a workflow skill. Absent otherwise

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

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

825 830 

172* Jump to a symbol's definition172* Jump to a symbol's definition

173* Find all references to a symbol173* Find all references to a symbol

174* Get type information at a position174* Get type information at a position

175* List symbols in a file or workspace175* List symbols in a file

176* Search for a symbol by name across the workspace

176* Find implementations of an interface177* Find implementations of an interface

177* Trace call hierarchies178* Trace call hierarchies

178 179 

275* Responses are cached for 15 minutes, so repeated fetches of the same URL return quickly.276* Responses are cached for 15 minutes, so repeated fetches of the same URL return quickly.

276* When a URL redirects to a different host, WebFetch returns a text result that names the original URL and the redirect target instead of following it. Claude then fetches the new URL with a second WebFetch call.277* When a URL redirects to a different host, WebFetch returns a text result that names the original URL and the redirect target instead of following it. Claude then fetches the new URL with a second WebFetch call.

277 278 

278In the default and `acceptEdits` permission modes, WebFetch prompts the first time it reaches a new domain. To allow a domain in advance without a prompt, add a permission rule like `WebFetch(domain:example.com)`. The `auto` and `bypassPermissions` [permission modes](/en/permissions#permission-modes) skip the prompt entirely.279In the default and `acceptEdits` permission modes, WebFetch prompts the first time it reaches a new domain, except for a built-in set of preapproved documentation domains that fetch without a prompt. To allow another domain in advance without a prompt, add a permission rule like `WebFetch(domain:example.com)`. The `auto` and `bypassPermissions` [permission modes](/en/permissions#permission-modes) skip the prompt entirely.

280 

281An explicit `WebFetch(domain:...)` rule in `deny`, `ask`, or `allow` takes precedence over the preapproved set, so you can block a preapproved domain or require a prompt for it.

279 282 

280WebFetch sets a `User-Agent` header beginning with `Claude-User`, and an `Accept` header that prefers Markdown over HTML so servers that support content negotiation can return Markdown directly. [Sandbox](/en/sandboxing) network rules are configured separately, so a domain you want a sandboxed process to reach still needs an explicit sandbox permission rule.283WebFetch sets a `User-Agent` header beginning with `Claude-User`, and an `Accept` header that prefers Markdown over HTML so servers that support content negotiation can return Markdown directly. [Sandbox](/en/sandboxing) network rules are configured separately, so a domain you want a sandboxed process to reach still needs an explicit sandbox permission rule.

281 284 

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

56```56```

57 57 

58In PowerShell, run `curl.exe -sI` instead. PowerShell aliases `curl` to `Invoke-WebRequest`, which rejects the `-sI` flags.

59 

58An `HTTP/2 200` line means you reached the server. If you see no output, `Could not resolve host`, or a connection timeout, your network is blocking the connection. Common causes:60An `HTTP/2 200` line means you reached the server. If you see no output, `Could not resolve host`, or a connection timeout, your network is blocking the connection. Common causes:

59 61 

60* Corporate firewalls or proxies blocking `downloads.claude.ai`62* Corporate firewalls or proxies blocking `downloads.claude.ai`

5102. Search for "Claude Code"5102. Search for "Claude Code"

5113. Click **Uninstall**5113. Click **Uninstall**

512 512 

513To also remove extension data and reset all settings:513To also remove extension data and reset all settings, delete the extension's storage directory for your platform.

514 

515On macOS:

516 

517```bash theme={null}

518rm -rf ~/Library/"Application Support"/Code/User/globalStorage/anthropic.claude-code

519```

520 

521On Linux:

514 522 

515```bash theme={null}523```bash theme={null}

516rm -rf ~/.vscode/globalStorage/anthropic.claude-code524rm -rf ~/.config/Code/User/globalStorage/anthropic.claude-code

525```

526 

527On Windows, in PowerShell:

528 

529```powershell theme={null}

530Remove-Item -Recurse -Force "$env:APPDATA\Code\User\globalStorage\anthropic.claude-code"

517```531```

518 532 

519For additional help, see the [troubleshooting guide](/en/troubleshooting).533For additional help, see the [troubleshooting guide](/en/troubleshooting).