Documentation — Spybara

cli-reference.md +2 −2

Details

11You can start sessions, pipe content, resume conversations, and manage updates with these commands:11You can start sessions, pipe content, resume conversations, and manage updates with these commands:

12 12

14| :------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------- |14| :------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------ |

23| `claude auth login` | Sign in to your Anthropic account. Use `--email` to pre-fill your email address and `--sso` to force SSO authentication | `claude auth login --email user@example.com --sso` |23| `claude auth login` | Sign in to your Anthropic account. Use `--email` to pre-fill your email address, `--sso` to force SSO authentication, and `--console` to sign in with Anthropic Console for API usage billing instead of a Claude subscription | `claude auth login --console` |

env-vars.md +4 −1

Details

14| `ANTHROPIC_AUTH_TOKEN` | Custom value for the `Authorization` header (the value you set here will be prefixed with `Bearer `) |14| `ANTHROPIC_AUTH_TOKEN` | Custom value for the `Authorization` header (the value you set here will be prefixed with `Bearer `) |

15| `ANTHROPIC_BASE_URL` | Override the API endpoint to route requests through a proxy or gateway. When set to a non-first-party host, [MCP tool search](/en/mcp#scale-with-mcp-tool-search) is disabled by default. Set `ENABLE_TOOL_SEARCH=true` if your proxy forwards `tool_reference` blocks |15| `ANTHROPIC_BASE_URL` | Override the API endpoint to route requests through a proxy or gateway. When set to a non-first-party host, [MCP tool search](/en/mcp#scale-with-mcp-tool-search) is disabled by default. Set `ENABLE_TOOL_SEARCH=true` if your proxy forwards `tool_reference` blocks |

16| `ANTHROPIC_CUSTOM_HEADERS` | Custom headers to add to requests (`Name: Value` format, newline-separated for multiple headers) |16| `ANTHROPIC_CUSTOM_HEADERS` | Custom headers to add to requests (`Name: Value` format, newline-separated for multiple headers) |

17| `ANTHROPIC_CUSTOM_MODEL_OPTION` | Model ID to add as a custom entry in the `/model` picker. Use this to make a non-standard or gateway-specific model selectable without replacing built-in aliases. See [Model configuration](/en/model-config#add-a-custom-model-option) |

18| `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` | Display description for the custom model entry in the `/model` picker. Defaults to `Custom model (<model-id>)` when not set |

19| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | Display name for the custom model entry in the `/model` picker. Defaults to the model ID when not set |

62| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Interval for refreshing dynamic OpenTelemetry headers in milliseconds (default: 1740000 / 29 minutes). See [Dynamic headers](/en/monitoring-usage#dynamic-headers) |65| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Interval for refreshing dynamic OpenTelemetry headers in milliseconds (default: 1740000 / 29 minutes). See [Dynamic headers](/en/monitoring-usage#dynamic-headers) |

63| `CLAUDE_CODE_PLAN_MODE_REQUIRED` | Auto-set to `true` on [agent team](/en/agent-teams) teammates that require plan approval. Read-only: set by Claude Code when spawning teammates. See [require plan approval](/en/agent-teams#require-plan-approval-for-teammates) |66| `CLAUDE_CODE_PLAN_MODE_REQUIRED` | Auto-set to `true` on [agent team](/en/agent-teams) teammates that require plan approval. Read-only: set by Claude Code when spawning teammates. See [require plan approval](/en/agent-teams#require-plan-approval-for-teammates) |

64| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | Timeout in milliseconds for git operations when installing or updating plugins (default: 120000). Increase this value for large repositories or slow network connections. See [Git operations time out](/en/plugin-marketplaces#git-operations-time-out) |67| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | Timeout in milliseconds for git operations when installing or updating plugins (default: 120000). Increase this value for large repositories or slow network connections. See [Git operations time out](/en/plugin-marketplaces#git-operations-time-out) |

65| `CLAUDE_CODE_PLUGIN_SEED_DIR` | Path to a read-only plugin seed directory. Use this to bundle a pre-populated plugins directory into a container image. Claude Code registers marketplaces from this directory at startup and uses pre-cached plugins without re-cloning. See [Pre-populate plugins for containers](/en/plugin-marketplaces#pre-populate-plugins-for-containers) |68| `CLAUDE_CODE_PLUGIN_SEED_DIR` | Path to one or more read-only plugin seed directories, separated by `:` on Unix or `;` on Windows. Use this to bundle a pre-populated plugins directory into a container image. Claude Code registers marketplaces from these directories at startup and uses pre-cached plugins without re-cloning. See [Pre-populate plugins for containers](/en/plugin-marketplaces#pre-populate-plugins-for-containers) |

66| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | Set to `true` to allow the proxy to perform DNS resolution instead of the caller. Opt-in for environments where the proxy should handle hostname resolution |69| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | Set to `true` to allow the proxy to perform DNS resolution instead of the caller. Opt-in for environments where the proxy should handle hostname resolution |

67| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | Maximum time in milliseconds for [SessionEnd](/en/hooks#sessionend) hooks to complete (default: `1500`). Applies to both session exit and `/clear`. Per-hook `timeout` values are also capped by this budget |70| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | Maximum time in milliseconds for [SessionEnd](/en/hooks#sessionend) hooks to complete (default: `1500`). Applies to both session exit and `/clear`. Per-hook `timeout` values are also capped by this budget |

68| `CLAUDE_CODE_SHELL` | Override automatic shell detection. Useful when your login shell differs from your preferred working shell (for example, `bash` vs `zsh`) |71| `CLAUDE_CODE_SHELL` | Override automatic shell detection. Useful when your login shell differs from your preferred working shell (for example, `bash` vs `zsh`) |

hooks.md +47 −19

Details

18 18

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

20 <Frame>20 <Frame>

21 <img src="https://mintcdn.com/claude-code/lBsitdsGyD9caWJQ/images/hooks-lifecycle.svg?fit=max&auto=format&n=lBsitdsGyD9caWJQ&q=85&s=be3486ef2cf2563eb213b6cbbce93982" alt="Hook lifecycle diagram showing the sequence of hooks from SessionStart through the agentic loop (PreToolUse, PermissionRequest, PostToolUse, SubagentStart/Stop, TaskCompleted) to PostCompact and SessionEnd, with Elicitation and ElicitationResult nested inside MCP tool execution and WorktreeCreate, WorktreeRemove, Notification, ConfigChange, and InstructionsLoaded as standalone async events" width="520" height="1100" data-path="images/hooks-lifecycle.svg" />21 <img src="https://mintcdn.com/claude-code/2YzYcIR7V1VggfgF/images/hooks-lifecycle.svg?fit=max&auto=format&n=2YzYcIR7V1VggfgF&q=85&s=3004e6c5dc95c4fe7fa3eb40fdc4176c" alt="Hook lifecycle diagram showing the sequence of hooks from SessionStart through the agentic loop (PreToolUse, PermissionRequest, PostToolUse, SubagentStart/Stop, TaskCompleted) to Stop or StopFailure, TeammateIdle, PreCompact, PostCompact, and SessionEnd, with Elicitation and ElicitationResult nested inside MCP tool execution and WorktreeCreate, WorktreeRemove, Notification, ConfigChange, and InstructionsLoaded as standalone async events" width="520" height="1100" data-path="images/hooks-lifecycle.svg" />

22 </Frame>22 </Frame>

23</div>23</div>

24 24

36| `SubagentStart` | When a subagent is spawned |36| `SubagentStart` | When a subagent is spawned |

37| `SubagentStop` | When a subagent finishes |37| `SubagentStop` | When a subagent finishes |

38| `Stop` | When Claude finishes responding |38| `Stop` | When Claude finishes responding |

39| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |

39| `TeammateIdle` | When an [agent team](/en/agent-teams) teammate is about to go idle |40| `TeammateIdle` | When an [agent team](/en/agent-teams) teammate is about to go idle |

40| `TaskCompleted` | When a task is being marked as completed |41| `TaskCompleted` | When a task is being marked as completed |

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

166The `matcher` field is a regex string that filters when hooks fire. Use `"*"`, `""`, or omit `matcher` entirely to match all occurrences. Each event type matches on a different field:167The `matcher` field is a regex string that filters when hooks fire. Use `"*"`, `""`, or omit `matcher` entirely to match all occurrences. Each event type matches on a different field:

167 168

169| :-------------------------------------------------------------------------------------------------------------------- | :------------------------ | :--------------------------------------------------------------------------------- |170| :---------------------------------------------------------------------------------------------- | :------------------------ | :------------------------------------------------------------------------------------------------------------------------ |

180| `InstructionsLoaded` | load reason | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` |

181| `Elicitation` | MCP server name | your configured MCP server names |

182| `ElicitationResult` | MCP server name | same values as `Elicitation` |

183| `UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove` | no matcher support | always fires on every occurrence |

179 184

180The matcher is a regex, so `Edit|Write` matches either tool and `Notebook.*` matches any tool starting with Notebook. The matcher runs against a field from the [JSON input](#hook-input-and-output) that Claude Code sends to your hook on stdin. For tool events, that field is `tool_name`. Each [hook event](#hook-events) section lists the full set of matcher values and the input schema for that event.185The matcher is a regex, so `Edit|Write` matches either tool and `Notebook.*` matches any tool starting with Notebook. The matcher runs against a field from the [JSON input](#hook-input-and-output) that Claude Code sends to your hook on stdin. For tool events, that field is `tool_name`. Each [hook event](#hook-events) section lists the full set of matcher values and the input schema for that event.

181 186

199}204}

200```205```

201 206

202`UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, and `InstructionsLoaded` don't support matchers and always fire on every occurrence. If you add a `matcher` field to these events, it is silently ignored.207`UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCompleted`, `WorktreeCreate`, and `WorktreeRemove` don't support matchers and always fire on every occurrence. If you add a `matcher` field to these events, it is silently ignored.

203 208

204#### Match MCP tools209#### Match MCP tools

205 210

440 445

441### Common input fields446### Common input fields

442 447

443All hook events receive these fields as JSON, in addition to event-specific fields documented in each [hook event](#hook-events) section. For command hooks, this JSON arrives via stdin. For HTTP hooks, it arrives as the POST request body.448Hook events receive these fields as JSON, in addition to event-specific fields documented in each [hook event](#hook-events) section. For command hooks, this JSON arrives via stdin. For HTTP hooks, it arrives as the POST request body.

444 449

445| Field | Description |450| Field | Description |

446| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |451| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

449| `cwd` | Current working directory when the hook is invoked |454| `cwd` | Current working directory when the hook is invoked |

450| `permission_mode` | Current [permission mode](/en/permissions#permission-modes): `"default"`, `"plan"`, `"acceptEdits"`, `"dontAsk"`, or `"bypassPermissions"` |455| `permission_mode` | Current [permission mode](/en/permissions#permission-modes): `"default"`, `"plan"`, `"acceptEdits"`, `"dontAsk"`, or `"bypassPermissions"`. Not all events receive this field: see each event's JSON example below to check |

452 457

453When running with `--agent` or inside a subagent, two additional fields are included:458When running with `--agent` or inside a subagent, two additional fields are included:

514| `TeammateIdle` | Yes | Prevents the teammate from going idle (teammate continues working) |519| `TeammateIdle` | Yes | Prevents the teammate from going idle (teammate continues working) |

515| `TaskCompleted` | Yes | Prevents the task from being marked as completed |520| `TaskCompleted` | Yes | Prevents the task from being marked as completed |

516| `ConfigChange` | Yes | Blocks the configuration change from taking effect (except `policy_settings`) |521| `ConfigChange` | Yes | Blocks the configuration change from taking effect (except `policy_settings`) |

522| `StopFailure` | No | Output and exit code are ignored |

517| `PostToolUse` | No | Shows stderr to Claude (tool already ran) |523| `PostToolUse` | No | Shows stderr to Claude (tool already ran) |

518| `PostToolUseFailure` | No | Shows stderr to Claude (tool already failed) |524| `PostToolUseFailure` | No | Shows stderr to Claude (tool already failed) |

519| `Notification` | No | Shows stderr to user only |525| `Notification` | No | Shows stderr to user only |

574Not every event supports blocking or controlling behavior through JSON. The events that do each use a different set of fields to express that decision. Use this table as a quick reference before writing a hook:580Not every event supports blocking or controlling behavior through JSON. The events that do each use a different set of fields to express that decision. Use this table as a quick reference before writing a hook:

575 581

577| :------------------------------------------------------------------------------------ | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |583| :------------------------------------------------------------------------------------------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

579| TeammateIdle, TaskCompleted | Exit code or `continue: false` | Exit code 2 blocks the action with stderr feedback. JSON `{"continue": false, "stopReason": "..."}` also stops the teammate entirely, matching `Stop` hook behavior |585| TeammateIdle, TaskCompleted | Exit code or `continue: false` | Exit code 2 blocks the action with stderr feedback. JSON `{"continue": false, "stopReason": "..."}` also stops the teammate entirely, matching `Stop` hook behavior |

586 592

587Here are examples of each pattern in action:593Here are examples of each pattern in action:

588 594

661 "session_id": "abc123",667 "session_id": "abc123",

662 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",668 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",

663 "cwd": "/Users/...",669 "cwd": "/Users/...",

664 "permission_mode": "default",

665 "hook_event_name": "SessionStart",670 "hook_event_name": "SessionStart",

666 "source": "startup",671 "source": "startup",

667 "model": "claude-sonnet-4-6"672 "model": "claude-sonnet-4-6"

732 737

733Fires when a `CLAUDE.md` or `.claude/rules/*.md` file is loaded into context. This event fires at session start for eagerly-loaded files and again later when files are lazily loaded, for example when Claude accesses a subdirectory that contains a nested `CLAUDE.md` or when conditional rules with `paths:` frontmatter match. The hook does not support blocking or decision control. It runs asynchronously for observability purposes.738Fires when a `CLAUDE.md` or `.claude/rules/*.md` file is loaded into context. This event fires at session start for eagerly-loaded files and again later when files are lazily loaded, for example when Claude accesses a subdirectory that contains a nested `CLAUDE.md` or when conditional rules with `paths:` frontmatter match. The hook does not support blocking or decision control. It runs asynchronously for observability purposes.

734 739

735InstructionsLoaded does not support matchers and fires on every load occurrence.740The matcher runs against `load_reason`. For example, use `"matcher": "session_start"` to fire only for files loaded at session start, or `"matcher": "path_glob_match|nested_traversal"` to fire only for lazy loads.

736 741

737#### InstructionsLoaded input742#### InstructionsLoaded input

738 743

752 "session_id": "abc123",757 "session_id": "abc123",

753 "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",758 "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",

754 "cwd": "/Users/my-project",759 "cwd": "/Users/my-project",

755 "permission_mode": "default",

756 "hook_event_name": "InstructionsLoaded",760 "hook_event_name": "InstructionsLoaded",

757 "file_path": "/Users/my-project/CLAUDE.md",761 "file_path": "/Users/my-project/CLAUDE.md",

758 "memory_type": "Project",762 "memory_type": "Project",

1182 "session_id": "abc123",1186 "session_id": "abc123",

1183 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",1187 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",

1184 "cwd": "/Users/...",1188 "cwd": "/Users/...",

1185 "permission_mode": "default",

1186 "hook_event_name": "Notification",1189 "hook_event_name": "Notification",

1187 "message": "Claude needs your permission to use Bash",1190 "message": "Claude needs your permission to use Bash",

1188 "title": "Permission needed",1191 "title": "Permission needed",

1209 "session_id": "abc123",1212 "session_id": "abc123",

1210 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",1213 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",

1211 "cwd": "/Users/...",1214 "cwd": "/Users/...",

1212 "permission_mode": "default",

1213 "hook_event_name": "SubagentStart",1215 "hook_event_name": "SubagentStart",

1214 "agent_id": "agent-abc123",1216 "agent_id": "agent-abc123",

1215 "agent_type": "Explore"1217 "agent_type": "Explore"

1259### Stop1261### Stop

1260 1262

1261Runs when the main Claude Code agent has finished responding. Does not run if1263Runs when the main Claude Code agent has finished responding. Does not run if

1262the stoppage occurred due to a user interrupt.1264the stoppage occurred due to a user interrupt. API errors fire

1265[StopFailure](#stopfailure) instead.

1263 1266

1264#### Stop input1267#### Stop input

1265 1268

1293}1296}

1294```1297```

1295 1298

1299### StopFailure

1300

1301Runs instead of [Stop](#stop) when the turn ends due to an API error. Output and exit code are ignored. Use this to log failures, send alerts, or take recovery actions when Claude cannot complete a response due to rate limits, authentication problems, or other API errors.

1302

1303#### StopFailure input

1304

1305In addition to the [common input fields](#common-input-fields), StopFailure hooks receive `error`, optional `error_details`, and optional `last_assistant_message`. The `error` field identifies the error type and is used for matcher filtering.

1306

1307| Field | Description |

1308| :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1309| `error` | Error type: `rate_limit`, `authentication_failed`, `billing_error`, `invalid_request`, `server_error`, `max_output_tokens`, or `unknown` |

1310| `error_details` | Additional details about the error, when available |

1311| `last_assistant_message` | The rendered error text shown in the conversation. Unlike `Stop` and `SubagentStop`, where this field holds Claude's conversational output, for `StopFailure` it contains the API error string itself, such as `"API Error: Rate limit reached"` |

1312

1313```json theme={null}

1314{

1315 "session_id": "abc123",

1316 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",

1317 "cwd": "/Users/...",

1318 "hook_event_name": "StopFailure",

1319 "error": "rate_limit",

1320 "error_details": "429 Too Many Requests",

1321 "last_assistant_message": "API Error: Rate limit reached"

1322}

1323```

1324

1325StopFailure hooks have no decision control. They run for notification and logging purposes only.

1326

1296### TeammateIdle1327### TeammateIdle

1297 1328

1298Runs when an [agent team](/en/agent-teams) teammate is about to go idle after finishing its turn. Use this to enforce quality gates before a teammate stops working, such as requiring passing lint checks or verifying that output files exist.1329Runs when an [agent team](/en/agent-teams) teammate is about to go idle after finishing its turn. Use this to enforce quality gates before a teammate stops working, such as requiring passing lint checks or verifying that output files exist.

1440 "session_id": "abc123",1471 "session_id": "abc123",

1441 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",1472 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",

1442 "cwd": "/Users/...",1473 "cwd": "/Users/...",

1443 "permission_mode": "default",

1444 "hook_event_name": "ConfigChange",1474 "hook_event_name": "ConfigChange",

1445 "source": "project_settings",1475 "source": "project_settings",

1446 "file_path": "/Users/.../my-project/.claude/settings.json"1476 "file_path": "/Users/.../my-project/.claude/settings.json"

1571 "session_id": "abc123",1601 "session_id": "abc123",

1572 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",1602 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",

1573 "cwd": "/Users/...",1603 "cwd": "/Users/...",

1574 "permission_mode": "default",

1575 "hook_event_name": "PreCompact",1604 "hook_event_name": "PreCompact",

1576 "trigger": "manual",1605 "trigger": "manual",

1577 "custom_instructions": ""1606 "custom_instructions": ""

1598 "session_id": "abc123",1627 "session_id": "abc123",

1599 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",1628 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",

1600 "cwd": "/Users/...",1629 "cwd": "/Users/...",

1601 "permission_mode": "default",

1602 "hook_event_name": "PostCompact",1630 "hook_event_name": "PostCompact",

1603 "trigger": "manual",1631 "trigger": "manual",

1604 "compact_summary": "Summary of the compacted conversation..."1632 "compact_summary": "Summary of the compacted conversation..."

1631 "session_id": "abc123",1659 "session_id": "abc123",

1632 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",1660 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",

1633 "cwd": "/Users/...",1661 "cwd": "/Users/...",

1634 "permission_mode": "default",

1635 "hook_event_name": "SessionEnd",1662 "hook_event_name": "SessionEnd",

1636 "reason": "other"1663 "reason": "other"

1637}1664}

1787* `PreCompact`1814* `PreCompact`

1788* `SessionEnd`1815* `SessionEnd`

1789* `SessionStart`1816* `SessionStart`

1817* `StopFailure`

1790* `SubagentStart`1818* `SubagentStart`

1791* `TeammateIdle`1819* `TeammateIdle`

1792* `WorktreeCreate`1820* `WorktreeCreate`

hooks-guide.md +7 −2

Details

347| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |

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

463Each event type matches on a specific field. Matchers support exact strings and regex patterns:464Each event type matches on a specific field. Matchers support exact strings and regex patterns:

464 465

466| :---------------------------------------------------------------------------------------------- | :------------------------ | :--------------------------------------------------------------------------------- |467| :---------------------------------------------------------------------------------------------- | :------------------------ | :------------------------------------------------------------------------------------------------------------------------ |

476| `StopFailure` | error type | `rate_limit`, `authentication_failed`, `billing_error`, `invalid_request`, `server_error`, `max_output_tokens`, `unknown` |

477| `InstructionsLoaded` | load reason | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` |

478| `Elicitation` | MCP server name | your configured MCP server names |

479| `ElicitationResult` | MCP server name | same values as `Elicitation` |

476 481

477A few more examples showing matchers on different event types:482A few more examples showing matchers on different event types:

668* Hook timeout is 10 minutes by default, configurable per hook with the `timeout` field (in seconds).673* Hook timeout is 10 minutes by default, configurable per hook with the `timeout` field (in seconds).

669* `PostToolUse` hooks cannot undo actions since the tool has already executed.674* `PostToolUse` hooks cannot undo actions since the tool has already executed.

670* `PermissionRequest` hooks do not fire in [non-interactive mode](/en/headless) (`-p`). Use `PreToolUse` hooks for automated permission decisions.675* `PermissionRequest` hooks do not fire in [non-interactive mode](/en/headless) (`-p`). Use `PreToolUse` hooks for automated permission decisions.

671* `Stop` hooks fire whenever Claude finishes responding, not only at task completion. They do not fire on user interrupts.676* `Stop` hooks fire whenever Claude finishes responding, not only at task completion. They do not fire on user interrupts. API errors fire [StopFailure](/en/hooks#stopfailure) instead.

672 677

673### Hook not firing678### Hook not firing

674 679

model-config.md +16 −0

Details

1831. In [status line](/en/statusline) (if configured)1831. In [status line](/en/statusline) (if configured)

1842. In `/status`, which also displays your account information.1842. In `/status`, which also displays your account information.

185 185

186## Add a custom model option

187

188Use `ANTHROPIC_CUSTOM_MODEL_OPTION` to add a single custom entry to the `/model` picker without replacing the built-in aliases. This is useful for LLM gateway deployments or testing model IDs that Claude Code does not list by default.

189

190This example sets all three variables to make a gateway-routed Opus deployment selectable:

191

192```bash theme={null}

193export ANTHROPIC_CUSTOM_MODEL_OPTION="my-gateway/claude-opus-4-6"

194export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Opus via Gateway"

195export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Custom deployment routed through the internal LLM gateway"

196```

197

198The custom entry appears at the bottom of the `/model` picker. `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` and `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` are optional. If omitted, the model ID is used as the name and the description defaults to `Custom model (<model-id>)`.

199

200Claude Code skips validation for the model ID set in `ANTHROPIC_CUSTOM_MODEL_OPTION`, so you can use any string your API endpoint accepts.

201

186## Environment variables202## Environment variables

187 203

188You can use the following environment variables, which must be full **model204You can use the following environment variables, which must be full **model

overview.md +5 −5

Details

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

23 **macOS, Linux, WSL:**23 **macOS, Linux, WSL:**

24 24

~~25 ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}~~25 ```bash theme={null}

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

27 ```27 ```

28 28

29 **Windows PowerShell:**29 **Windows PowerShell:**

30 30

~~31 ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}~~31 ```powershell theme={null}

32 irm https://claude.ai/install.ps1 | iex32 irm https://claude.ai/install.ps1 | iex

33 ```33 ```

34 34

35 **Windows CMD:**35 **Windows CMD:**

36 36

~~37 ```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}~~37 ```batch theme={null}

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

39 ```39 ```

40 40

46 </Tab>46 </Tab>

47 47

48 <Tab title="Homebrew">48 <Tab title="Homebrew">

~~49 ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}~~49 ```bash theme={null}

50 brew install --cask claude-code50 brew install --cask claude-code

51 ```51 ```

52 52

56 </Tab>56 </Tab>

57 57

58 <Tab title="WinGet">58 <Tab title="WinGet">

~~59 ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}~~59 ```powershell theme={null}

60 winget install Anthropic.ClaudeCode60 winget install Anthropic.ClaudeCode

61 ```61 ```

62 62

plugin-marketplaces.md +3 −1

Details

221 221

223| ------------- | ------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------- |223| ------------- | ------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------- |

562 562

563For container images and CI environments, you can pre-populate a plugins directory at build time so Claude Code starts with marketplaces and plugins already available, without cloning anything at runtime. Set the `CLAUDE_CODE_PLUGIN_SEED_DIR` environment variable to point at this directory.563For container images and CI environments, you can pre-populate a plugins directory at build time so Claude Code starts with marketplaces and plugins already available, without cloning anything at runtime. Set the `CLAUDE_CODE_PLUGIN_SEED_DIR` environment variable to point at this directory.

564 564

565To layer multiple seed directories, separate paths with `:` on Unix or `;` on Windows. Claude Code searches each directory in order, and the first seed that contains a given marketplace or plugin cache wins.

566

565The seed directory mirrors the structure of `~/.claude/plugins`:567The seed directory mirrors the structure of `~/.claude/plugins`:

566 568

567```569```

plugins-reference.md +31 −21

Details

100}100}

101```101```

102 102

103**Available events**:103Plugin hooks respond to the same lifecycle events as [user-defined hooks](/en/hooks):

~~104~~ 104

105* `PreToolUse`: Before Claude uses any tool105| Event | When it fires |

106* `PostToolUse`: After Claude successfully uses any tool106| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |

107* `PostToolUseFailure`: After Claude tool execution fails107| `SessionStart` | When a session begins or resumes |

108* `PermissionRequest`: When a permission dialog is shown108| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |

109* `UserPromptSubmit`: When user submits a prompt109| `PreToolUse` | Before a tool call executes. Can block it |

110* `Notification`: When Claude Code sends notifications110| `PermissionRequest` | When a permission dialog appears |

111* `Stop`: When Claude attempts to stop111| `PostToolUse` | After a tool call succeeds |

112* `SubagentStart`: When a subagent is started112| `PostToolUseFailure` | After a tool call fails |

113* `SubagentStop`: When a subagent attempts to stop113| `Notification` | When Claude Code sends a notification |

114* `SessionStart`: At the beginning of sessions114| `SubagentStart` | When a subagent is spawned |

115* `SessionEnd`: At the end of sessions115| `SubagentStop` | When a subagent finishes |

116* `TeammateIdle`: When an agent team teammate is about to go idle116| `Stop` | When Claude finishes responding |

117* `TaskCompleted`: When a task is being marked as completed117| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |

118* `PreCompact`: Before conversation history is compacted118| `TeammateIdle` | When an [agent team](/en/agent-teams) teammate is about to go idle |

119* `PostCompact`: After conversation history is compacted119| `TaskCompleted` | When a task is being marked as completed |

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

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

122| `WorktreeCreate` | When a worktree is being created via `--worktree` or `isolation: "worktree"`. Replaces default git behavior |

123| `WorktreeRemove` | When a worktree is being removed, either at session exit or when a subagent finishes |

124| `PreCompact` | Before context compaction |

125| `PostCompact` | After context compaction completes |

126| `Elicitation` | When an MCP server requests user input during a tool call |

127| `ElicitationResult` | After a user responds to an MCP elicitation, before the response is sent back to the server |

128| `SessionEnd` | When a session terminates |

120 129

121**Hook types**:130**Hook types**:

122 131

123* `command`: Execute shell commands or scripts132* `command`: execute shell commands or scripts

124* `prompt`: Evaluate a prompt with an LLM (uses `$ARGUMENTS` placeholder for context)133* `http`: send the event JSON as a POST request to a URL

125* `agent`: Run an agentic verifier with tools for complex verification tasks134* `prompt`: evaluate a prompt with an LLM (uses `$ARGUMENTS` placeholder for context)

135* `agent`: run an agentic verifier with tools for complex verification tasks

126 136

127### MCP servers137### MCP servers

128 138

680 690

6811. Verify the event name is correct (case-sensitive): `PostToolUse`, not `postToolUse`6911. Verify the event name is correct (case-sensitive): `PostToolUse`, not `postToolUse`

6822. Check the matcher pattern matches your tools: `"matcher": "Write|Edit"` for file operations6922. Check the matcher pattern matches your tools: `"matcher": "Write|Edit"` for file operations

6833. Confirm the hook type is valid: `command`, `prompt`, or `agent`6933. Confirm the hook type is valid: `command`, `http`, `prompt`, or `agent`

684 694

685### MCP server troubleshooting695### MCP server troubleshooting

686 696

sandboxing.md +7 −6

Details

124 "sandbox": {124 "sandbox": {

125 "enabled": true,125 "enabled": true,

126 "filesystem": {126 "filesystem": {

127 "allowWrite": ["~/.kube", "//tmp/build"]127 "allowWrite": ["~/.kube", "/tmp/build"]

128 }128 }

129 }129 }

130}130}

132 132

133These paths are enforced at the OS level, so all commands running inside the sandbox, including their child processes, respect them. This is the recommended approach when a tool needs write access to a specific location, rather than excluding the tool from the sandbox entirely with `excludedCommands`.133These paths are enforced at the OS level, so all commands running inside the sandbox, including their child processes, respect them. This is the recommended approach when a tool needs write access to a specific location, rather than excluding the tool from the sandbox entirely with `excludedCommands`.

134 134

135When `allowWrite` (or `denyWrite`/`denyRead`/`allowRead`) is defined in multiple [settings scopes](/en/settings#settings-precedence), the arrays are **merged**, meaning paths from every scope are combined, not replaced. For example, if managed settings allow writes to `//opt/company-tools` and a user adds `~/.kube` in their personal settings, both paths are included in the final sandbox configuration. This means users and projects can extend the list without duplicating or overriding paths set by higher-priority scopes.135When `allowWrite` (or `denyWrite`/`denyRead`/`allowRead`) is defined in multiple [settings scopes](/en/settings#settings-precedence), the arrays are **merged**, meaning paths from every scope are combined, not replaced. For example, if managed settings allow writes to `/opt/company-tools` and a user adds `~/.kube` in their personal settings, both paths are included in the final sandbox configuration. This means users and projects can extend the list without duplicating or overriding paths set by higher-priority scopes.

136 136

137Path prefixes control how paths are resolved:137Path prefixes control how paths are resolved:

138 138

140| :---------------- | :------------------------------------------ | :------------------------------------- |140| :---------------- | :------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ |

141| `//` | Absolute path from filesystem root | `//tmp/build` becomes `/tmp/build` |141| `/` | Absolute path from filesystem root | `/tmp/build` stays `/tmp/build` |

142| `~/` | Relative to home directory | `~/.kube` becomes `$HOME/.kube` |142| `~/` | Relative to home directory | `~/.kube` becomes `$HOME/.kube` |

144| `./` or no prefix | Relative path (resolved by sandbox runtime) | `./output` |144

145The older `//path` prefix for absolute paths still works. If you previously used single-slash `/path` expecting project-relative resolution, switch to `./path`. This syntax differs from [Read and Edit permission rules](/en/permissions#read-and-edit), which use `//path` for absolute and `/path` for project-relative. Sandbox filesystem paths use standard conventions: `/tmp/build` is an absolute path.

145 146

146You can also deny write or read access using `sandbox.filesystem.denyWrite` and `sandbox.filesystem.denyRead`. These are merged with any paths from `Edit(...)` and `Read(...)` permission rules. To re-allow reading specific paths within a denied region, use `sandbox.filesystem.allowRead`, which takes precedence over `denyRead`. When `allowManagedReadPathsOnly` is enabled in managed settings, only managed `allowRead` entries are respected; user, project, and local `allowRead` entries are ignored.147You can also deny write or read access using `sandbox.filesystem.denyWrite` and `sandbox.filesystem.denyRead`. These are merged with any paths from `Edit(...)` and `Read(...)` permission rules. To re-allow reading specific paths within a denied region, use `sandbox.filesystem.allowRead`, which takes precedence over `denyRead`. When `allowManagedReadPathsOnly` is enabled in managed settings, only managed `allowRead` entries are respected; user, project, and local `allowRead` entries are ignored.

147 148

settings.md +10 −9

Details

205 205

206| Key | Description | Example |206| Key | Description | Example |

207| :--------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |207| :--------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |

209| `terminalProgressBarEnabled` | Show the terminal progress bar in supported terminals like Windows Terminal and iTerm2. Default: `true`. Appears in `/config` as **Terminal progress bar** | `false` |209| `terminalProgressBarEnabled` | Show the terminal progress bar in supported terminals like Windows Terminal and iTerm2. Default: `true`. Appears in `/config` as **Terminal progress bar** | `false` |

210 210

211### Worktree settings211### Worktree settings

255| `allowUnsandboxedCommands` | Allow commands to run outside the sandbox via the `dangerouslyDisableSandbox` parameter. When set to `false`, the `dangerouslyDisableSandbox` escape hatch is completely disabled and all commands must run sandboxed (or be in `excludedCommands`). Useful for enterprise policies that require strict sandboxing. Default: true | `false` |255| `allowUnsandboxedCommands` | Allow commands to run outside the sandbox via the `dangerouslyDisableSandbox` parameter. When set to `false`, the `dangerouslyDisableSandbox` escape hatch is completely disabled and all commands must run sandboxed (or be in `excludedCommands`). Useful for enterprise policies that require strict sandboxing. Default: true | `false` |

256| `filesystem.allowWrite` | Additional paths where sandboxed commands can write. Arrays are merged across all settings scopes: user, project, and managed paths are combined, not replaced. Also merged with paths from `Edit(...)` allow permission rules. See [path prefixes](#sandbox-path-prefixes) below. | `["//tmp/build", "~/.kube"]` |256| `filesystem.allowWrite` | Additional paths where sandboxed commands can write. Arrays are merged across all settings scopes: user, project, and managed paths are combined, not replaced. Also merged with paths from `Edit(...)` allow permission rules. See [path prefixes](#sandbox-path-prefixes) below. | `["/tmp/build", "~/.kube"]` |

257| `filesystem.denyWrite` | Paths where sandboxed commands cannot write. Arrays are merged across all settings scopes. Also merged with paths from `Edit(...)` deny permission rules. | `["//etc", "//usr/local/bin"]` |257| `filesystem.denyWrite` | Paths where sandboxed commands cannot write. Arrays are merged across all settings scopes. Also merged with paths from `Edit(...)` deny permission rules. | `["/etc", "/usr/local/bin"]` |

258| `filesystem.denyRead` | Paths where sandboxed commands cannot read. Arrays are merged across all settings scopes. Also merged with paths from `Read(...)` deny permission rules. | `["~/.aws/credentials"]` |258| `filesystem.denyRead` | Paths where sandboxed commands cannot read. Arrays are merged across all settings scopes. Also merged with paths from `Read(...)` deny permission rules. | `["~/.aws/credentials"]` |

259| `filesystem.allowRead` | Paths to re-allow reading within `denyRead` regions. Takes precedence over `denyRead`. Arrays are merged across all settings scopes. Use this to create workspace-only read access patterns. | `["."]` |259| `filesystem.allowRead` | Paths to re-allow reading within `denyRead` regions. Takes precedence over `denyRead`. Arrays are merged across all settings scopes. Use this to create workspace-only read access patterns. | `["."]` |

260| `filesystem.allowManagedReadPathsOnly` | (Managed settings only) Only `allowRead` paths from managed settings are respected. `allowRead` entries from user, project, and local settings are ignored. Default: false | `true` |260| `filesystem.allowManagedReadPathsOnly` | (Managed settings only) Only `allowRead` paths from managed settings are respected. `allowRead` entries from user, project, and local settings are ignored. Default: false | `true` |

273Paths in `filesystem.allowWrite`, `filesystem.denyWrite`, `filesystem.denyRead`, and `filesystem.allowRead` support these prefixes:273Paths in `filesystem.allowWrite`, `filesystem.denyWrite`, `filesystem.denyRead`, and `filesystem.allowRead` support these prefixes:

274 274

276| :---------------- | :------------------------------------------ | :------------------------------------- |276| :---------------- | :------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ |

277| `//` | Absolute path from filesystem root | `//tmp/build` becomes `/tmp/build` |277| `/` | Absolute path from filesystem root | `/tmp/build` stays `/tmp/build` |

278| `~/` | Relative to home directory | `~/.kube` becomes `$HOME/.kube` |278| `~/` | Relative to home directory | `~/.kube` becomes `$HOME/.kube` |

280| `./` or no prefix | Relative path (resolved by sandbox runtime) | `./output` |280

281The older `//path` prefix for absolute paths still works. If you previously used single-slash `/path` expecting project-relative resolution, switch to `./path`. This syntax differs from [Read and Edit permission rules](/en/permissions#read-and-edit), which use `//path` for absolute and `/path` for project-relative. Sandbox filesystem paths use standard conventions: `/tmp/build` is an absolute path.

281 282

282**Configuration example:**283**Configuration example:**

283 284

288 "autoAllowBashIfSandboxed": true,289 "autoAllowBashIfSandboxed": true,

289 "excludedCommands": ["docker"],290 "excludedCommands": ["docker"],

290 "filesystem": {291 "filesystem": {

291 "allowWrite": ["//tmp/build", "~/.kube"],292 "allowWrite": ["/tmp/build", "~/.kube"],

292 "denyRead": ["~/.aws/credentials"]293 "denyRead": ["~/.aws/credentials"]

293 },294 },

294 "network": {295 "network": {

438For example, if your user settings allow `Bash(npm run *)` but a project's shared settings deny it, the project setting takes precedence and the command is blocked.439For example, if your user settings allow `Bash(npm run *)` but a project's shared settings deny it, the project setting takes precedence and the command is blocked.

439 440

440<Note>441<Note>

441 **Array settings merge across scopes.** When the same array-valued setting (such as `sandbox.filesystem.allowWrite` or `permissions.allow`) appears in multiple scopes, the arrays are **concatenated and deduplicated**, not replaced. This means lower-priority scopes can add entries without overriding those set by higher-priority scopes, and vice versa. For example, if managed settings set `allowWrite` to `["//opt/company-tools"]` and a user adds `["~/.kube"]`, both paths are included in the final configuration.442 **Array settings merge across scopes.** When the same array-valued setting (such as `sandbox.filesystem.allowWrite` or `permissions.allow`) appears in multiple scopes, the arrays are **concatenated and deduplicated**, not replaced. This means lower-priority scopes can add entries without overriding those set by higher-priority scopes, and vice versa. For example, if managed settings set `allowWrite` to `["/opt/company-tools"]` and a user adds `["~/.kube"]`, both paths are included in the final configuration.

442</Note>443</Note>

443 444

444### Verify active settings445### Verify active settings

sub-agents.md +1 −1

Details

384 384

385##### Persistent memory tips385##### Persistent memory tips

386 386

387* `user` is the recommended default scope. Use `project` or `local` when the subagent's knowledge is only relevant to a specific codebase.387* `project` is the recommended default scope. It makes subagent knowledge shareable via version control. Use `user` when the subagent's knowledge is broadly applicable across projects, or `local` when the knowledge should not be checked into version control.

388* Ask the subagent to consult its memory before starting work: "Review this PR, and check your memory for patterns you've seen before."388* Ask the subagent to consult its memory before starting work: "Review this PR, and check your memory for patterns you've seen before."

389* Ask the subagent to update its memory after completing a task: "Now that you're done, save what you learned to your memory." Over time, this builds a knowledge base that makes the subagent more effective.389* Ask the subagent to update its memory after completing a task: "Now that you're done, save what you learned to your memory." Over time, this builds a knowledge base that makes the subagent more effective.

390* Include memory instructions directly in the subagent's markdown file so it proactively maintains its own knowledge base:390* Include memory instructions directly in the subagent's markdown file so it proactively maintains its own knowledge base:

vs-code.md +23 −2

Details

85The prompt box supports several features:85The prompt box supports several features:

86 86

87* **Permission modes**: click the mode indicator at the bottom of the prompt box to switch modes. In normal mode, Claude asks permission before each action. In Plan mode, Claude describes what it will do and waits for approval before making changes. VS Code automatically opens the plan as a full markdown document where you can add inline comments to give feedback before Claude begins. In auto-accept mode, Claude makes edits without asking. Set the default in VS Code settings under `claudeCode.initialPermissionMode`.87* **Permission modes**: click the mode indicator at the bottom of the prompt box to switch modes. In normal mode, Claude asks permission before each action. In Plan mode, Claude describes what it will do and waits for approval before making changes. VS Code automatically opens the plan as a full markdown document where you can add inline comments to give feedback before Claude begins. In auto-accept mode, Claude makes edits without asking. Set the default in VS Code settings under `claudeCode.initialPermissionMode`.

88* **Command menu**: click `/` or type `/` to open the command menu. Options include attaching files, switching models, toggling extended thinking, and viewing plan usage (`/usage`). The Customize section provides access to MCP servers, hooks, memory, permissions, and plugins. Items with a terminal icon open in the integrated terminal.88* **Command menu**: click `/` or type `/` to open the command menu. Options include attaching files, switching models, toggling extended thinking, viewing plan usage (`/usage`), and starting a [Remote Control](/en/remote-control) session (`/remote-control`). The Customize section provides access to MCP servers, hooks, memory, permissions, and plugins. Items with a terminal icon open in the integrated terminal.

89* **Context indicator**: the prompt box shows how much of Claude's context window you're using. Claude automatically compacts when needed, or you can run `/compact` manually.89* **Context indicator**: the prompt box shows how much of Claude's context window you're using. Claude automatically compacts when needed, or you can run `/compact` manually.

90* **Extended thinking**: lets Claude spend more time reasoning through complex problems. Toggle it on via the command menu (`/`). See [Extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) for details.90* **Extended thinking**: lets Claude spend more time reasoning through complex problems. Toggle it on via the command menu (`/`). See [Extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) for details.

91* **Multi-line input**: press `Shift+Enter` to add a new line without sending. This also works in the "Other" free-text input of question dialogs.91* **Multi-line input**: press `Shift+Enter` to add a new line without sending. This also works in the "Other" free-text input of question dialogs.

107 107

108### Resume past conversations108### Resume past conversations

109 109

110Click the dropdown at the top of the Claude Code panel to access your conversation history. You can search by keyword or browse by time (Today, Yesterday, Last 7 days, etc.). Click any conversation to resume it with the full message history. Hover over a session to reveal rename and remove actions: rename to give it a descriptive title, or remove to delete it from the list. For more on resuming sessions, see [Common workflows](/en/common-workflows#resume-previous-conversations).110Click the dropdown at the top of the Claude Code panel to access your conversation history. You can search by keyword or browse by time (Today, Yesterday, Last 7 days, etc.). Click any conversation to resume it with the full message history. New sessions receive AI-generated titles based on your first message. Hover over a session to reveal rename and remove actions: rename to give it a descriptive title, or remove to delete it from the list. For more on resuming sessions, see [Common workflows](/en/common-workflows#resume-previous-conversations).

111 111

112### Resume remote sessions from Claude.ai112### Resume remote sessions from Claude.ai

113 113

375* Use manual approval mode instead of auto-accept for edits375* Use manual approval mode instead of auto-accept for edits

376* Review changes carefully before accepting them376* Review changes carefully before accepting them

377 377

378### The built-in IDE MCP server

379

380When the extension is active, it runs a local MCP server that the CLI connects to automatically. This is how the CLI opens diffs in VS Code's native diff viewer, reads your current selection for `@`-mentions, and — when you're working in a Jupyter notebook — asks VS Code to execute cells.

381

382The server is named `ide` and is hidden from `/mcp` because there's nothing to configure. If your organization uses a `PreToolUse` hook to allowlist MCP tools, though, you'll need to know it exists.

383

384**Transport and authentication.** The server binds to `127.0.0.1` on a random high port and is not reachable from other machines. Each extension activation generates a fresh random auth token that the CLI must present to connect. The token is written to a lock file under `~/.claude/ide/` with `0600` permissions in a `0700` directory, so only the user running VS Code can read it.

385

386**Tools exposed to the model.** The server hosts a dozen tools, but only two are visible to the model. The rest are internal RPC the CLI uses for its own UI — opening diffs, reading selections, saving files — and are filtered out before the tool list reaches Claude.

387

388| Tool name (as seen by hooks) | What it does | Writes? |

389| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------- |

390| `mcp__ide__getDiagnostics` | Returns language-server diagnostics — the errors and warnings in VS Code's Problems panel. Optionally scoped to one file. | No |

391| `mcp__ide__executeCode` | Runs Python code in the active Jupyter notebook's kernel. See confirmation flow below. | Yes |

392

393**Jupyter execution always asks first.** `mcp__ide__executeCode` can't run anything silently. On each call, the code is inserted as a new cell at the end of the active notebook, VS Code scrolls it into view, and a native Quick Pick asks you to **Execute** or **Cancel**. Cancelling — or dismissing the picker with `Esc` — returns an error to Claude and nothing runs. The tool also refuses outright when there's no active notebook, when the Jupyter extension (`ms-toolsai.jupyter`) isn't installed, or when the kernel isn't Python.

394

395<Note>

396 The Quick Pick confirmation is separate from `PreToolUse` hooks. An allowlist entry for `mcp__ide__executeCode` lets Claude *propose* running a cell; the Quick Pick inside VS Code is what lets it *actually* run.

397</Note>

398

378## Fix common issues399## Fix common issues

379 400

380### Extension won't install401### Extension won't install

Documentation 2026-03-18 18:16 UTC to 2026-03-19 06:17 UTC