Documentation 2026-03-24 18:15 UTC to 2026-03-25 21:08 UTC

288 288 

289## Enterprise controls289## Enterprise controls

290 290 

291Channels are controlled by the `channelsEnabled` setting in [managed settings](/en/settings).291On Team and Enterprise plans, channels are off by default. Admins control availability through two [managed settings](/en/settings) that users cannot override:

292 292 

293| Plan type | Default behavior |293| Setting | Purpose | When not configured |

294| :------------------------- | :------------------------------------------------------------- |294| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------- |

295| Pro / Max, no organization | Channels available; users opt in per session with `--channels` |295| `channelsEnabled` | Master switch. Must be `true` for any channel to deliver messages. Set via the [claude.ai Admin console](https://claude.ai/admin-settings/claude-code) toggle or directly in managed settings. Blocks all channels including the development flag when off. | Channels blocked |

296| Team / Enterprise | Channels disabled until an admin explicitly enables them |296| `allowedChannelPlugins` | Which plugins can register once channels are enabled. Replaces the Anthropic-maintained list when set. Only applies when `channelsEnabled` is `true`. | Anthropic default list applies |

297 

298Pro and Max users without an organization skip these checks entirely: channels are available and users opt in per session with `--channels`.

297 299 

298### Enable channels for your organization300### Enable channels for your organization

299 301 

301 303 

302Once enabled, users in your organization can use `--channels` to opt channel servers into individual sessions. If the setting is disabled or unset, the MCP server still connects and its tools work, but channel messages won't arrive. A startup warning tells the user to have an admin enable the setting.304Once enabled, users in your organization can use `--channels` to opt channel servers into individual sessions. If the setting is disabled or unset, the MCP server still connects and its tools work, but channel messages won't arrive. A startup warning tells the user to have an admin enable the setting.

303 305 

306### Restrict which channel plugins can run

307 

308By default, any plugin on the Anthropic-maintained allowlist can register as a channel. Admins on Team and Enterprise plans can replace that allowlist with their own by setting `allowedChannelPlugins` in managed settings. Use this to restrict which official plugins are allowed, approve channels from your own internal marketplace, or both. Each entry names a plugin and the marketplace it comes from:

309 

310```json theme={null}

311{

312 "channelsEnabled": true,

313 "allowedChannelPlugins": [

314 { "marketplace": "claude-plugins-official", "plugin": "telegram" },

315 { "marketplace": "claude-plugins-official", "plugin": "discord" },

316 { "marketplace": "acme-corp-plugins", "plugin": "internal-alerts" }

317 ]

318}

319```

320 

321When `allowedChannelPlugins` is set, it replaces the Anthropic allowlist entirely: only the listed plugins can register. Leave it unset to fall back to the default Anthropic allowlist. An empty array blocks all channel plugins from the allowlist, but `--dangerously-load-development-channels` can still bypass it for local testing. To block channels entirely including the development flag, leave `channelsEnabled` unset instead.

322 

323This setting requires `channelsEnabled: true`. If a user passes a plugin to `--channels` that isn't on your list, Claude Code starts normally but the channel doesn't register, and the startup notice explains that the plugin isn't on the organization's approved list.

324 

304## Research preview325## Research preview

305 326 

306Channels are a research preview feature. Availability is rolling out gradually, and the `--channels` flag syntax and protocol contract may change based on feedback.327Channels are a research preview feature. Availability is rolling out gradually, and the `--channels` flag syntax and protocol contract may change based on feedback.

307 328 

308During the preview, `--channels` only accepts plugins from an Anthropic-maintained allowlist. The channel plugins in [claude-plugins-official](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins) are the approved set. If you pass something that isn't, Claude Code starts normally but the channel doesn't register, and the startup notice tells you why.329During the preview, `--channels` only accepts plugins from an Anthropic-maintained allowlist, or from your organization's allowlist if an admin has set [`allowedChannelPlugins`](#restrict-which-channel-plugins-can-run). The channel plugins in [claude-plugins-official](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins) are the default approved set. If you pass something that isn't on the effective allowlist, Claude Code starts normally but the channel doesn't register, and the startup notice tells you why.

309 330 

310To test a channel you're building, use `--dangerously-load-development-channels`. See [Test during the research preview](/en/channels-reference#test-during-the-research-preview) for information about testing custom channels that you build.331To test a channel you're building, use `--dangerously-load-development-channels`. See [Test during the research preview](/en/channels-reference#test-during-the-research-preview) for information about testing custom channels that you build.

311 332 

739 739 

740To make your channel installable and shareable, wrap it in a [plugin](/en/plugins) and publish it to a [marketplace](/en/plugin-marketplaces). Users install it with `/plugin install`, then enable it per session with `--channels plugin:<name>@<marketplace>`.740To make your channel installable and shareable, wrap it in a [plugin](/en/plugins) and publish it to a [marketplace](/en/plugin-marketplaces). Users install it with `/plugin install`, then enable it per session with `--channels plugin:<name>@<marketplace>`.

741 741 

742A channel published to your own marketplace still needs `--dangerously-load-development-channels` to run, since it isn't on the [approved allowlist](/en/channels#supported-channels). To get it added, [submit it to the official marketplace](/en/plugins#submit-your-plugin-to-the-official-marketplace). Channel plugins go through security review before being approved.742A channel published to your own marketplace still needs `--dangerously-load-development-channels` to run, since it isn't on the [approved allowlist](/en/channels#supported-channels). To get it added, [submit it to the official marketplace](/en/plugins#submit-your-plugin-to-the-official-marketplace). Channel plugins go through security review before being approved. On Team and Enterprise plans, an admin can instead include your plugin in the organization's own [`allowedChannelPlugins`](/en/channels#restrict-which-channel-plugins-can-run) list, which replaces the default Anthropic allowlist.

743 743 

744## See also744## See also

745 745 

68| `/security-review` | Analyze pending changes on the current branch for security vulnerabilities. Reviews the git diff and identifies risks like injection, auth issues, and data exposure |68| `/security-review` | Analyze pending changes on the current branch for security vulnerabilities. Reviews the git diff and identifies risks like injection, auth issues, and data exposure |

69| `/skills` | List available [skills](/en/skills) |69| `/skills` | List available [skills](/en/skills) |

70| `/stats` | Visualize daily usage, session history, streaks, and model preferences |70| `/stats` | Visualize daily usage, session history, streaks, and model preferences |

71| `/status` | Open the Settings interface (Status tab) showing version, model, account, and connectivity |71| `/status` | Open the Settings interface (Status tab) showing version, model, account, and connectivity. Works while Claude is responding, without waiting for the current response to finish |

72| `/statusline` | Configure Claude Code's [status line](/en/statusline). Describe what you want, or run without arguments to auto-configure from your shell prompt |72| `/statusline` | Configure Claude Code's [status line](/en/statusline). Describe what you want, or run without arguments to auto-configure from your shell prompt |

73| `/stickers` | Order Claude Code stickers |73| `/stickers` | Order Claude Code stickers |

74| `/tasks` | List and manage background tasks |74| `/tasks` | List and manage background tasks |

51 51 

52The prompt box supports two ways to bring in external context:52The prompt box supports two ways to bring in external context:

53 53 

54* **@mention files**: type `@` followed by a filename to add a file to the conversation context. Claude can then read and reference that file.54* **@mention files**: type `@` followed by a filename to add a file to the conversation context. Claude can then read and reference that file. @mention is not available in remote sessions.

55* **Attach files**: attach images, PDFs, and other files to your prompt using the attachment button, or drag and drop files directly into the prompt. This is useful for sharing screenshots of bugs, design mockups, or reference documents.55* **Attach files**: attach images, PDFs, and other files to your prompt using the attachment button, or drag and drop files directly into the prompt. This is useful for sharing screenshots of bugs, design mockups, or reference documents.

56 56 

57### Choose a permission mode57### Choose a permission mode

622| [Third-party providers](/en/third-party-integrations) | Bedrock, Vertex, Foundry | Not available. Desktop connects to Anthropic's API directly. |622| [Third-party providers](/en/third-party-integrations) | Bedrock, Vertex, Foundry | Not available. Desktop connects to Anthropic's API directly. |

623| [MCP servers](/en/mcp) | Configure in settings files | Connectors UI for local and SSH sessions, or settings files |623| [MCP servers](/en/mcp) | Configure in settings files | Connectors UI for local and SSH sessions, or settings files |

624| [Plugins](/en/plugins) | `/plugin` command | Plugin manager UI |624| [Plugins](/en/plugins) | `/plugin` command | Plugin manager UI |

625| @mention files | Text-based | With autocomplete |625| @mention files | Text-based | With autocomplete; local and SSH sessions only |

626| File attachments | Not available | Images, PDFs |626| File attachments | Not available | Images, PDFs |

627| Session isolation | [`--worktree`](/en/cli-reference) flag | Automatic worktrees |627| Session isolation | [`--worktree`](/en/cli-reference) flag | Automatic worktrees |

628| Multiple sessions | Separate terminals | Sidebar tabs |628| Multiple sessions | Separate terminals | Sidebar tabs |

50| `CLAUDE_CODE_DISABLE_FAST_MODE` | Set to `1` to disable [fast mode](/en/fast-mode) |50| `CLAUDE_CODE_DISABLE_FAST_MODE` | Set to `1` to disable [fast mode](/en/fast-mode) |

51| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | Set to `1` to disable the "How is Claude doing?" session quality surveys. Surveys are also disabled when `DISABLE_TELEMETRY` or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` is set. See [Session quality surveys](/en/data-usage#session-quality-surveys) |51| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | Set to `1` to disable the "How is Claude doing?" session quality surveys. Surveys are also disabled when `DISABLE_TELEMETRY` or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` is set. See [Session quality surveys](/en/data-usage#session-quality-surveys) |

52| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Equivalent of setting `DISABLE_AUTOUPDATER`, `DISABLE_FEEDBACK_COMMAND`, `DISABLE_ERROR_REPORTING`, and `DISABLE_TELEMETRY` |52| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Equivalent of setting `DISABLE_AUTOUPDATER`, `DISABLE_FEEDBACK_COMMAND`, `DISABLE_ERROR_REPORTING`, and `DISABLE_TELEMETRY` |

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

53| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates based on conversation context |54| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates based on conversation context |

54| `CLAUDE_CODE_EFFORT_LEVEL` | Set the effort level for supported models. Values: `low`, `medium`, `high`, `max` (Opus 4.6 only), or `auto` to use the model default. Takes precedence over `/effort` and the `effortLevel` setting. See [Adjust effort level](/en/model-config#adjust-effort-level) |55| `CLAUDE_CODE_EFFORT_LEVEL` | Set the effort level for supported models. Values: `low`, `medium`, `high`, `max` (Opus 4.6 only), or `auto` to use the model default. Takes precedence over `/effort` and the `effortLevel` setting. See [Adjust effort level](/en/model-config#adjust-effort-level) |

55| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | Set to `false` to disable prompt suggestions (the "Prompt suggestions" toggle in `/config`). These are the grayed-out predictions that appear in your prompt input after Claude responds. See [Prompt suggestions](/en/interactive-mode#prompt-suggestions) |56| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | Set to `false` to disable prompt suggestions (the "Prompt suggestions" toggle in `/config`). These are the grayed-out predictions that appear in your prompt input after Claude responds. See [Prompt suggestions](/en/interactive-mode#prompt-suggestions) |

76| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Skip Azure authentication for Microsoft Foundry (for example, when using an LLM gateway) |77| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Skip Azure authentication for Microsoft Foundry (for example, when using an LLM gateway) |

77| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Skip Google authentication for Vertex (for example, when using an LLM gateway) |78| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Skip Google authentication for Vertex (for example, when using an LLM gateway) |

78| `CLAUDE_CODE_SUBAGENT_MODEL` | See [Model configuration](/en/model-config) |79| `CLAUDE_CODE_SUBAGENT_MODEL` | See [Model configuration](/en/model-config) |

80| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Set to `1` to strip Anthropic and cloud provider credentials from subprocess environments (Bash tool, hooks, MCP stdio servers). The parent Claude process keeps these credentials for API calls, but child processes cannot read them, reducing exposure to prompt injection attacks that attempt to exfiltrate secrets via shell expansion. `claude-code-action` sets this automatically when `allowed_non_write_users` is configured |

79| `CLAUDE_CODE_TASK_LIST_ID` | Share a task list across sessions. Set the same ID in multiple Claude Code instances to coordinate on a shared task list. See [Task list](/en/interactive-mode#task-list) |81| `CLAUDE_CODE_TASK_LIST_ID` | Share a task list across sessions. Set the same ID in multiple Claude Code instances to coordinate on a shared task list. See [Task list](/en/interactive-mode#task-list) |

80| `CLAUDE_CODE_TEAM_NAME` | Name of the agent team this teammate belongs to. Set automatically on [agent team](/en/agent-teams) members |82| `CLAUDE_CODE_TEAM_NAME` | Name of the agent team this teammate belongs to. Set automatically on [agent team](/en/agent-teams) members |

81| `CLAUDE_CODE_TMPDIR` | Override the temp directory used for internal temp files. Claude Code appends `/claude/` to this path. Default: `/tmp` on Unix/macOS, `os.tmpdir()` on Windows |83| `CLAUDE_CODE_TMPDIR` | Override the temp directory used for internal temp files. Claude Code appends `/claude/` to this path. Default: `/tmp` on Unix/macOS, `os.tmpdir()` on Windows |

84| `CLAUDE_CODE_USE_FOUNDRY` | Use [Microsoft Foundry](/en/microsoft-foundry) |86| `CLAUDE_CODE_USE_FOUNDRY` | Use [Microsoft Foundry](/en/microsoft-foundry) |

85| `CLAUDE_CODE_USE_VERTEX` | Use [Vertex](/en/google-vertex-ai) |87| `CLAUDE_CODE_USE_VERTEX` | Use [Vertex](/en/google-vertex-ai) |

86| `CLAUDE_CONFIG_DIR` | Customize where Claude Code stores its configuration and data files |88| `CLAUDE_CONFIG_DIR` | Customize where Claude Code stores its configuration and data files |

87| `CLAUDE_ENV_FILE` | Path to a shell script that Claude Code sources before each Bash command. Use to persist virtualenv or conda activation across commands. Also populated dynamically by [SessionStart hooks](/en/hooks#persist-environment-variables) |89| `CLAUDE_ENV_FILE` | Path to a shell script that Claude Code sources before each Bash command. Use to persist virtualenv or conda activation across commands. Also populated dynamically by [SessionStart](/en/hooks#persist-environment-variables), [CwdChanged](/en/hooks#cwdchanged), and [FileChanged](/en/hooks#filechanged) hooks |

88| `DISABLE_AUTOUPDATER` | Set to `1` to disable automatic updates. |90| `DISABLE_AUTOUPDATER` | Set to `1` to disable automatic updates. |

89| `DISABLE_COST_WARNINGS` | Set to `1` to disable cost warning messages |91| `DISABLE_COST_WARNINGS` | Set to `1` to disable cost warning messages |

90| `DISABLE_ERROR_REPORTING` | Set to `1` to opt out of Sentry error reporting |92| `DISABLE_ERROR_REPORTING` | Set to `1` to opt out of Sentry error reporting |

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/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" />21 <img src="https://mintcdn.com/claude-code/JCMefyZyaJwkJgv-/images/hooks-lifecycle.svg?fit=max&auto=format&n=JCMefyZyaJwkJgv-&q=85&s=f004f3fc7324fa2a4630e8d6559cf6dd" 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, InstructionsLoaded, CwdChanged, and FileChanged as standalone async events" width="520" height="1100" data-path="images/hooks-lifecycle.svg" />

22 </Frame>22 </Frame>

23</div>23</div>

24 24 

25The table below summarizes when each event fires. The [Hook events](#hook-events) section documents the full input schema and decision control options for each one.25The table below summarizes when each event fires. The [Hook events](#hook-events) section documents the full input schema and decision control options for each one.

26 26 

27| Event | When it fires |27| Event | When it fires |

28| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |28| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

29| `SessionStart` | When a session begins or resumes |29| `SessionStart` | When a session begins or resumes |

30| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |30| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |

31| `PreToolUse` | Before a tool call executes. Can block it |31| `PreToolUse` | Before a tool call executes. Can block it |

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

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 |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 |

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

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

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

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

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

46| `PreCompact` | Before context compaction |48| `PreCompact` | Before context compaction |

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:169The `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:

168 170 

169| Event | What the matcher filters | Example matcher values |171| Event | What the matcher filters | Example matcher values |

170| :---------------------------------------------------------------------------------------------- | :------------------------ | :------------------------------------------------------------------------------------------------------------------------ |172| :---------------------------------------------------------------------------------------------- | :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |

171| `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` | tool name | `Bash`, `Edit\|Write`, `mcp__.*` |173| `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` | tool name | `Bash`, `Edit\|Write`, `mcp__.*` |

172| `SessionStart` | how the session started | `startup`, `resume`, `clear`, `compact` |174| `SessionStart` | how the session started | `startup`, `resume`, `clear`, `compact` |

173| `SessionEnd` | why the session ended | `clear`, `resume`, `logout`, `prompt_input_exit`, `bypass_permissions_disabled`, `other` |175| `SessionEnd` | why the session ended | `clear`, `resume`, `logout`, `prompt_input_exit`, `bypass_permissions_disabled`, `other` |

176| `PreCompact`, `PostCompact` | what triggered compaction | `manual`, `auto` |178| `PreCompact`, `PostCompact` | what triggered compaction | `manual`, `auto` |

177| `SubagentStop` | agent type | same values as `SubagentStart` |179| `SubagentStop` | agent type | same values as `SubagentStart` |

178| `ConfigChange` | configuration source | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` |180| `ConfigChange` | configuration source | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` |

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

182| `FileChanged` | filename (basename of the changed file) | `.envrc`, `.env`, any filename you want to watch |

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

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

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

204}208}

205```209```

206 210 

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.211`UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, and `CwdChanged` don't support matchers and always fire on every occurrence. If you add a `matcher` field to these events, it is silently ignored.

208 212 

209#### Match MCP tools213#### Match MCP tools

210 214 

526| `SubagentStart` | No | Shows stderr to user only |530| `SubagentStart` | No | Shows stderr to user only |

527| `SessionStart` | No | Shows stderr to user only |531| `SessionStart` | No | Shows stderr to user only |

528| `SessionEnd` | No | Shows stderr to user only |532| `SessionEnd` | No | Shows stderr to user only |

533| `CwdChanged` | No | Shows stderr to user only |

534| `FileChanged` | No | Shows stderr to user only |

529| `PreCompact` | No | Shows stderr to user only |535| `PreCompact` | No | Shows stderr to user only |

530| `PostCompact` | No | Shows stderr to user only |536| `PostCompact` | No | Shows stderr to user only |

531| `Elicitation` | Yes | Denies the elicitation |537| `Elicitation` | Yes | Denies the elicitation |

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:586Not 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:

581 587 

582| Events | Decision pattern | Key fields |588| Events | Decision pattern | Key fields |

583| :------------------------------------------------------------------------------------------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |589| :-------------------------------------------------------------------------------------------------------------------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

584| UserPromptSubmit, PostToolUse, PostToolUseFailure, Stop, SubagentStop, ConfigChange | Top-level `decision` | `decision: "block"`, `reason` |590| UserPromptSubmit, PostToolUse, PostToolUseFailure, Stop, SubagentStop, ConfigChange | Top-level `decision` | `decision: "block"`, `reason` |

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 |591| 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| PreToolUse | `hookSpecificOutput` | `permissionDecision` (allow/deny/ask), `permissionDecisionReason` |592| PreToolUse | `hookSpecificOutput` | `permissionDecision` (allow/deny/ask), `permissionDecisionReason` |

588| WorktreeCreate | stdout path | Hook prints absolute path to created worktree. Non-zero exit fails creation |594| WorktreeCreate | stdout path | Hook prints absolute path to created worktree. Non-zero exit fails creation |

589| Elicitation | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (form field values for accept) |595| Elicitation | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (form field values for accept) |

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

591| WorktreeRemove, Notification, SessionEnd, PreCompact, PostCompact, InstructionsLoaded, StopFailure | None | No decision control. Used for side effects like logging or cleanup |597| WorktreeRemove, Notification, SessionEnd, PreCompact, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, FileChanged | None | No decision control. Used for side effects like logging or cleanup |

592 598 

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

594 600 

730Any variables written to this file will be available in all subsequent Bash commands that Claude Code executes during the session.736Any variables written to this file will be available in all subsequent Bash commands that Claude Code executes during the session.

731 737 

732<Note>738<Note>

733 `CLAUDE_ENV_FILE` is available for SessionStart hooks. Other hook types do not have access to this variable.739 `CLAUDE_ENV_FILE` is available for SessionStart, [CwdChanged](#cwdchanged), and [FileChanged](#filechanged) hooks. Other hook types do not have access to this variable.

734</Note>740</Note>

735 741 

736### InstructionsLoaded742### InstructionsLoaded

1495 1501 

1496`policy_settings` changes cannot be blocked. Hooks still fire for `policy_settings` sources, so you can use them for audit logging, but any blocking decision is ignored. This ensures enterprise-managed settings always take effect.1502`policy_settings` changes cannot be blocked. Hooks still fire for `policy_settings` sources, so you can use them for audit logging, but any blocking decision is ignored. This ensures enterprise-managed settings always take effect.

1497 1503 

1504### CwdChanged

1505 

1506Runs when the working directory changes during a session, for example when Claude executes a `cd` command. Use this to react to directory changes: reload environment variables, activate project-specific toolchains, or run setup scripts automatically. Pairs with [FileChanged](#filechanged) for tools like [direnv](https://direnv.net/) that manage per-directory environment.

1507 

1508CwdChanged hooks have access to `CLAUDE_ENV_FILE`. Variables written to that file persist into subsequent Bash commands for the session, just as in [SessionStart hooks](#persist-environment-variables). Only `type: "command"` hooks are supported.

1509 

1510CwdChanged does not support matchers and fires on every directory change.

1511 

1512#### CwdChanged input

1513 

1514In addition to the [common input fields](#common-input-fields), CwdChanged hooks receive `old_cwd` and `new_cwd`.

1515 

1516```json theme={null}

1517{

1518 "session_id": "abc123",

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

1520 "cwd": "/Users/my-project/src",

1521 "hook_event_name": "CwdChanged",

1522 "old_cwd": "/Users/my-project",

1523 "new_cwd": "/Users/my-project/src"

1524}

1525```

1526 

1527#### CwdChanged output

1528 

1529In addition to the [JSON output fields](#json-output) available to all hooks, CwdChanged hooks can return `watchPaths` to dynamically set which file paths [FileChanged](#filechanged) watches:

1530 

1531| Field | Description |

1532| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

1533| `watchPaths` | Array of absolute paths. Replaces the current dynamic watch list (paths from your `matcher` configuration are always watched). Returning an empty array clears the dynamic list, which is typical when entering a new directory |

1534 

1535CwdChanged hooks have no decision control. They cannot block the directory change.

1536 

1537### FileChanged

1538 

1539Runs when a watched file changes on disk. The `matcher` field in your hook configuration controls which filenames to watch: it is a pipe-separated list of basenames (filenames without directory paths, for example `".envrc|.env"`). The same `matcher` value is also used to filter which hooks run when a file changes, matching against the basename of the changed file. Useful for reloading environment variables when project configuration files are modified.

1540 

1541FileChanged hooks have access to `CLAUDE_ENV_FILE`. Variables written to that file persist into subsequent Bash commands for the session, just as in [SessionStart hooks](#persist-environment-variables). Only `type: "command"` hooks are supported.

1542 

1543#### FileChanged input

1544 

1545In addition to the [common input fields](#common-input-fields), FileChanged hooks receive `file_path` and `event`.

1546 

1547| Field | Description |

1548| :---------- | :---------------------------------------------------------------------------------------------- |

1549| `file_path` | Absolute path to the file that changed |

1550| `event` | What happened: `"change"` (file modified), `"add"` (file created), or `"unlink"` (file deleted) |

1551 

1552```json theme={null}

1553{

1554 "session_id": "abc123",

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

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

1557 "hook_event_name": "FileChanged",

1558 "file_path": "/Users/my-project/.envrc",

1559 "event": "change"

1560}

1561```

1562 

1563#### FileChanged output

1564 

1565In addition to the [JSON output fields](#json-output) available to all hooks, FileChanged hooks can return `watchPaths` to dynamically update which file paths are watched:

1566 

1567| Field | Description |

1568| :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1569| `watchPaths` | Array of absolute paths. Replaces the current dynamic watch list (paths from your `matcher` configuration are always watched). Use this when your hook script discovers additional files to watch based on the changed file |

1570 

1571FileChanged hooks have no decision control. They cannot block the file change from occurring.

1572 

1498### WorktreeCreate1573### WorktreeCreate

1499 1574 

1500When you run `claude --worktree` or a [subagent uses `isolation: "worktree"`](/en/sub-agents#choose-the-subagent-scope), Claude Code creates an isolated working copy using `git worktree`. If you configure a WorktreeCreate hook, it replaces the default git behavior, letting you use a different version control system like SVN, Perforce, or Mercurial.1575When you run `claude --worktree` or a [subagent uses `isolation: "worktree"`](/en/sub-agents#choose-the-subagent-scope), Claude Code creates an isolated working copy using `git worktree`. If you configure a WorktreeCreate hook, it replaces the default git behavior, letting you use a different version control system like SVN, Perforce, or Mercurial.

1807Events that only support `type: "command"` hooks:1882Events that only support `type: "command"` hooks:

1808 1883 

1809* `ConfigChange`1884* `ConfigChange`

1885* `CwdChanged`

1810* `Elicitation`1886* `Elicitation`

1811* `ElicitationResult`1887* `ElicitationResult`

1888* `FileChanged`

1812* `InstructionsLoaded`1889* `InstructionsLoaded`

1813* `Notification`1890* `Notification`

1814* `PostCompact`1891* `PostCompact`

69* [Block edits to protected files](#block-edits-to-protected-files)69* [Block edits to protected files](#block-edits-to-protected-files)

70* [Re-inject context after compaction](#re-inject-context-after-compaction)70* [Re-inject context after compaction](#re-inject-context-after-compaction)

71* [Audit configuration changes](#audit-configuration-changes)71* [Audit configuration changes](#audit-configuration-changes)

72* [Reload environment when directory or files change](#reload-environment-when-directory-or-files-change)

72* [Auto-approve specific permission prompts](#auto-approve-specific-permission-prompts)73* [Auto-approve specific permission prompts](#auto-approve-specific-permission-prompts)

73 74 

74### Get notified when Claude needs input75### Get notified when Claude needs input

280 281 

281The matcher filters by configuration type: `user_settings`, `project_settings`, `local_settings`, `policy_settings`, or `skills`. To block a change from taking effect, exit with code 2 or return `{"decision": "block"}`. See the [ConfigChange reference](/en/hooks#configchange) for the full input schema.282The matcher filters by configuration type: `user_settings`, `project_settings`, `local_settings`, `policy_settings`, or `skills`. To block a change from taking effect, exit with code 2 or return `{"decision": "block"}`. See the [ConfigChange reference](/en/hooks#configchange) for the full input schema.

282 283 

284### Reload environment when directory or files change

285 

286Some projects set different environment variables depending on which directory you are in. Tools like [direnv](https://direnv.net/) do this automatically in your shell, but Claude's Bash tool does not pick up those changes on its own.

287 

288A `CwdChanged` hook fixes this: it runs each time Claude changes directory, so you can reload the correct variables for the new location. The hook writes the updated values to `CLAUDE_ENV_FILE`, which Claude Code applies before each Bash command. Add this to `~/.claude/settings.json`:

289 

290```json theme={null}

291{

292 "hooks": {

293 "CwdChanged": [

294 {

295 "hooks": [

296 {

297 "type": "command",

298 "command": "direnv export bash >> \"$CLAUDE_ENV_FILE\""

299 }

300 ]

301 }

302 ]

303 }

304}

305```

306 

307To react to specific files instead of every directory change, use `FileChanged` with a `matcher` listing the filenames to watch (pipe-separated). The `matcher` both configures which files to watch and filters which hooks run. This example watches `.envrc` and `.env` for changes in the current directory:

308 

309```json theme={null}

310{

311 "hooks": {

312 "FileChanged": [

313 {

314 "matcher": ".envrc|.env",

315 "hooks": [

316 {

317 "type": "command",

318 "command": "direnv export bash >> \"$CLAUDE_ENV_FILE\""

319 }

320 ]

321 }

322 ]

323 }

324}

325```

326 

327See the [CwdChanged](/en/hooks#cwdchanged) and [FileChanged](/en/hooks#filechanged) reference entries for input schemas, `watchPaths` output, and `CLAUDE_ENV_FILE` details.

328 

283### Auto-approve specific permission prompts329### Auto-approve specific permission prompts

284 330 

285Skip the approval dialog for tool calls you always allow. This example auto-approves `ExitPlanMode`, the tool Claude calls when it finishes presenting a plan and asks to proceed, so you aren't prompted every time a plan is ready.331Skip the approval dialog for tool calls you always allow. This example auto-approves `ExitPlanMode`, the tool Claude calls when it finishes presenting a plan and asks to proceed, so you aren't prompted every time a plan is ready.

333Hook events fire at specific lifecycle points in Claude Code. When an event fires, all matching hooks run in parallel, and identical hook commands are automatically deduplicated. The table below shows each event and when it triggers:379Hook events fire at specific lifecycle points in Claude Code. When an event fires, all matching hooks run in parallel, and identical hook commands are automatically deduplicated. The table below shows each event and when it triggers:

334 380 

335| Event | When it fires |381| Event | When it fires |

336| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |382| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

337| `SessionStart` | When a session begins or resumes |383| `SessionStart` | When a session begins or resumes |

338| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |384| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |

339| `PreToolUse` | Before a tool call executes. Can block it |385| `PreToolUse` | Before a tool call executes. Can block it |

349| `TaskCompleted` | When a task is being marked as completed |395| `TaskCompleted` | When a task is being marked as completed |

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 |396| `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 |

351| `ConfigChange` | When a configuration file changes during a session |397| `ConfigChange` | When a configuration file changes during a session |

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

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

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

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

354| `PreCompact` | Before context compaction |402| `PreCompact` | Before context compaction |

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

465 513 

466| Event | What the matcher filters | Example matcher values |514| Event | What the matcher filters | Example matcher values |

467| :---------------------------------------------------------------------------------------------- | :------------------------ | :------------------------------------------------------------------------------------------------------------------------ |515| :------------------------------------------------------------------------------------------------------------ | :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |

468| `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` | tool name | `Bash`, `Edit\|Write`, `mcp__.*` |516| `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` | tool name | `Bash`, `Edit\|Write`, `mcp__.*` |

469| `SessionStart` | how the session started | `startup`, `resume`, `clear`, `compact` |517| `SessionStart` | how the session started | `startup`, `resume`, `clear`, `compact` |

470| `SessionEnd` | why the session ended | `clear`, `resume`, `logout`, `prompt_input_exit`, `bypass_permissions_disabled`, `other` |518| `SessionEnd` | why the session ended | `clear`, `resume`, `logout`, `prompt_input_exit`, `bypass_permissions_disabled`, `other` |

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

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

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

480| `UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove` | no matcher support | always fires on every occurrence |528| `FileChanged` | filename (basename of the changed file) | `.envrc`, `.env`, any filename you want to watch |

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

481 530 

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

483 532 

25| Shortcut | Description | Context |25| Shortcut | Description | Context |

26| :------------------------------------------------ | :------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |26| :------------------------------------------------ | :------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

27| `Ctrl+C` | Cancel current input or generation | Standard interrupt |27| `Ctrl+C` | Cancel current input or generation | Standard interrupt |

28| `Ctrl+F` | Kill all background agents. Press twice within 3 seconds to confirm | Background agent control |28| `Ctrl+X Ctrl+K` | Kill all background agents. Press twice within 3 seconds to confirm | Background agent control |

29| `Ctrl+D` | Exit Claude Code session | EOF signal |29| `Ctrl+D` | Exit Claude Code session | EOF signal |

30| `Ctrl+G` | Open in default text editor | Edit your prompt or custom response in your default text editor |30| `Ctrl+G` or `Ctrl+X Ctrl+E` | Open in default text editor | Edit your prompt or custom response in your default text editor. `Ctrl+X Ctrl+E` is the readline-native binding |

31| `Ctrl+L` | Clear terminal screen | Keeps conversation history |31| `Ctrl+L` | Clear terminal screen | Keeps conversation history |

32| `Ctrl+O` | Toggle verbose output | Shows detailed tool usage and execution. Also expands MCP read and search calls, which collapse to a single line like "Queried slack" by default |32| `Ctrl+O` | Toggle verbose output | Shows detailed tool usage and execution. Also expands MCP read and search calls, which collapse to a single line like "Queried slack" by default |

33| `Ctrl+R` | Reverse search command history | Search through previous commands interactively |33| `Ctrl+R` | Reverse search command history | Search through previous commands interactively |

34| `Ctrl+V` or `Cmd+V` (iTerm2) or `Alt+V` (Windows) | Paste image from clipboard | Pastes an image or path to an image file |34| `Ctrl+V` or `Cmd+V` (iTerm2) or `Alt+V` (Windows) | Paste image from clipboard | Inserts an `[Image #N]` chip at the cursor so you can reference it positionally in your prompt |

35| `Ctrl+B` | Background running tasks | Backgrounds bash commands and agents. Tmux users press twice |35| `Ctrl+B` | Background running tasks | Backgrounds bash commands and agents. Tmux users press twice |

36| `Ctrl+T` | Toggle task list | Show or hide the [task list](#task-list) in the terminal status area |36| `Ctrl+T` | Toggle task list | Show or hide the [task list](#task-list) in the terminal status area |

37| `Left/Right arrows` | Cycle through dialog tabs | Navigate between tabs in permission dialogs and menus |37| `Left/Right arrows` | Cycle through dialog tabs | Navigate between tabs in permission dialogs and menus |

40| `Shift+Tab` or `Alt+M` (some configurations) | Cycle permission modes | Cycle through `default`, `acceptEdits`, `plan`, and any modes you have enabled, such as `auto` or `bypassPermissions`. See [permission modes](/en/permission-modes). |40| `Shift+Tab` or `Alt+M` (some configurations) | Cycle permission modes | Cycle through `default`, `acceptEdits`, `plan`, and any modes you have enabled, such as `auto` or `bypassPermissions`. See [permission modes](/en/permission-modes). |

41| `Option+P` (macOS) or `Alt+P` (Windows/Linux) | Switch model | Switch models without clearing your prompt |41| `Option+P` (macOS) or `Alt+P` (Windows/Linux) | Switch model | Switch models without clearing your prompt |

42| `Option+T` (macOS) or `Alt+T` (Windows/Linux) | Toggle extended thinking | Enable or disable extended thinking mode. Run `/terminal-setup` first to enable this shortcut |42| `Option+T` (macOS) or `Alt+T` (Windows/Linux) | Toggle extended thinking | Enable or disable extended thinking mode. Run `/terminal-setup` first to enable this shortcut |

43| `Option+O` (macOS) or `Alt+O` (Windows/Linux) | Toggle fast mode | Enable or disable [fast mode](/en/fast-mode) |

43 44 

44### Text editing45### Text editing

45 46 

84| `!` at start | Bash mode | Run commands directly and add execution output to the session |85| `!` at start | Bash mode | Run commands directly and add execution output to the session |

85| `@` | File path mention | Trigger file path autocomplete |86| `@` | File path mention | Trigger file path autocomplete |

86 87 

88### Transcript viewer

89 

90When the transcript viewer is open (toggled with `Ctrl+O`), these shortcuts are available. `Ctrl+E` can be rebound via [`transcript:toggleShowAll`](/en/keybindings).

91 

92| Shortcut | Description |

93| :------------------- | :---------------------------------------------------------------------------------------------------------------------- |

94| `Ctrl+E` | Toggle show all content |

95| `q`, `Ctrl+C`, `Esc` | Exit transcript view. `Ctrl+C` and `Esc` can be rebound via [`transcript:exit`](/en/keybindings); `q` is not rebindable |

96 

87### Voice input97### Voice input

88 98 

89| Shortcut | Description | Notes |99| Shortcut | Description | Notes |

210 220 

211**Key features:**221**Key features:**

212 222 

213* Output is buffered and Claude can retrieve it using the TaskOutput tool223* Output is written to a file and Claude can retrieve it using the Read tool

214* Background tasks have unique IDs for tracking and output retrieval224* Background tasks have unique IDs for tracking and output retrieval

215* Background tasks are automatically cleaned up when Claude Code exits225* Background tasks are automatically cleaned up when Claude Code exits

216* Background tasks are automatically terminated if output exceeds 5GB, with a note in stderr explaining why226* Background tasks are automatically terminated if output exceeds 5GB, with a note in stderr explaining why

97Actions available in the `Chat` context:97Actions available in the `Chat` context:

98 98 

99| Action | Default | Description |99| Action | Default | Description |

100| :-------------------- | :------------------------ | :----------------------- |100| :-------------------- | :------------------------ | :------------------------- |

101| `chat:cancel` | Escape | Cancel current input |101| `chat:cancel` | Escape | Cancel current input |

102| `chat:killAgents` | Ctrl+X Ctrl+K | Kill all background agents |

102| `chat:cycleMode` | Shift+Tab\* | Cycle permission modes |103| `chat:cycleMode` | Shift+Tab\* | Cycle permission modes |

103| `chat:modelPicker` | Cmd+P / Meta+P | Open model picker |104| `chat:modelPicker` | Cmd+P / Meta+P | Open model picker |

105| `chat:fastMode` | Meta+O | Toggle fast mode |

104| `chat:thinkingToggle` | Cmd+T / Meta+T | Toggle extended thinking |106| `chat:thinkingToggle` | Cmd+T / Meta+T | Toggle extended thinking |

105| `chat:submit` | Enter | Submit message |107| `chat:submit` | Enter | Submit message |

106| `chat:undo` | Ctrl+\_ | Undo last action |108| `chat:undo` | Ctrl+\_ | Undo last action |

107| `chat:externalEditor` | Ctrl+G | Open in external editor |109| `chat:externalEditor` | Ctrl+G, Ctrl+X Ctrl+E | Open in external editor |

108| `chat:stash` | Ctrl+S | Stash current prompt |110| `chat:stash` | Ctrl+S | Stash current prompt |

109| `chat:imagePaste` | Ctrl+V (Alt+V on Windows) | Paste image |111| `chat:imagePaste` | Ctrl+V (Alt+V on Windows) | Paste image |

110 112 

356These shortcuts cannot be rebound:358These shortcuts cannot be rebound:

357 359 

358| Shortcut | Reason |360| Shortcut | Reason |

359| :------- | :------------------------- |361| :------- | :--------------------------------------------- |

360| Ctrl+C | Hardcoded interrupt/cancel |362| Ctrl+C | Hardcoded interrupt/cancel |

361| Ctrl+D | Hardcoded exit |363| Ctrl+D | Hardcoded exit |

364| Ctrl+M | Identical to Enter in terminals (both send CR) |

362 365 

363## Terminal conflicts366## Terminal conflicts

364 367 

374 374 

375```json theme={null}375```json theme={null}

376{376{

377 "mcpServers": {

377 "database-tools": {378 "database-tools": {

378 "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",379 "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",

379 "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],380 "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],

381 "DB_URL": "${DB_URL}"382 "DB_URL": "${DB_URL}"

382 }383 }

383 }384 }

385 }

384}386}

385```387```

386 388 

765 767 

766The URL must use `https://`. This option requires Claude Code v2.1.64 or later.768The URL must use `https://`. This option requires Claude Code v2.1.64 or later.

767 769 

770### Use dynamic headers for custom authentication

771 

772If your MCP server uses an authentication scheme other than OAuth (such as Kerberos, short-lived tokens, or an internal SSO), use `headersHelper` to generate request headers at connection time. Claude Code runs the command and merges its output into the connection headers.

773 

774```json theme={null}

775{

776 "mcpServers": {

777 "internal-api": {

778 "type": "http",

779 "url": "https://mcp.internal.example.com",

780 "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"

781 }

782 }

783}

784```

785 

786The command can also be inline:

787 

788```json theme={null}

789{

790 "mcpServers": {

791 "internal-api": {

792 "type": "http",

793 "url": "https://mcp.internal.example.com",

794 "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"

795 }

796 }

797}

798```

799 

800**Requirements:**

801 

802* The command must write a JSON object of string key-value pairs to stdout

803* The command runs in a shell with a 10-second timeout

804* Dynamic headers override any static `headers` with the same name

805 

806The helper runs fresh on each connection (at session start and on reconnect). There is no caching, so your script is responsible for any token reuse.

807 

808<Note>

809 `headersHelper` executes arbitrary shell commands. When defined at project or local scope, it only runs after you accept the workspace trust dialog.

810</Note>

811 

768## Add MCP servers from JSON configuration812## Add MCP servers from JSON configuration

769 813 

770If you have a JSON configuration for an MCP server, you can add it directly:814If you have a JSON configuration for an MCP server, you can add it directly:

131 131 

132[Effort levels](https://platform.claude.com/docs/en/build-with-claude/effort) control adaptive reasoning, which dynamically allocates thinking based on task complexity. Lower effort is faster and cheaper for straightforward tasks, while higher effort provides deeper reasoning for complex problems.132[Effort levels](https://platform.claude.com/docs/en/build-with-claude/effort) control adaptive reasoning, which dynamically allocates thinking based on task complexity. Lower effort is faster and cheaper for straightforward tasks, while higher effort provides deeper reasoning for complex problems.

133 133 

134Three levels persist across sessions: **low**, **medium**, and **high**. A fourth level, **max**, provides the deepest reasoning with no constraint on token spending, so responses are slower and cost more than at `high`. `max` is available on Opus 4.6 only and applies to the current session without persisting. Opus 4.6 defaults to medium effort for Max and Team subscribers.134Three levels persist across sessions: **low**, **medium**, and **high**. A fourth level, **max**, provides the deepest reasoning with no constraint on token spending, so responses are slower and cost more than at `high`. `max` is available on Opus 4.6 only and does not persist across sessions except through the `CLAUDE_CODE_EFFORT_LEVEL` environment variable.

135 

136Opus 4.6 and Sonnet 4.6 default to medium effort. This applies to all providers, including Bedrock, Vertex AI, and direct API access.

137 

138Medium is the recommended level for most coding tasks: it balances speed and reasoning depth, and higher levels can cause the model to overthink routine work. Reserve `high` or `max` for tasks that genuinely benefit from deeper reasoning, such as hard debugging problems or complex architectural decisions.

139 

140For one-off deep reasoning without changing your session setting, include "ultrathink" in your prompt to trigger high effort for that turn.

135 141 

136**Setting effort:**142**Setting effort:**

137 143 

85| `OTEL_METRIC_EXPORT_INTERVAL` | Export interval in milliseconds (default: 60000) | `5000`, `60000` |85| `OTEL_METRIC_EXPORT_INTERVAL` | Export interval in milliseconds (default: 60000) | `5000`, `60000` |

86| `OTEL_LOGS_EXPORT_INTERVAL` | Logs export interval in milliseconds (default: 5000) | `1000`, `10000` |86| `OTEL_LOGS_EXPORT_INTERVAL` | Logs export interval in milliseconds (default: 5000) | `1000`, `10000` |

87| `OTEL_LOG_USER_PROMPTS` | Enable logging of user prompt content (default: disabled) | `1` to enable |87| `OTEL_LOG_USER_PROMPTS` | Enable logging of user prompt content (default: disabled) | `1` to enable |

88| `OTEL_LOG_TOOL_DETAILS` | Enable logging of MCP server/tool names and skill names in tool events (default: disabled) | `1` to enable |88| `OTEL_LOG_TOOL_DETAILS` | Enable logging of tool input arguments, MCP server/tool names, and skill names in tool events (default: disabled) | `1` to enable |

89| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | Metrics temporality preference (default: `delta`). Set to `cumulative` if your backend expects cumulative temporality | `delta`, `cumulative` |89| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | Metrics temporality preference (default: `delta`). Set to `cumulative` if your backend expects cumulative temporality | `delta`, `cumulative` |

90| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Interval for refreshing dynamic headers (default: 1740000ms / 29 minutes) | `900000` |90| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Interval for refreshing dynamic headers (default: 1740000ms / 29 minutes) | `900000` |

91 91 

390 * For Bash tool: includes `bash_command`, `full_command`, `timeout`, `description`, `dangerouslyDisableSandbox`, and `git_commit_id` (the commit SHA, when a `git commit` command succeeds)390 * For Bash tool: includes `bash_command`, `full_command`, `timeout`, `description`, `dangerouslyDisableSandbox`, and `git_commit_id` (the commit SHA, when a `git commit` command succeeds)

391 * For MCP tools (when `OTEL_LOG_TOOL_DETAILS=1`): includes `mcp_server_name`, `mcp_tool_name`391 * For MCP tools (when `OTEL_LOG_TOOL_DETAILS=1`): includes `mcp_server_name`, `mcp_tool_name`

392 * For Skill tool (when `OTEL_LOG_TOOL_DETAILS=1`): includes `skill_name`392 * For Skill tool (when `OTEL_LOG_TOOL_DETAILS=1`): includes `skill_name`

393* `tool_input` (when `OTEL_LOG_TOOL_DETAILS=1`): JSON-serialized tool arguments. Individual values over 512 characters are truncated, and the full payload is bounded to \~4 K characters. Applies to all tools including MCP tools.

393 394 

394#### API request event395#### API request event

395 396 

534* Raw file contents and code snippets are not included in metrics or events. Tool execution events include bash commands and file paths in the `tool_parameters` field, which may contain sensitive values. If your commands may include secrets, configure your telemetry backend to filter or redact `tool_parameters`535* Raw file contents and code snippets are not included in metrics or events. Tool execution events include bash commands and file paths in the `tool_parameters` field, which may contain sensitive values. If your commands may include secrets, configure your telemetry backend to filter or redact `tool_parameters`

535* When authenticated via OAuth, `user.email` is included in telemetry attributes. If this is a concern for your organization, work with your telemetry backend to filter or redact this field536* When authenticated via OAuth, `user.email` is included in telemetry attributes. If this is a concern for your organization, work with your telemetry backend to filter or redact this field

536* User prompt content is not collected by default. Only prompt length is recorded. To include prompt content, set `OTEL_LOG_USER_PROMPTS=1`537* User prompt content is not collected by default. Only prompt length is recorded. To include prompt content, set `OTEL_LOG_USER_PROMPTS=1`

537* MCP server/tool names and skill names are not logged by default because they can reveal user-specific configurations. To include them, set `OTEL_LOG_TOOL_DETAILS=1`538* Tool input arguments are not logged by default. To include them, set `OTEL_LOG_TOOL_DETAILS=1`. When enabled, `tool_result` events include MCP server/tool names and skill names plus a `tool_input` attribute with file paths, URLs, search patterns, and other arguments. Individual values over 512 characters are truncated and the total is bounded to \~4 K characters, but the arguments may still contain sensitive values. Configure your telemetry backend to filter or redact `tool_input` as needed

538 539 

539## Monitor Claude Code on Amazon Bedrock540## Monitor Claude Code on Amazon Bedrock

540 541 

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

110 110 

111| Event | When it fires |111| Event | When it fires |

112| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |112| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

113| `SessionStart` | When a session begins or resumes |113| `SessionStart` | When a session begins or resumes |

114| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |114| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |

115| `PreToolUse` | Before a tool call executes. Can block it |115| `PreToolUse` | Before a tool call executes. Can block it |

125| `TaskCompleted` | When a task is being marked as completed |125| `TaskCompleted` | When a task is being marked as completed |

126| `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 |126| `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 |

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

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

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

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

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

130| `PreCompact` | Before context compaction |132| `PreCompact` | Before context compaction |

345| `mcpServers` | string\|array\|object | MCP config paths or inline config | `"./my-extra-mcp-config.json"` |347| `mcpServers` | string\|array\|object | MCP config paths or inline config | `"./my-extra-mcp-config.json"` |

346| `outputStyles` | string\|array | Additional output style files/directories | `"./styles/"` |348| `outputStyles` | string\|array | Additional output style files/directories | `"./styles/"` |

347| `lspServers` | string\|array\|object | [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) configs for code intelligence (go to definition, find references, etc.) | `"./.lsp.json"` |349| `lspServers` | string\|array\|object | [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) configs for code intelligence (go to definition, find references, etc.) | `"./.lsp.json"` |

350| `userConfig` | object | User-configurable values prompted at enable time. See [User configuration](#user-configuration) | See below |

351| `channels` | array | Channel declarations for message injection (Telegram, Slack, Discord style). See [Channels](#channels) | See below |

352 

353### User configuration

354 

355The `userConfig` field declares values that Claude Code prompts the user for when the plugin is enabled. Use this instead of requiring users to hand-edit `settings.json`.

356 

357```json theme={null}

358{

359 "userConfig": {

360 "api_endpoint": {

361 "description": "Your team's API endpoint",

362 "sensitive": false

363 },

364 "api_token": {

365 "description": "API authentication token",

366 "sensitive": true

367 }

368 }

369}

370```

371 

372Keys must be valid identifiers. Each value is available for substitution as `${user_config.KEY}` in MCP and LSP server configs, hook commands, and (for non-sensitive values only) skill and agent content. Values are also exported to plugin subprocesses as `CLAUDE_PLUGIN_OPTION_<KEY>` environment variables.

373 

374Non-sensitive values are stored in `settings.json` under `pluginConfigs[<plugin-id>].options`. Sensitive values go to the system keychain (or `~/.claude/.credentials.json` where the keychain is unavailable). Keychain storage is shared with OAuth tokens and has an approximately 2 KB total limit, so keep sensitive values small.

375 

376### Channels

377 

378The `channels` field lets a plugin declare one or more message channels that inject content into the conversation. Each channel binds to an MCP server that the plugin provides.

379 

380```json theme={null}

381{

382 "channels": [

383 {

384 "server": "telegram",

385 "userConfig": {

386 "bot_token": { "description": "Telegram bot token", "sensitive": true },

387 "owner_id": { "description": "Your Telegram user ID", "sensitive": false }

388 }

389 }

390 ]

391}

392```

393 

394The `server` field is required and must match a key in the plugin's `mcpServers`. The optional per-channel `userConfig` uses the same schema as the top-level field, letting the plugin prompt for bot tokens or owner IDs when the plugin is enabled.

348 395 

349### Path behavior rules396### Path behavior rules

350 397 

6 6 

7> Welcome to Claude Code!7> Welcome to Claude Code!

8 8 

9export const InstallConfigurator = () => {

10 const TERM = {

11 mac: {

12 label: 'macOS / Linux',

13 cmd: 'curl -fsSL https://claude.ai/install.sh | bash'

14 },

15 win: {

16 label: 'Windows'

17 },

18 brew: {

19 label: 'Homebrew',

20 cmd: 'brew install --cask claude-code'

21 },

22 winget: {

23 label: 'WinGet',

24 cmd: 'winget install Anthropic.ClaudeCode'

25 }

26 };

27 const WIN_VARIANTS = {

28 ps: 'irm https://claude.ai/install.ps1 | iex',

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

30 };

31 const TABS = [{

32 key: 'terminal',

33 label: 'Terminal'

34 }, {

35 key: 'desktop',

36 label: 'Desktop'

37 }, {

38 key: 'vscode',

39 label: 'VS Code'

40 }, {

41 key: 'jetbrains',

42 label: 'JetBrains'

43 }];

44 const ALT_TARGETS = {

45 desktop: {

46 name: 'Desktop',

47 installLabel: 'Download the app',

48 installHref: 'https://claude.com/download?utm_source=claude_code&utm_medium=docs&utm_content=configurator_desktop_download',

49 guideHref: '/en/desktop-quickstart'

50 },

51 vscode: {

52 name: 'VS Code',

53 installLabel: 'Install from Marketplace',

54 installHref: 'https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code',

55 altCmd: 'code --install-extension anthropic.claude-code',

56 guideHref: '/en/vs-code'

57 },

58 jetbrains: {

59 name: 'JetBrains',

60 installLabel: 'Install from Marketplace',

61 installHref: 'https://plugins.jetbrains.com/plugin/27310-claude-code-beta-',

62 guideHref: '/en/jetbrains'

63 }

64 };

65 const PROVIDERS = [{

66 key: 'anthropic',

67 label: 'Anthropic'

68 }, {

69 key: 'bedrock',

70 label: 'Amazon Bedrock'

71 }, {

72 key: 'foundry',

73 label: 'Microsoft Foundry'

74 }, {

75 key: 'vertex',

76 label: 'Google Vertex AI'

77 }];

78 const PROVIDER_NOTICE = {

79 bedrock: <>

80 <strong>Configure your AWS account first.</strong> Running on Bedrock

81 requires model access enabled in the AWS console and IAM credentials.{' '}

82 <a href="/en/amazon-bedrock">Bedrock setup guide →</a>

83 </>,

84 vertex: <>

85 <strong>Configure your GCP project first.</strong> Running on Vertex AI

86 requires the Vertex API enabled and a service account with the right

87 permissions.{' '}

88 <a href="/en/google-vertex-ai">Vertex setup guide →</a>

89 </>,

90 foundry: <>

91 <strong>Configure your Azure resources first.</strong> Running on

92 Microsoft Foundry requires an Azure subscription with a Foundry resource

93 and model deployments provisioned.{' '}

94 <a href="/en/microsoft-foundry">Foundry setup guide →</a>

95 </>

96 };

97 const iconCheck = (size = 14) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="3" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

98 <polyline points="20 6 9 17 4 12" />

99 </svg>;

100 const iconCopy = (size = 14) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

101 <rect x="9" y="9" width="13" height="13" rx="2" />

102 <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />

103 </svg>;

104 const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

105 <line x1="5" y1="12" x2="19" y2="12" />

106 <polyline points="12 5 19 12 12 19" />

107 </svg>;

108 const iconArrowUpRight = (size = 14) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

109 <line x1="7" y1="17" x2="17" y2="7" />

110 <polyline points="7 7 17 7 17 17" />

111 </svg>;

112 const iconInfo = (size = 16) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

113 <circle cx="12" cy="12" r="10" />

114 <line x1="12" y1="16" x2="12" y2="12" />

115 <line x1="12" y1="8" x2="12.01" y2="8" />

116 </svg>;

117 const [target, setTarget] = useState('terminal');

118 const [team, setTeam] = useState(false);

119 const [provider, setProvider] = useState('anthropic');

120 const [pkg, setPkg] = useState(() => (/Win/).test(navigator.userAgent) ? 'win' : 'mac');

121 const [winCmd, setWinCmd] = useState(false);

122 const [copied, setCopied] = useState(null);

123 const copyTimer = useRef(null);

124 const handleCopy = async (text, key) => {

125 try {

126 await navigator.clipboard.writeText(text);

127 } catch {

128 const ta = document.createElement('textarea');

129 ta.value = text;

130 document.body.appendChild(ta);

131 ta.select();

132 document.execCommand('copy');

133 document.body.removeChild(ta);

134 }

135 clearTimeout(copyTimer.current);

136 setCopied(key);

137 copyTimer.current = setTimeout(() => setCopied(null), 1800);

138 };

139 const cardBodyCmd = (cmd, prompt) => {

140 const on = copied === 'term';

141 return <div className="cc-ic-card-body">

142 <span className="cc-ic-prompt">{prompt || '$'}</span>

143 <div className="cc-ic-cmd">{cmd}</div>

144 <button type="button" className={'cc-ic-copy' + (on ? ' cc-ic-copied' : '')} onClick={() => handleCopy(cmd, 'term')}>

145 {on ? iconCheck(13) : iconCopy(13)}

146 <span>{on ? 'Copied' : 'Copy'}</span>

147 </button>

148 </div>;

149 };

150 const isWinInstaller = pkg === 'win';

151 const isWinPrompt = pkg === 'win' || pkg === 'winget';

152 const terminalCmd = isWinInstaller ? WIN_VARIANTS[winCmd ? 'cmd' : 'ps'] : TERM[pkg].cmd;

153 const alt = ALT_TARGETS[target];

154 const showNotice = team && provider !== 'anthropic';

155 const STYLES = `

156.cc-ic {

157 --ic-slate: #141413;

158 --ic-clay: #d97757;

159 --ic-clay-deep: #c6613f;

160 --ic-gray-000: #ffffff;

161 --ic-gray-150: #f0eee6;

162 --ic-gray-550: #73726c;

163 --ic-gray-700: #3d3d3a;

164 --ic-border-subtle: rgba(31, 30, 29, 0.08);

165 --ic-border-default: rgba(31, 30, 29, 0.15);

166 --ic-border-strong: rgba(31, 30, 29, 0.3);

167 --ic-font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, 'Courier New', monospace;

168 font-family: 'Anthropic Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;

169 font-size: 14px; line-height: 1.5; color: var(--ic-slate);

170 margin: 8px 0 32px;

171}

172.dark .cc-ic {

173 --ic-slate: #f0eee6;

174 --ic-gray-000: #262624;

175 --ic-gray-150: #1f1e1d;

176 --ic-gray-550: #91908a;

177 --ic-gray-700: #bfbdb4;

178 --ic-border-subtle: rgba(240, 238, 230, 0.08);

179 --ic-border-default: rgba(240, 238, 230, 0.14);

180 --ic-border-strong: rgba(240, 238, 230, 0.28);

181}

182.dark .cc-ic-check { background: transparent; }

183.dark .cc-ic-card { border: 0.5px solid var(--ic-border-subtle); }

184.dark .cc-ic-p-pill.cc-ic-active { box-shadow: 0 1px 2px rgba(0, 0, 0, 0.3); }

185.cc-ic *, .cc-ic *::before, .cc-ic *::after { box-sizing: border-box; }

186.cc-ic a { text-decoration: none; }

187.cc-ic a:not([class]) { color: inherit; }

188.cc-ic button { font-family: inherit; cursor: pointer; }

189 

190.cc-ic-tab-strip {

191 display: inline-flex; gap: 2px;

192 padding: 4px; background: var(--ic-gray-150);

193 border-radius: 10px; overflow-x: auto;

194 max-width: 100%;

195}

196.cc-ic-tab {

197 appearance: none; background: none; border: none;

198 padding: 10px 18px; font-size: 15px; font-weight: 430;

199 color: var(--ic-gray-550); border-radius: 7px;

200 white-space: nowrap;

201 transition: color 0.12s, background-color 0.12s;

202}

203.cc-ic-tab:hover { color: var(--ic-gray-700); }

204.cc-ic-tab.cc-ic-active {

205 color: var(--ic-slate); font-weight: 500;

206 background: var(--ic-gray-000);

207 box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);

208}

209.dark .cc-ic-tab.cc-ic-active { box-shadow: 0 1px 3px rgba(0, 0, 0, 0.4); }

210 

211.cc-ic-team-wrap { padding: 16px 0 20px; }

212.cc-ic-team-toggle {

213 display: flex; align-items: center; gap: 12px; font-family: inherit;

214 padding: 12px 16px; font-size: 14px; font-weight: 430;

215 color: var(--ic-gray-700); cursor: pointer; user-select: none;

216 width: fit-content; background: var(--ic-gray-150);

217 border: 0.5px solid var(--ic-border-subtle); border-radius: 8px;

218 transition: border-color 0.15s;

219}

220.cc-ic-team-toggle:hover { border-color: var(--ic-border-default); }

221.cc-ic-team-toggle.cc-ic-checked {

222 background: rgba(217, 119, 87, 0.08);

223 border-color: rgba(217, 119, 87, 0.25);

224}

225.cc-ic-check {

226 width: 16px; height: 16px;

227 border: 1px solid var(--ic-border-strong); border-radius: 4px;

228 background: var(--ic-gray-000);

229 display: flex; align-items: center; justify-content: center;

230 flex-shrink: 0;

231}

232.cc-ic-check svg { color: #fff; display: none; }

233.cc-ic-team-toggle.cc-ic-checked .cc-ic-check { background: var(--ic-clay-deep); border-color: var(--ic-clay-deep); }

234.cc-ic-team-toggle.cc-ic-checked .cc-ic-check svg { display: block; }

235 

236.cc-ic-team-reveal { display: flex; flex-direction: column; gap: 12px; margin-bottom: 16px; }

237.cc-ic-sales {

238 display: flex; align-items: center; justify-content: space-between;

239 gap: 16px; padding: 14px 16px;

240 background: var(--ic-gray-000); border: 0.5px solid var(--ic-border-default);

241 border-radius: 8px; flex-wrap: wrap;

242}

243.cc-ic-sales-text { font-size: 13px; color: var(--ic-gray-700); line-height: 1.5; flex: 1; min-width: 200px; }

244.cc-ic-sales-text strong { font-weight: 550; color: var(--ic-slate); }

245.cc-ic-sales-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }

246.cc-ic-btn-clay {

247 display: inline-flex; align-items: center; gap: 8px;

248 background: var(--ic-clay-deep); color: #fff; border: none;

249 border-radius: 8px; padding: 8px 14px;

250 font-size: 13px; font-weight: 500;

251 transition: background-color 0.15s; white-space: nowrap;

252}

253.cc-ic-btn-clay:hover { background: var(--ic-clay); }

254.cc-ic-btn-ghost {

255 display: inline-flex; align-items: center; gap: 8px;

256 background: transparent; color: var(--ic-gray-700);

257 border: 0.5px solid var(--ic-border-default);

258 border-radius: 8px; padding: 8px 14px;

259 font-size: 13px; font-weight: 500;

260}

261.cc-ic-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }

262 

263.cc-ic-provider-bar {

264 display: flex; align-items: center; gap: 12px;

265 padding: 14px 16px; background: var(--ic-gray-150);

266 border-radius: 8px; font-size: 13px; flex-wrap: wrap;

267}

268.cc-ic-provider-bar .cc-ic-label { color: var(--ic-gray-550); flex-shrink: 0; }

269.cc-ic-provider-pills { display: flex; gap: 4px; flex-wrap: wrap; }

270.cc-ic-p-pill {

271 appearance: none; border: none; background: transparent;

272 padding: 6px 12px; border-radius: 6px;

273 font-size: 13px; font-weight: 430; color: var(--ic-gray-700);

274 white-space: nowrap;

275}

276.cc-ic-p-pill:hover { background: rgba(0, 0, 0, 0.04); }

277.cc-ic-p-pill.cc-ic-active {

278 background: var(--ic-gray-000); color: var(--ic-slate);

279 font-weight: 500; box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);

280}

281.cc-ic-provider-notice {

282 display: flex; padding: 16px 18px;

283 background: var(--ic-gray-000); border: 0.5px solid var(--ic-border-default);

284 border-radius: 8px; gap: 14px; align-items: flex-start;

285}

286.cc-ic-provider-notice > svg { color: var(--ic-gray-550); margin-top: 2px; flex-shrink: 0; }

287.cc-ic-provider-notice-body { font-size: 14px; line-height: 1.55; color: var(--ic-gray-700); }

288.cc-ic-provider-notice-body strong { font-weight: 550; color: var(--ic-slate); }

289.cc-ic-provider-notice-body a { color: var(--ic-clay-deep); font-weight: 500; }

290.cc-ic-provider-notice-body a:hover { text-decoration: underline; }

291 

292.cc-ic-card { background: #141413; border-radius: 12px; overflow: hidden; }

293.cc-ic-subtabs {

294 display: flex; align-items: center;

295 background: #1a1918;

296 border-bottom: 0.5px solid rgba(255, 255, 255, 0.08);

297 padding: 0 8px; overflow-x: auto;

298}

299.cc-ic-subtab-spacer { flex: 1; }

300.cc-ic-subtab {

301 appearance: none; background: none; border: none;

302 padding: 12px 16px; font-size: 12px;

303 color: rgba(255, 255, 255, 0.5);

304 position: relative; white-space: nowrap;

305}

306.cc-ic-subtab:hover { color: rgba(255, 255, 255, 0.75); }

307.cc-ic-subtab.cc-ic-active { color: #fff; }

308.cc-ic-subtab.cc-ic-active::after {

309 content: ''; position: absolute;

310 left: 12px; right: 12px; bottom: -0.5px;

311 height: 2px; background: var(--ic-clay);

312}

313.cc-ic-cmd-toggle {

314 display: flex; align-items: center; gap: 8px; font-family: inherit;

315 background: none; border: none;

316 padding: 0 12px; font-size: 11px;

317 color: rgba(255, 255, 255, 0.5);

318 cursor: pointer; user-select: none; white-space: nowrap;

319}

320.cc-ic-cmd-toggle:hover { color: rgba(255, 255, 255, 0.75); }

321.cc-ic-mini-check {

322 width: 12px; height: 12px;

323 border: 1px solid rgba(255, 255, 255, 0.3); border-radius: 3px;

324 display: flex; align-items: center; justify-content: center;

325 flex-shrink: 0;

326}

327.cc-ic-mini-check svg { color: #fff; display: none; }

328.cc-ic-cmd-toggle.cc-ic-checked .cc-ic-mini-check { background: var(--ic-clay-deep); border-color: var(--ic-clay-deep); }

329.cc-ic-cmd-toggle.cc-ic-checked .cc-ic-mini-check svg { display: block; }

330 

331.cc-ic-card-body { padding: 24px 26px; display: flex; align-items: flex-start; gap: 14px; }

332.cc-ic-prompt {

333 color: var(--ic-clay); font-family: var(--ic-font-mono);

334 font-size: 17px; user-select: none; padding-top: 2px;

335}

336.cc-ic-cmd {

337 flex: 1; font-family: var(--ic-font-mono);

338 font-size: 17px; color: #f0eee6;

339 line-height: 1.55; white-space: pre-wrap; word-break: break-word;

340}

341.cc-ic-copy {

342 display: inline-flex; align-items: center; gap: 6px;

343 background: rgba(255, 255, 255, 0.08);

344 border: 0.5px solid rgba(255, 255, 255, 0.12);

345 color: rgba(255, 255, 255, 0.85);

346 padding: 7px 13px; border-radius: 8px;

347 font-size: 13px; font-weight: 500; flex-shrink: 0;

348}

349.cc-ic-copy:hover { background: rgba(255, 255, 255, 0.14); }

350.cc-ic-copy.cc-ic-copied { background: var(--ic-clay-deep); border-color: var(--ic-clay-deep); color: #fff; }

351 

352.cc-ic-below {

353 margin-top: 12px; font-size: 13px; color: var(--ic-gray-550);

354 display: flex; gap: 16px; flex-wrap: wrap; align-items: baseline;

355}

356.cc-ic-below a { color: var(--ic-gray-700); border-bottom: 0.5px solid var(--ic-border-default); }

357.cc-ic-below a:hover { color: var(--ic-clay-deep); border-bottom-color: var(--ic-clay-deep); }

358.cc-ic-handoff {

359 padding: 20px 22px;

360 background: var(--ic-gray-000);

361 border: 0.5px solid var(--ic-border-default);

362 border-radius: 12px;

363}

364.cc-ic-handoff-head {

365 font-size: 14px; line-height: 1.55; color: var(--ic-gray-700);

366 margin-bottom: 14px;

367}

368.cc-ic-handoff-head strong { font-weight: 550; color: var(--ic-slate); }

369.cc-ic-handoff-actions { display: flex; gap: 10px; flex-wrap: wrap; }

370.cc-ic-handoff-alt {

371 margin-top: 12px; font-size: 12px; color: var(--ic-gray-550);

372}

373.cc-ic-handoff-alt code {

374 font-family: var(--ic-font-mono); font-size: 11px;

375 background: var(--ic-gray-150); padding: 2px 6px;

376 border-radius: 4px; color: var(--ic-gray-700);

377}

378.cc-ic-copy-sm {

379 appearance: none; border: none;

380 display: inline-flex; align-items: center; justify-content: center;

381 width: 22px; height: 22px;

382 margin-left: 4px; vertical-align: middle;

383 background: var(--ic-gray-150); color: var(--ic-gray-550);

384 border-radius: 4px;

385 transition: color 0.1s, background-color 0.1s;

386}

387.cc-ic-copy-sm:hover { color: var(--ic-gray-700); background: var(--ic-border-default); }

388.cc-ic-copy-sm.cc-ic-copied { background: var(--ic-clay-deep); color: #fff; }

389 

390@media (max-width: 720px) {

391 .cc-ic-tab { padding: 12px 14px; font-size: 14px; }

392 .cc-ic-sales-actions { width: 100%; }

393 .cc-ic-card-body { padding: 20px; }

394 .cc-ic-cmd { font-size: 15px; }

395}

396`;

397 return <div className="cc-ic not-prose">

398 <style>{STYLES}</style>

399 

400 {}

401 <div className="cc-ic-tab-strip" role="tablist">

402 {TABS.map(t => <button key={t.key} type="button" role="tab" aria-selected={target === t.key} className={'cc-ic-tab' + (target === t.key ? ' cc-ic-active' : '')} onClick={() => setTarget(t.key)}>

403 {t.label}

404 </button>)}

405 </div>

406 

407 {}

408 <div className="cc-ic-team-wrap">

409 <button type="button" role="switch" aria-checked={team} className={'cc-ic-team-toggle' + (team ? ' cc-ic-checked' : '')} onClick={() => setTeam(!team)}>

410 <span className="cc-ic-check">{iconCheck(11)}</span>

411 <span>

412 I’m buying for a team or company (SSO, AWS/Azure/GCP, central billing)

413 </span>

414 </button>

415 </div>

416 

417 {}

418 {team && <div className="cc-ic-team-reveal">

419 <div className="cc-ic-sales">

420 <div className="cc-ic-sales-text">

421 <strong>Set up your team:</strong> self-serve or talk to sales.

422 </div>

423 <div className="cc-ic-sales-actions">

424 <a href="https://claude.ai/upgrade?initialPlanType=team&amp;utm_source=claude_code&amp;utm_medium=docs&amp;utm_content=configurator_team_get_started" className="cc-ic-btn-ghost">

425 Get started

426 </a>

427 <a href="https://www.anthropic.com/contact-sales?utm_source=claude_code&amp;utm_medium=docs&amp;utm_content=configurator_team_contact_sales" className="cc-ic-btn-clay">

428 Contact sales {iconArrowRight()}

429 </a>

430 </div>

431 </div>

432 

433 <div className="cc-ic-provider-bar">

434 <span className="cc-ic-label">Run on</span>

435 <div className="cc-ic-provider-pills" role="radiogroup" aria-label="Provider">

436 {PROVIDERS.map(p => <button key={p.key} type="button" role="radio" aria-checked={provider === p.key} className={'cc-ic-p-pill' + (provider === p.key ? ' cc-ic-active' : '')} onClick={() => setProvider(p.key)}>

437 {p.label}

438 </button>)}

439 </div>

440 </div>

441 

442 {showNotice && <div className="cc-ic-provider-notice">

443 {iconInfo()}

444 <div className="cc-ic-provider-notice-body">

445 {PROVIDER_NOTICE[provider]}

446 </div>

447 </div>}

448 </div>}

449 

450 {}

451 {target === 'terminal' && <div className="cc-ic-card">

452 <div className="cc-ic-subtabs" role="tablist" aria-label="Install method">

453 {Object.keys(TERM).map(k => <button key={k} type="button" role="tab" aria-selected={pkg === k} className={'cc-ic-subtab' + (pkg === k ? ' cc-ic-active' : '')} onClick={() => setPkg(k)}>

454 {TERM[k].label}

455 </button>)}

456 <span className="cc-ic-subtab-spacer" />

457 {isWinInstaller && <button type="button" role="switch" aria-checked={winCmd} className={'cc-ic-cmd-toggle' + (winCmd ? ' cc-ic-checked' : '')} onClick={() => setWinCmd(!winCmd)}>

458 <span className="cc-ic-mini-check">{iconCheck(9)}</span>

459 <span>CMD instead of PowerShell</span>

460 </button>}

461 </div>

462 {cardBodyCmd(terminalCmd, isWinPrompt ? '>' : '$')}

463 </div>}

464 

465 {}

466 {target === 'terminal' && <div className="cc-ic-below">

467 {isWinInstaller && <span>

468 Requires{' '}

469 <a href="https://git-scm.com/downloads/win" target="_blank" rel="noopener">

470 Git for Windows

471 </a>.

472 </span>}

473 {(pkg === 'brew' || pkg === 'winget') && <span>

474 Does not auto-update. Run{' '}

475 <code>{pkg === 'brew' ? 'brew upgrade claude-code' : 'winget upgrade Anthropic.ClaudeCode'}</code>{' '}

476 periodically.

477 </span>}

478 <a href="/en/troubleshooting">Troubleshooting</a>

479 </div>}

480 

481 {alt && <div className="cc-ic-handoff">

482 <div className="cc-ic-handoff-head">

483 <strong>The steps below use the command line.</strong>{' '}

484 Prefer {alt.name}? Install here, then follow the {alt.name} guide instead.

485 </div>

486 <div className="cc-ic-handoff-actions">

487 <a href={alt.installHref} className="cc-ic-btn-clay" {...alt.installHref.startsWith('http') ? {

488 target: '_blank',

489 rel: 'noopener'

490 } : {}}>

491 {alt.installLabel} {iconArrowUpRight(13)}

492 </a>

493 <a href={alt.guideHref} className="cc-ic-btn-ghost">

494 {alt.name} guide {iconArrowRight(12)}

495 </a>

496 </div>

497 {alt.altCmd && <div className="cc-ic-handoff-alt">

498 or run <code>{alt.altCmd}</code>

499 <button type="button" className={'cc-ic-copy-sm' + (copied === 'alt' ? ' cc-ic-copied' : '')} onClick={() => handleCopy(alt.altCmd, 'alt')} aria-label="Copy command">

500 {copied === 'alt' ? iconCheck(11) : iconCopy(11)}

501 </button>

502 </div>}

503 </div>}

504 </div>;

505};

506 

507export const Experiment = ({flag, treatment, children}) => {

508 const VID_KEY = 'exp_vid';

509 const CONSENT_COUNTRIES = new Set(['AT', 'BE', 'BG', 'HR', 'CY', 'CZ', 'DK', 'EE', 'FI', 'FR', 'DE', 'GR', 'HU', 'IE', 'IT', 'LV', 'LT', 'LU', 'MT', 'NL', 'PL', 'PT', 'RO', 'SK', 'SI', 'ES', 'SE', 'RE', 'GP', 'MQ', 'GF', 'YT', 'BL', 'MF', 'PM', 'WF', 'PF', 'NC', 'AW', 'CW', 'SX', 'FO', 'GL', 'AX', 'GB', 'UK', 'AI', 'BM', 'IO', 'VG', 'KY', 'FK', 'GI', 'MS', 'PN', 'SH', 'TC', 'GG', 'JE', 'IM', 'CA', 'BR', 'IN']);

510 const fnv1a = s => {

511 let h = 0x811c9dc5;

512 for (let i = 0; i < s.length; i++) {

513 h ^= s.charCodeAt(i);

514 h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24);

515 }

516 return h >>> 0;

517 };

518 const bucket = (seed, vid) => fnv1a(fnv1a(seed + vid) + '') % 10000 < 5000 ? 'control' : 'treatment';

519 const [decision] = useState(() => {

520 const params = new URLSearchParams(location.search);

521 const force = params.get('gb-force');

522 if (force) {

523 for (const p of force.split(',')) {

524 const [k, v] = p.split(':');

525 if (k === flag) return {

526 variant: v || 'treatment',

527 track: false

528 };

529 }

530 }

531 if (navigator.globalPrivacyControl) {

532 return {

533 variant: 'control',

534 track: false

535 };

536 }

537 const prefsMatch = document.cookie.match(/(?:^|; )anthropic-consent-preferences=([^;]+)/);

538 if (prefsMatch) {

539 try {

540 if (JSON.parse(decodeURIComponent(prefsMatch[1])).analytics !== true) {

541 return {

542 variant: 'control',

543 track: false

544 };

545 }

546 } catch {

547 return {

548 variant: 'control',

549 track: false

550 };

551 }

552 } else {

553 const country = params.get('country')?.toUpperCase() || (document.cookie.match(/(?:^|; )cf_geo=([A-Z]{2})/) || [])[1];

554 if (!country || CONSENT_COUNTRIES.has(country)) {

555 return {

556 variant: 'control',

557 track: false

558 };

559 }

560 }

561 let vid;

562 try {

563 const ajsMatch = document.cookie.match(/(?:^|; )ajs_anonymous_id=([^;]+)/);

564 if (ajsMatch) {

565 vid = decodeURIComponent(ajsMatch[1]).replace(/^"|"$/g, '');

566 } else {

567 vid = localStorage.getItem(VID_KEY);

568 if (!vid) {

569 vid = crypto.randomUUID();

570 }

571 document.cookie = `ajs_anonymous_id=${vid}; domain=.claude.com; path=/; Secure; SameSite=Lax; max-age=31536000`;

572 }

573 try {

574 localStorage.setItem(VID_KEY, vid);

575 } catch {}

576 } catch {

577 return {

578 variant: 'control',

579 track: false

580 };

581 }

582 return {

583 variant: bucket(flag, vid),

584 track: true,

585 vid

586 };

587 });

588 useEffect(() => {

589 if (!decision.track) return;

590 fetch('https://api.anthropic.com/api/event_logging/v2/batch', {

591 method: 'POST',

592 headers: {

593 'Content-Type': 'application/json',

594 'x-service-name': 'claude_code_docs'

595 },

596 body: JSON.stringify({

597 events: [{

598 event_type: 'GrowthbookExperimentEvent',

599 event_data: {

600 device_id: decision.vid,

601 anonymous_id: decision.vid,

602 timestamp: new Date().toISOString(),

603 experiment_id: flag,

604 variation_id: decision.variant === 'treatment' ? 1 : 0,

605 environment: 'production'

606 }

607 }]

608 }),

609 keepalive: true

610 }).catch(() => {});

611 }, []);

612 return decision.variant === 'treatment' ? treatment : children;

613};

614 

9This quickstart guide will have you using AI-powered coding assistance in a few minutes. By the end, you'll understand how to use Claude Code for common development tasks.615This quickstart guide will have you using AI-powered coding assistance in a few minutes. By the end, you'll understand how to use Claude Code for common development tasks.

10 616 

617<Experiment flag="quickstart-install-configurator" treatment={<InstallConfigurator />} />

618 

11## Before you begin619## Before you begin

12 620 

13Make sure you have:621Make sure you have:

97 97 

98This opens a menu where you can choose between sandbox modes. If required dependencies are missing (such as `bubblewrap` or `socat` on Linux), the menu displays installation instructions for your platform.98This opens a menu where you can choose between sandbox modes. If required dependencies are missing (such as `bubblewrap` or `socat` on Linux), the menu displays installation instructions for your platform.

99 99 

100By default, if the sandbox cannot start (missing dependencies, unsupported platform, or platform restrictions), Claude Code shows a warning and runs commands without sandboxing. To make this a hard failure instead, set [`sandbox.failIfUnavailable`](/en/settings#sandbox-settings) to `true`. This is intended for managed deployments that require sandboxing as a security gate.

101 

100### Sandbox modes102### Sandbox modes

101 103 

102Claude Code offers two sandbox modes:104Claude Code offers two sandbox modes:

100 The legacy Windows path `C:\ProgramData\ClaudeCode\managed-settings.json` is no longer supported as of v2.1.75. Administrators who deployed settings to that location must migrate files to `C:\Program Files\ClaudeCode\managed-settings.json`.100 The legacy Windows path `C:\ProgramData\ClaudeCode\managed-settings.json` is no longer supported as of v2.1.75. Administrators who deployed settings to that location must migrate files to `C:\Program Files\ClaudeCode\managed-settings.json`.

101 </Warning>101 </Warning>

102 102 

103 File-based managed settings also support a drop-in directory at `managed-settings.d/` in the same system directory alongside `managed-settings.json`. This lets separate teams deploy independent policy fragments without coordinating edits to a single file.

104 

105 Following the systemd convention, `managed-settings.json` is merged first as the base, then all `*.json` files in the drop-in directory are sorted alphabetically and merged on top. Later files override earlier ones for scalar values; arrays are concatenated and de-duplicated; objects are deep-merged. Hidden files starting with `.` are ignored.

106 

107 Use numeric prefixes to control merge order, for example `10-telemetry.json` and `20-security.json`.

108 

103 See [managed settings](/en/permissions#managed-only-settings) and [Managed MCP configuration](/en/mcp#managed-mcp-configuration) for details.109 See [managed settings](/en/permissions#managed-only-settings) and [Managed MCP configuration](/en/mcp#managed-mcp-configuration) for details.

104 110 

105 <Note>111 <Note>

147`settings.json` supports a number of options:153`settings.json` supports a number of options:

148 154 

149| Key | Description | Example |155| Key | Description | Example |

150| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------- |156| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- |

151| `apiKeyHelper` | Custom script, to be executed in `/bin/sh`, to generate an auth value. This value will be sent as `X-Api-Key` and `Authorization: Bearer` headers for model requests | `/bin/generate_temp_api_key.sh` |157| `apiKeyHelper` | Custom script, to be executed in `/bin/sh`, to generate an auth value. This value will be sent as `X-Api-Key` and `Authorization: Bearer` headers for model requests | `/bin/generate_temp_api_key.sh` |

152| `autoMemoryDirectory` | Custom directory for [auto memory](/en/memory#storage-location) storage. Accepts `~/`-expanded paths. Not accepted in project settings (`.claude/settings.json`) to prevent shared repos from redirecting memory writes to sensitive locations. Accepted from policy, local, and user settings | `"~/my-memory-dir"` |158| `autoMemoryDirectory` | Custom directory for [auto memory](/en/memory#storage-location) storage. Accepts `~/`-expanded paths. Not accepted in project settings (`.claude/settings.json`) to prevent shared repos from redirecting memory writes to sensitive locations. Accepted from policy, local, and user settings | `"~/my-memory-dir"` |

153| `cleanupPeriodDays` | Sessions inactive for longer than this period are deleted at startup (default: 30 days).<br /><br />Setting to `0` deletes all existing transcripts at startup and disables session persistence entirely. No new `.jsonl` files are written, `/resume` shows no conversations, and hooks receive an empty `transcript_path`. | `20` |159| `cleanupPeriodDays` | Sessions inactive for longer than this period are deleted at startup (default: 30 days).<br /><br />Setting to `0` deletes all existing transcripts at startup and disables session persistence entirely. No new `.jsonl` files are written, `/resume` shows no conversations, and hooks receive an empty `transcript_path`. | `20` |

159| `permissions` | See table below for structure of permissions. | |165| `permissions` | See table below for structure of permissions. | |

160| `autoMode` | Customize what the [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) classifier blocks and allows. Contains `environment`, `allow`, and `soft_deny` arrays of prose rules. See [Configure the auto mode classifier](/en/permissions#configure-the-auto-mode-classifier). Not read from shared project settings | `{"environment": ["Trusted repo: github.example.com/acme"]}` |166| `autoMode` | Customize what the [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) classifier blocks and allows. Contains `environment`, `allow`, and `soft_deny` arrays of prose rules. See [Configure the auto mode classifier](/en/permissions#configure-the-auto-mode-classifier). Not read from shared project settings | `{"environment": ["Trusted repo: github.example.com/acme"]}` |

161| `disableAutoMode` | Set to `"disable"` to prevent [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) from being activated. Removes `auto` from the `Shift+Tab` cycle and rejects `--permission-mode auto` at startup. Most useful in [managed settings](/en/permissions#managed-settings) where users cannot override it | `"disable"` |167| `disableAutoMode` | Set to `"disable"` to prevent [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) from being activated. Removes `auto` from the `Shift+Tab` cycle and rejects `--permission-mode auto` at startup. Most useful in [managed settings](/en/permissions#managed-settings) where users cannot override it | `"disable"` |

168| `useAutoModeDuringPlan` | Whether plan mode uses auto mode semantics when auto mode is available. Default: `true`. Not read from shared project settings. Appears in `/config` as "Use auto mode during plan" | `false` |

162| `hooks` | Configure custom commands to run at lifecycle events. See [hooks documentation](/en/hooks) for format | See [hooks](/en/hooks) |169| `hooks` | Configure custom commands to run at lifecycle events. See [hooks documentation](/en/hooks) for format | See [hooks](/en/hooks) |

163| `disableAllHooks` | Disable all [hooks](/en/hooks) and any custom [status line](/en/statusline) | `true` |170| `disableAllHooks` | Disable all [hooks](/en/hooks) and any custom [status line](/en/statusline) | `true` |

164| `allowManagedHooksOnly` | (Managed settings only) Prevent loading of user, project, and plugin hooks. Only allows managed hooks and SDK hooks. See [Hook configuration](#hook-configuration) | `true` |171| `allowManagedHooksOnly` | (Managed settings only) Prevent loading of user, project, and plugin hooks. Only allows managed hooks and SDK hooks. See [Hook configuration](#hook-configuration) | `true` |

182| `enabledMcpjsonServers` | List of specific MCP servers from `.mcp.json` files to approve | `["memory", "github"]` |189| `enabledMcpjsonServers` | List of specific MCP servers from `.mcp.json` files to approve | `["memory", "github"]` |

183| `disabledMcpjsonServers` | List of specific MCP servers from `.mcp.json` files to reject | `["filesystem"]` |190| `disabledMcpjsonServers` | List of specific MCP servers from `.mcp.json` files to reject | `["filesystem"]` |

184| `channelsEnabled` | (Managed settings only) Allow [channels](/en/channels) for Team and Enterprise users. Unset or `false` blocks channel message delivery regardless of what users pass to `--channels` | `true` |191| `channelsEnabled` | (Managed settings only) Allow [channels](/en/channels) for Team and Enterprise users. Unset or `false` blocks channel message delivery regardless of what users pass to `--channels` | `true` |

192| `allowedChannelPlugins` | (Managed settings only) Allowlist of channel plugins that may push messages. Replaces the default Anthropic allowlist when set. Undefined = fall back to the default, empty array = block all channel plugins. Requires `channelsEnabled: true`. See [Restrict which channel plugins can run](/en/channels#restrict-which-channel-plugins-can-run) | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |

185| `allowedMcpServers` | When set in managed-settings.json, allowlist of MCP servers users can configure. Undefined = no restrictions, empty array = lockdown. Applies to all scopes. Denylist takes precedence. See [Managed MCP configuration](/en/mcp#managed-mcp-configuration) | `[{ "serverName": "github" }]` |193| `allowedMcpServers` | When set in managed-settings.json, allowlist of MCP servers users can configure. Undefined = no restrictions, empty array = lockdown. Applies to all scopes. Denylist takes precedence. See [Managed MCP configuration](/en/mcp#managed-mcp-configuration) | `[{ "serverName": "github" }]` |

186| `deniedMcpServers` | When set in managed-settings.json, denylist of MCP servers that are explicitly blocked. Applies to all scopes including managed servers. Denylist takes precedence over allowlist. See [Managed MCP configuration](/en/mcp#managed-mcp-configuration) | `[{ "serverName": "filesystem" }]` |194| `deniedMcpServers` | When set in managed-settings.json, denylist of MCP servers that are explicitly blocked. Applies to all scopes including managed servers. Denylist takes precedence over allowlist. See [Managed MCP configuration](/en/mcp#managed-mcp-configuration) | `[{ "serverName": "filesystem" }]` |

187| `strictKnownMarketplaces` | When set in managed-settings.json, allowlist of plugin marketplaces users can add. Undefined = no restrictions, empty array = lockdown. Applies to marketplace additions only. See [Managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |195| `strictKnownMarketplaces` | When set in managed-settings.json, allowlist of plugin marketplaces users can add. Undefined = no restrictions, empty array = lockdown. Applies to marketplace additions only. See [Managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |

257| Keys | Description | Example |265| Keys | Description | Example |

258| :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ |266| :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ |

259| `enabled` | Enable bash sandboxing (macOS, Linux, and WSL2). Default: false | `true` |267| `enabled` | Enable bash sandboxing (macOS, Linux, and WSL2). Default: false | `true` |

268| `failIfUnavailable` | Exit with an error at startup if `sandbox.enabled` is true but the sandbox cannot start (missing dependencies, unsupported platform, or platform restrictions). When false (default), a warning is shown and commands run unsandboxed. Intended for managed settings deployments that require sandboxing as a hard gate | `true` |

260| `autoAllowBashIfSandboxed` | Auto-approve bash commands when sandboxed. Default: true | `true` |269| `autoAllowBashIfSandboxed` | Auto-approve bash commands when sandboxed. Default: true | `true` |

261| `excludedCommands` | Commands that should run outside of the sandbox | `["git", "docker"]` |270| `excludedCommands` | Commands that should run outside of the sandbox | `["git", "docker"]` |

262| `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` |271| `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` |

4271. **Managed settings** ([server-managed](/en/server-managed-settings), [MDM/OS-level policies](#configuration-scopes), or [managed settings](/en/settings#settings-files))4361. **Managed settings** ([server-managed](/en/server-managed-settings), [MDM/OS-level policies](#configuration-scopes), or [managed settings](/en/settings#settings-files))

428 * Policies deployed by IT through server delivery, MDM configuration profiles, registry policies, or managed settings files437 * Policies deployed by IT through server delivery, MDM configuration profiles, registry policies, or managed settings files

429 * Cannot be overridden by any other level, including command line arguments438 * Cannot be overridden by any other level, including command line arguments

430 * Within the managed tier, precedence is: server-managed > MDM/OS-level policies > `managed-settings.json` > HKCU registry (Windows only). Only one managed source is used; sources do not merge.439 * Within the managed tier, precedence is: server-managed > MDM/OS-level policies > file-based (`managed-settings.d/*.json` + `managed-settings.json`) > HKCU registry (Windows only). Only one managed source is used; sources do not merge across tiers. Within the file-based tier, drop-in files and the base file are merged together.

431 440 

4322. **Command line arguments**4412. **Command line arguments**

433 * Temporary overrides for a specific session442 * Temporary overrides for a specific session

4415. **User settings** (`~/.claude/settings.json`)4505. **User settings** (`~/.claude/settings.json`)

442 * Personal global settings451 * Personal global settings

443 452 

444This hierarchy ensures that organizational policies are always enforced while still allowing teams and individuals to customize their experience.453This hierarchy ensures that organizational policies are always enforced while still allowing teams and individuals to customize their experience. The same precedence applies whether you run Claude Code from the CLI, the [VS Code extension](/en/vs-code), or a [JetBrains IDE](/en/jetbrains).

445 454 

446For 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.455For 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.

447 456 

184}'184}'

185```185```

186 186 

187The `--agents` flag accepts JSON with the same [frontmatter](#supported-frontmatter-fields) fields as file-based subagents: `description`, `prompt`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `memory`, `effort`, `background`, and `isolation`. Use `prompt` for the system prompt, equivalent to the markdown body in file-based subagents.187The `--agents` flag accepts JSON with the same [frontmatter](#supported-frontmatter-fields) fields as file-based subagents: `description`, `prompt`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, and `isolation`. Use `prompt` for the system prompt, equivalent to the markdown body in file-based subagents.

188 188 

189**Plugin subagents** come from [plugins](/en/plugins) you've installed. They appear in `/agents` alongside your custom subagents. See the [plugin components reference](/en/plugins-reference#agents) for details on creating plugin subagents.189**Plugin subagents** come from [plugins](/en/plugins) you've installed. They appear in `/agents` alongside your custom subagents. See the [plugin components reference](/en/plugins-reference#agents) for details on creating plugin subagents.

190 190 

234| `background` | No | Set to `true` to always run this subagent as a [background task](#run-subagents-in-foreground-or-background). Default: `false` |234| `background` | No | Set to `true` to always run this subagent as a [background task](#run-subagents-in-foreground-or-background). Default: `false` |

235| `effort` | No | Effort level when this subagent is active. Overrides the session effort level. Default: inherits from session. Options: `low`, `medium`, `high`, `max` (Opus 4.6 only) |235| `effort` | No | Effort level when this subagent is active. Overrides the session effort level. Default: inherits from session. Options: `low`, `medium`, `high`, `max` (Opus 4.6 only) |

236| `isolation` | No | Set to `worktree` to run the subagent in a temporary [git worktree](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), giving it an isolated copy of the repository. The worktree is automatically cleaned up if the subagent makes no changes |236| `isolation` | No | Set to `worktree` to run the subagent in a temporary [git worktree](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), giving it an isolated copy of the repository. The worktree is automatically cleaned up if the subagent makes no changes |

237| `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main session agent (via `--agent` or the `agent` setting). [Commands](/en/commands) and [skills](/en/skills) are processed. Prepended to any user-provided prompt |

237 238 

238### Choose a model239### Choose a model

239 240 

32| `TaskCreate` | Creates a new task in the task list | No |32| `TaskCreate` | Creates a new task in the task list | No |

33| `TaskGet` | Retrieves full details for a specific task | No |33| `TaskGet` | Retrieves full details for a specific task | No |

34| `TaskList` | Lists all tasks with their current status | No |34| `TaskList` | Lists all tasks with their current status | No |

35| `TaskOutput` | Retrieves output from a background task | No |35| `TaskOutput` | (Deprecated) Retrieves output from a background task. Prefer `Read` on the task's output file path | No |

36| `TaskStop` | Kills a running background task by ID | No |36| `TaskStop` | Kills a running background task by ID | No |

37| `TaskUpdate` | Updates task status, dependencies, details, or deletes tasks | No |37| `TaskUpdate` | Updates task status, dependencies, details, or deletes tasks | No |

38| `TodoWrite` | Manages the session task checklist. Available in non-interactive mode and the [Agent SDK](/en/headless); interactive sessions use TaskCreate, TaskGet, TaskList, and TaskUpdate instead | No |38| `TodoWrite` | Manages the session task checklist. Available in non-interactive mode and the [Agent SDK](/en/headless); interactive sessions use TaskCreate, TaskGet, TaskList, and TaskUpdate instead | No |