51 51
52When the same setting appears in multiple scopes, Claude Code applies them in priority order:52When the same setting appears in multiple scopes, Claude Code applies them in priority order:
53 53
541. **Managed** (highest): can't be overridden by any other scope, apart from the exceptions under [Settings precedence](#settings-precedence)541. **Managed** (highest): can't be overridden by any other scope, apart from the [exceptions to managed settings precedence](#exceptions-to-managed-settings-precedence)
552. **Command line arguments**: temporary session overrides552. **Command line arguments**: temporary session overrides
563. **Local**: overrides project and user settings563. **Local**: overrides project and user settings
574. **Project**: overrides user settings574. **Project**: overrides user settings
585. **User** (lowest): applies when nothing else specifies the setting585. **User** (lowest): applies when nothing else specifies the setting
59 59
60For example, if your user settings set `spinnerTipsEnabled` to `true` and project settings set it to `false`, the project value applies. Permission rules behave differently because they merge across scopes rather than override, and a few security-sensitive settings honor a restrictive value from certain scopes that otherwise couldn't override them. See [Settings precedence](#settings-precedence).60For example, if your user settings set `spinnerTipsEnabled` to `true` and project settings set it to `false`, the project value applies. Permission rules merge across scopes instead, and a few security-sensitive keys are exceptions. See [Settings precedence](#settings-precedence).
61 61
62### What uses scopes62### What uses scopes
63 63
93 Claude Code also saves permanent "don't ask again" [permission approvals](/docs/en/permissions#permission-system), such as Bash command approvals, to this file.93 Claude Code also saves permanent "don't ask again" [permission approvals](/docs/en/permissions#permission-system), such as Bash command approvals, to this file.
94 94
95 Because this file is yours rather than the repository's, its permission `allow` rules take effect without the [workspace trust](/docs/en/permissions#project-allow-rules-and-workspace-trust) step that `.claude/settings.json` allow rules require. If the repository supplies the file, for example by committing it, workspace trust still applies.95 Because this file is yours rather than the repository's, its permission `allow` rules take effect without the [workspace trust](/docs/en/permissions#project-allow-rules-and-workspace-trust) step that `.claude/settings.json` allow rules require. If the repository supplies the file, for example by committing it, workspace trust still applies.
96* **Managed settings**: For organizations that need centralized control, Claude Code supports multiple delivery mechanisms for managed settings. All use the same JSON format and cannot be overridden by user or project settings, apart from the exceptions listed under [Settings precedence](#settings-precedence):96* **Managed settings**: For organizations that need centralized control, Claude Code supports multiple delivery mechanisms for managed settings. All use the same JSON format and cannot be overridden by user or project settings:
97 97
98 * **Server-managed settings**: delivered remotely at sign-in, either from Anthropic's servers via the claude.ai admin console or from a self-hosted [Claude apps gateway](/docs/en/claude-apps-gateway). See [server-managed settings](/docs/en/server-managed-settings).98 * **Server-managed settings**: delivered remotely at sign-in, either from Anthropic's servers via the claude.ai admin console or from a self-hosted [Claude apps gateway](/docs/en/claude-apps-gateway). See [server-managed settings](/docs/en/server-managed-settings).
99 * **MDM/OS-level policies**: delivered through native device management on macOS and Windows:99 * **MDM/OS-level policies**: delivered through native device management on macOS and Windows:
190Security-enforcement fields are handled per field instead of being stripped wholesale when they are present but invalid:190Security-enforcement fields are handled per field instead of being stripped wholesale when they are present but invalid:
191 191
192| Field | Behavior when present but invalid |192| Field | Behavior when present but invalid |
193| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |193| :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
194| `allowedMcpServers` | Enforced as an empty allowlist, so no MCP servers are admitted until the value is fixed. An individual invalid entry is stripped and the valid subset is enforced. |194| `allowedMcpServers` | Enforced as an empty allowlist, so no MCP servers are admitted until the value is fixed. An individual invalid entry is stripped and the valid subset is enforced. |
195| `allowManagedHooksOnly` | Treated as `true`, so the [hook restrictions](#hook-configuration) apply until the value is fixed and, unless `disableCommandPluginSources` is explicitly `false`, command-sourced plugins are disabled. Applies in v2.1.229 and later. |
195| `allowManagedMcpServersOnly` | Treated as `true`. |196| `allowManagedMcpServersOnly` | Treated as `true`. |
197| `disableCommandPluginSources` | Treated as `true`, so command-sourced plugins stay disabled until the value is fixed. Applies in v2.1.229 and later. |
196| `availableModels` | Enforced as an empty allowlist, so only the Default model is available until the value is fixed. An individual non-string entry is stripped and the valid subset is enforced. Applies in v2.1.175 and later. |198| `availableModels` | Enforced as an empty allowlist, so only the Default model is available until the value is fixed. An individual non-string entry is stripped and the valid subset is enforced. Applies in v2.1.175 and later. |
197| `enforceAvailableModels` | Treated as `true`. Applies in v2.1.175 and later. |199| `enforceAvailableModels` | Treated as `true`. Applies in v2.1.175 and later. |
198| `forceLoginOrgUUID` | No organization is permitted to log in until the value is fixed. |200| `forceLoginOrgUUID` | No organization is permitted to log in until the value is fixed. |
220| `advisorModel` | Model for the server-side [advisor tool](/docs/en/advisor). Accepts the model aliases `"fable"`, `"opus"`, and `"sonnet"`, or a full model ID. `"fable"` requires [Fable 5 access](/docs/en/advisor#choose-an-advisor-model). Written automatically when you run `/advisor`. Unset to disable the advisor. | `"opus"` |222| `advisorModel` | Model for the server-side [advisor tool](/docs/en/advisor). Accepts the model aliases `"fable"`, `"opus"`, and `"sonnet"`, or a full model ID. `"fable"` requires [Fable 5 access](/docs/en/advisor#choose-an-advisor-model). Written automatically when you run `/advisor`. Unset to disable the advisor. | `"opus"` |
221| `agent` | Run the main thread as a named subagent, and set the default agent for sessions dispatched from `claude agents`. Applies that subagent's system prompt, tool restrictions, and model. See [Invoke subagents explicitly](/docs/en/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |223| `agent` | Run the main thread as a named subagent, and set the default agent for sessions dispatched from `claude agents`. Applies that subagent's system prompt, tool restrictions, and model. See [Invoke subagents explicitly](/docs/en/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |
222| `agentPushNotifEnabled` | **Default**: `false`. When [Remote Control](/docs/en/remote-control) is connected, allow Claude to send proactive push notifications to your phone, for example when a long task finishes. Appears in `/config` as **Push when Claude decides**. See [Mobile push notifications](/docs/en/remote-control#mobile-push-notifications) | `true` |224| `agentPushNotifEnabled` | **Default**: `false`. When [Remote Control](/docs/en/remote-control) is connected, allow Claude to send proactive push notifications to your phone, for example when a long task finishes. Appears in `/config` as **Push when Claude decides**. See [Mobile push notifications](/docs/en/remote-control#mobile-push-notifications) | `true` |
223| `allowAllClaudeAiMcps` | (Managed settings only) Load claude.ai connectors alongside a deployed `managed-mcp.json`, which otherwise takes exclusive control and suppresses them. See [Managed MCP configuration](/docs/en/managed-mcp) | `true` |225| `allowAllClaudeAiMcps` | (Managed settings only) Load the claude.ai connectors Claude Code fetches itself alongside a deployed `managed-mcp.json`, which otherwise takes exclusive control and suppresses them. Connectors delivered to cloud sessions stay suppressed. See [Managed MCP configuration](/docs/en/managed-mcp#allow-claude-ai-connectors-alongside-the-managed-set) | `true` |
224| `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](/docs/en/channels#restrict-which-channel-plugins-can-run) | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |226| `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](/docs/en/channels#restrict-which-channel-plugins-can-run) | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |
225| `allowedHttpHookUrls` | Allowlist of URL patterns that HTTP hooks may target. Supports `*` as a wildcard. When set, hooks with non-matching URLs are blocked. Undefined = no restrictions, empty array = block all HTTP hooks. Arrays merge across settings sources. See [Hook configuration](#hook-configuration) | `["https://hooks.example.com/*"]` |227| `allowedHttpHookUrls` | Allowlist of URL patterns that HTTP hooks may target. Supports `*` as a wildcard. When set, hooks with non-matching URLs are blocked. Undefined = no restrictions, empty array = block all HTTP hooks. Arrays merge across settings sources. See [Hook configuration](#hook-configuration) | `["https://hooks.example.com/*"]` |
226| `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](/docs/en/managed-mcp) | `[{ "serverName": "github" }]` |228| `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](/docs/en/managed-mcp) | `[{ "serverName": "github" }]` |
227| `allowManagedHooksOnly` | (Managed settings only) Only managed hooks, SDK hooks, and hooks from plugins force-enabled in managed settings `enabledPlugins` are loaded. User, project, and all other plugin hooks are blocked. See [Hook configuration](#hook-configuration) | `true` |229| `allowManagedHooksOnly` | (Managed settings only) Restrict which hooks run; see [Hook configuration](#hook-configuration) for the full effect list | `true` |
228| `allowManagedMcpServersOnly` | (Managed settings only) Only `allowedMcpServers` from managed settings are respected. `deniedMcpServers` still merges from all sources. Users can still add MCP servers, but only the admin-defined allowlist applies. See [Managed MCP configuration](/docs/en/managed-mcp) | `true` |230| `allowManagedMcpServersOnly` | (Managed settings only) Only `allowedMcpServers` from managed settings are respected. `deniedMcpServers` still merges from all sources. Users can still add MCP servers, but only the admin-defined allowlist applies. See [Managed MCP configuration](/docs/en/managed-mcp) | `true` |
229| `allowManagedPermissionRulesOnly` | (Managed settings only) Prevent user and project settings from defining `allow`, `ask`, or `deny` permission rules. Only rules in managed settings apply. See [Managed-only settings](/docs/en/permissions#managed-only-settings) | `true` |231| `allowManagedPermissionRulesOnly` | (Managed settings only) Prevent user and project settings from defining `allow`, `ask`, or `deny` permission rules. Only rules in managed settings apply. See [Managed-only settings](/docs/en/permissions#managed-only-settings) | `true` |
230| `alwaysThinkingEnabled` | Enable [extended thinking](/docs/en/model-config#extended-thinking) by default for all sessions. Typically configured via the `/config` command rather than editing directly. To force thinking off regardless of this setting, set [`MAX_THINKING_TOKENS=0`](/docs/en/env-vars) in `env`, which disables thinking on the Anthropic API except on Fable 5, which cannot have thinking turned off. On [third-party providers](/docs/en/third-party-integrations) this omits the `thinking` parameter instead, and adaptive-reasoning models may still think | `true` |232| `alwaysThinkingEnabled` | Enable [extended thinking](/docs/en/model-config#extended-thinking) by default for all sessions. Typically configured via the `/config` command rather than editing directly. To force thinking off regardless of this setting, set [`MAX_THINKING_TOKENS=0`](/docs/en/env-vars) in `env`, which disables thinking on the Anthropic API except on Fable 5, which cannot have thinking turned off. On [third-party providers](/docs/en/third-party-integrations) this omits the `thinking` parameter instead, and adaptive-reasoning models may still think | `true` |
233| `attribution` | Customize attribution for git commits and pull requests. See [Attribution settings](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |235| `attribution` | Customize attribution for git commits and pull requests. See [Attribution settings](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |
234| `autoCompactEnabled` | **Default**: `true`. Automatically compact the conversation when context approaches the limit. Appears in `/config` as **Auto-compact**. To disable via environment variable, set [`DISABLE_AUTO_COMPACT`](/docs/en/env-vars) in `env` | `false` |236| `autoCompactEnabled` | **Default**: `true`. Automatically compact the conversation when context approaches the limit. Appears in `/config` as **Auto-compact**. To disable via environment variable, set [`DISABLE_AUTO_COMPACT`](/docs/en/env-vars) in `env` | `false` |
235| `autoCompactWindow` | How full the context window gets before Claude Code [compacts automatically](/docs/en/context-window#when-your-context-fills-up), in tokens from `100000` to `1000000`. When unset, Claude Code uses a window tuned for your model. Set it with the [`/autocompact`](/docs/en/commands#all-commands) command, which writes this key to user settings; the [`--autocompact`](/docs/en/cli-reference#cli-flags) flag and the [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/en/env-vars) environment variable can override it. [Set the auto-compact window](/docs/en/model-config#set-the-auto-compact-window) covers how they interact | `500000` |237| `autoCompactWindow` | How full the context window gets before Claude Code [compacts automatically](/docs/en/context-window#when-your-context-fills-up), in tokens from `100000` to `1000000`. When unset, Claude Code uses a window tuned for your model. Set it with the [`/autocompact`](/docs/en/commands#all-commands) command, which writes this key to user settings; the [`--autocompact`](/docs/en/cli-reference#cli-flags) flag and the [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/en/env-vars) environment variable can override it. [Set the auto-compact window](/docs/en/model-config#set-the-auto-compact-window) covers how they interact | `500000` |
236| `autoMemoryDirectory` | Custom directory for [auto memory](/docs/en/memory#storage-location) storage. Accepts an absolute path or a `~/`-prefixed path. From project or local settings, this is honored only after you accept the workspace trust dialog, since a cloned repository can supply this file | `"~/my-memory-dir"` |238| `autoMemoryDirectory` | Custom directory for [auto memory](/docs/en/memory#storage-location) storage. Accepts an absolute path or a `~/`-prefixed path. From project or local settings, Claude Code honors it under the same [workspace trust rule as hooks](/docs/en/permissions#what-runs-before-you-trust-a-folder), since a cloned repository can supply this file | `"~/my-memory-dir"` |
237| `autoMemoryEnabled` | **Default**: `true`. Enable [auto memory](/docs/en/memory#enable-or-disable-auto-memory). When `false`, Claude does not read from or write to the auto memory directory. You can also toggle this with `/memory` during a session. To disable via environment variable, set [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/docs/en/env-vars) in `env` | `false` |239| `autoMemoryEnabled` | **Default**: `true`. Enable [auto memory](/docs/en/memory#enable-or-disable-auto-memory). When `false`, Claude does not read from or write to the auto memory directory. You can also toggle this with `/memory` during a session. To disable via environment variable, set [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/docs/en/env-vars) in `env` | `false` |
238| `autoMode` | Customize what the [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) classifier blocks and allows. Contains `environment`, `allow`, `soft_deny`, and `hard_deny` arrays of prose rules. Include the literal string `"$defaults"` in an array to inherit the built-in rules at that position. See [Configure auto mode](/docs/en/auto-mode-config). Read from user settings, the `--settings` flag, and managed settings only. Ignored in project `.claude/settings.json` and local `.claude/settings.local.json`. Before v2.1.207, `.claude/settings.local.json` was also read | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |240| `autoMode` | Customize what the [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) classifier blocks and allows. Contains `environment`, `allow`, `soft_deny`, and `hard_deny` arrays of prose rules. Include the literal string `"$defaults"` in an array to inherit the built-in rules at that position. See [Configure auto mode](/docs/en/auto-mode-config). Read from user settings, the `--settings` flag, and managed settings only. Ignored in project `.claude/settings.json` and local `.claude/settings.local.json`. Before v2.1.207, `.claude/settings.local.json` was also read | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |
239| `autoMode.classifyAllShell` | **Default**: `false`. When `true`, suspends every Bash and PowerShell allow rule while auto mode is active so all shell commands route through the classifier, not only rules that match arbitrary-code-execution patterns. See [Route all shell commands through the classifier](/docs/en/auto-mode-config#route-all-shell-commands-through-the-classifier). Requires Claude Code v2.1.193 or later | `true` |241| `autoMode.classifyAllShell` | **Default**: `false`. When `true`, suspends every Bash and PowerShell allow rule while auto mode is active so all shell commands route through the classifier, not only rules that match arbitrary-code-execution patterns. See [Route all shell commands through the classifier](/docs/en/auto-mode-config#route-all-shell-commands-through-the-classifier). Requires Claude Code v2.1.193 or later | `true` |
256| `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](/docs/en/managed-mcp) | `[{ "serverName": "filesystem" }]` |258| `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](/docs/en/managed-mcp) | `[{ "serverName": "filesystem" }]` |
257| `dialogExpiry` | **Default**: `"5m"`. Deadline for dialogs Claude Code [forwards to a remote client](/docs/en/remote-control#limitations), such as a Remote Control or SDK host, and for the approval dialog for a [held cross-session message](/docs/en/cross-session-messaging#control-inbound-messages). When no answer arrives before the deadline, Claude Code cancels the dialog and continues with its no-action default. Permission prompts and [`AskUserQuestion`](/docs/en/tools-reference#askuserquestion-tool-behavior) questions use their own flows and aren't governed by this deadline. Accepts `"60s"`, `"5m"`, `"10m"`, or `"never"`, which disables the deadline. The [`CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS`](/docs/en/env-vars) environment variable overrides this setting. Read from user, managed, and `--settings` sources only. Requires Claude Code v2.1.224 or later | `"10m"` |259| `dialogExpiry` | **Default**: `"5m"`. Deadline for dialogs Claude Code [forwards to a remote client](/docs/en/remote-control#limitations), such as a Remote Control or SDK host, and for the approval dialog for a [held cross-session message](/docs/en/cross-session-messaging#control-inbound-messages). When no answer arrives before the deadline, Claude Code cancels the dialog and continues with its no-action default. Permission prompts and [`AskUserQuestion`](/docs/en/tools-reference#askuserquestion-tool-behavior) questions use their own flows and aren't governed by this deadline. Accepts `"60s"`, `"5m"`, `"10m"`, or `"never"`, which disables the deadline. The [`CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS`](/docs/en/env-vars) environment variable overrides this setting. Read from user, managed, and `--settings` sources only. Requires Claude Code v2.1.224 or later | `"10m"` |
258| `disableAgentView` | Set to `true` to turn off [background agents and agent view](/docs/en/agent-view): `claude agents`, `--bg`, `/background`, and the on-demand supervisor. Typically set in [managed settings](/docs/en/permissions#managed-settings). Equivalent to setting `CLAUDE_CODE_DISABLE_AGENT_VIEW` to `1` | `true` |260| `disableAgentView` | Set to `true` to turn off [background agents and agent view](/docs/en/agent-view): `claude agents`, `--bg`, `/background`, and the on-demand supervisor. Typically set in [managed settings](/docs/en/permissions#managed-settings). Equivalent to setting `CLAUDE_CODE_DISABLE_AGENT_VIEW` to `1` | `true` |
259| `disableAllHooks` | Disable all [hooks](/docs/en/hooks) and any custom [status line](/docs/en/statusline) | `true` |261| `disableAllHooks` | Disable all [hooks](/docs/en/hooks#disable-or-remove-hooks), any custom [status line](/docs/en/statusline), and any custom [file suggestion](#file-suggestion-settings) command | `true` |
260| `disableArtifact` | Set to `true` to disable the [Artifact](/docs/en/artifacts) tool, which publishes session output as a private web page on claude.ai. Equivalent to setting `CLAUDE_CODE_DISABLE_ARTIFACT` to `1` | `true` |262| `disableArtifact` | Set to `true` to disable the [Artifact](/docs/en/artifacts) tool, which publishes session output as a private web page on claude.ai. Equivalent to setting `CLAUDE_CODE_DISABLE_ARTIFACT` to `1` | `true` |
261| `disableAutoMode` | Set to `"disable"` to prevent [auto mode](/docs/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. Also accepted under `permissions` as `permissions.disableAutoMode`. Most useful in [managed settings](/docs/en/permissions#managed-settings) where users cannot override it | `"disable"` |263| `disableAutoMode` | Set to `"disable"` to prevent [auto mode](/docs/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. Also accepted under `permissions` as `permissions.disableAutoMode`. Most useful in [managed settings](/docs/en/permissions#managed-settings) where users cannot override it | `"disable"` |
262| `disableBrowserExternalNavigation` | (Managed settings only) Set to `true` to turn off external browsing in the desktop app's [Browser pane](/docs/en/desktop#browse-external-sites). Neither users nor Claude can navigate to external sites, and localhost dev server previews are unaffected. The value must be the JSON boolean `true`; the string `"true"` is ignored | `true` |264| `disableBrowserExternalNavigation` | (Managed settings only) Set to `true` to turn off external browsing in the desktop app's [Browser pane](/docs/en/desktop#browse-external-sites). Neither users nor Claude can navigate to external sites, and localhost dev server previews are unaffected. The value must be the JSON boolean `true`; the string `"true"` is ignored | `true` |
263| `disableBundledSkills` | Set to `true` to disable the [skills](/docs/en/skills) and workflows included with Claude Code: bundled skills and workflows are removed entirely, while built-in commands like `/init` stay typable but are hidden from the model. `/doctor` stays typable like the built-in commands; hide it with [`DISABLE_DOCTOR_COMMAND`](/docs/en/env-vars) instead. Skills from plugins, `.claude/skills/`, and `.claude/commands/` are unaffected. Equivalent to setting `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` to `1` | `true` |265| `disableBundledSkills` | Set to `true` to disable the [skills](/docs/en/skills) and workflows included with Claude Code: bundled skills and workflows are removed entirely, while built-in commands like `/init` stay typable but are hidden from the model. `/doctor` stays typable like the built-in commands; hide it with [`DISABLE_DOCTOR_COMMAND`](/docs/en/env-vars) instead. Skills from plugins, `.claude/skills/`, and `.claude/commands/` are unaffected. Equivalent to setting `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` to `1` | `true` |
264| `disableClaudeAiConnectors` | Disable [claude.ai MCP connectors](/docs/en/mcp#use-mcp-servers-from-claude-ai) so they are not auto-fetched or connected. Set in any settings scope. `true` in any source takes precedence, so a checked-in project `.claude/settings.json` can opt a repo out of cloud connectors, but a project-level `false` cannot override a user- or policy-level `true`. Servers passed explicitly via `--mcp-config` are unaffected. To deny individual connectors instead of all of them, use [`deniedMcpServers`](/docs/en/managed-mcp). Requires Claude Code v2.1.182 or later | `true` |266| `disableClaudeAiConnectors` | Disable [claude.ai MCP connectors](/docs/en/mcp#use-mcp-servers-from-claude-ai) so they are not auto-fetched or connected. Set in any settings scope. `true` in any source takes precedence, so a checked-in project `.claude/settings.json` can opt a repo out of cloud connectors, but a project-level `false` cannot override a user- or policy-level `true`. Servers passed explicitly via `--mcp-config` are unaffected. To deny individual connectors instead of all of them, use [`deniedMcpServers`](/docs/en/managed-mcp). Requires Claude Code v2.1.182 or later | `true` |
267| `disableCommandPluginSources` | (Managed settings only) Control the [`command` plugin source](/docs/en/plugin-marketplaces#command-sources), which installs a plugin by running a marketplace-declared command on the user's machine. Set to `true` to block command-sourced plugins entirely. Claude Code never runs the command, doesn't install or update those plugins, and stops loading the ones already installed. Set to `false` to allow them explicitly. When unset, Claude Code follows [`allowManagedHooksOnly`](#hook-configuration), so an organization that restricts hook execution to managed settings gets command sources disabled too. Requires Claude Code v2.1.229 or later | `true` |
265| `disableDeepLinkRegistration` | Set to `"disable"` to prevent Claude Code from registering the `claude-cli://` protocol handler with the operating system when you send the first prompt of an interactive session. [Deep links](/docs/en/deep-links) let external tools open a Claude Code session with a pre-filled prompt. Useful in environments where protocol handler registration is restricted or managed separately | `"disable"` |268| `disableDeepLinkRegistration` | Set to `"disable"` to prevent Claude Code from registering the `claude-cli://` protocol handler with the operating system when you send the first prompt of an interactive session. [Deep links](/docs/en/deep-links) let external tools open a Claude Code session with a pre-filled prompt. Useful in environments where protocol handler registration is restricted or managed separately | `"disable"` |
266| `disabledMcpjsonServers` | List of specific MCP servers from `.mcp.json` files to reject | `["filesystem"]` |269| `disabledMcpjsonServers` | List of specific MCP servers from `.mcp.json` files to reject | `["filesystem"]` |
267| `disableMobileSimulatorTools` | (Managed settings only) Set to `true` to block Claude's tools for the desktop app's [iOS Simulator pane](/docs/en/desktop-ios-simulator#turn-off-simulator-access). Users keep manual use of the pane; only Claude's access is removed. The value must be the JSON boolean `true`; any other value is ignored, and a malformed value such as `"true"` or `1` logs a warning | `true` |270| `disableMobileSimulatorTools` | (Managed settings only) Set to `true` to block Claude's tools for the desktop app's [iOS Simulator pane](/docs/en/desktop-ios-simulator#turn-off-simulator-access). Users keep manual use of the pane; only Claude's access is removed. The value must be the JSON boolean `true`; any other value is ignored, and a malformed value such as `"true"` or `1` logs a warning | `true` |
300| `modelOverrides` | Map Anthropic model IDs to provider-specific model IDs such as Amazon Bedrock inference profile ARNs. Each model picker entry uses its mapped value when calling the provider API. See [Override model IDs per version](/docs/en/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |303| `modelOverrides` | Map Anthropic model IDs to provider-specific model IDs such as Amazon Bedrock inference profile ARNs. Each model picker entry uses its mapped value when calling the provider API. See [Override model IDs per version](/docs/en/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |
301| `otelHeadersHelper` | Script to generate dynamic OpenTelemetry headers. Runs at startup and periodically. Set the refresh interval with [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/docs/en/env-vars). See [Dynamic headers](/docs/en/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |304| `otelHeadersHelper` | Script to generate dynamic OpenTelemetry headers. Runs at startup and periodically. Set the refresh interval with [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/docs/en/env-vars). See [Dynamic headers](/docs/en/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |
302| `outputStyle` | Configure an output style to adjust the system prompt. See [output styles documentation](/docs/en/output-styles) | `"Explanatory"` |305| `outputStyle` | Configure an output style to adjust the system prompt. See [output styles documentation](/docs/en/output-styles) | `"Explanatory"` |
303| `parentSettingsBehavior` | (Managed settings only) **Default**: `"first-wins"`. Controls whether Claude Code applies managed settings supplied by an embedding host process, such as the Agent SDK or an IDE extension, when an admin-deployed managed tier is also present. With `"first-wins"`, Claude Code drops the parent-supplied settings. With `"merge"`, Claude Code applies them under the admin tier through a restrictive-only filter. For the filter's limits and how the managed sources interact, see [Settings precedence](#settings-precedence) and [Restrict parent settings](/docs/en/claude-apps-gateway#restrict-parent-settings) | `"merge"` |306| `parentSettingsBehavior` | (Managed settings only) **Default**: `"first-wins"`. Controls whether Claude Code applies managed settings supplied by an embedding host process, such as the Agent SDK or an IDE extension, when an admin-deployed managed tier is also present. With `"first-wins"`, Claude Code drops the parent-supplied settings. With `"merge"`, Claude Code applies them under the admin tier through a restrictive-only filter. For the filter's limits and how the managed sources interact, see [Parent settings from embedding hosts](#parent-settings-from-embedding-hosts) and [Restrict parent settings](/docs/en/claude-apps-gateway#restrict-parent-settings) | `"merge"` |
304| `permissions` | See table below for structure of permissions. | |307| `permissions` | See table below for structure of permissions. | |
305| `plansDirectory` | **Default**: `~/.claude/plans`. Customize where plan files are stored. Path is relative to project root. | `"./plans"` |308| `plansDirectory` | **Default**: `~/.claude/plans`. Customize where plan files are stored. Path is relative to project root. | `"./plans"` |
306| `pluginSuggestionMarketplaces` | (Managed settings only) Marketplace names whose plugins can appear as contextual install suggestions. No marketplace-declared suggestions surface without this allowlist; the built-in first-party frontend-design tip is unaffected. Suggestions come from each plugin's `relevance` declaration in its marketplace entry. A name only takes effect when the marketplace is registered on the machine and its registered source is also declared in managed settings, either as the `extraKnownMarketplaces` entry for that name or as an entry of `strictKnownMarketplaces`. A marketplace registered from a different source under an allowlisted name is ignored. The official marketplace is exempt from the source requirement: allowlisting its name alone suffices, since that name can only register from the official Anthropic source. | `["acme-corp-plugins"]` |309| `pluginSuggestionMarketplaces` | (Managed settings only) Marketplace names whose plugins can appear as contextual install suggestions. No marketplace-declared suggestions surface without this allowlist; the built-in first-party frontend-design tip is unaffected. Suggestions come from each plugin's `relevance` declaration in its marketplace entry. A name only takes effect when the marketplace is registered on the machine and its registered source is also declared in managed settings, either as the `extraKnownMarketplaces` entry for that name or as an entry of `strictKnownMarketplaces`. A marketplace registered from a different source under an allowlisted name is ignored. The official marketplace is exempt from the source requirement: allowlisting its name alone suffices, since that name can only register from the official Anthropic source. | `["acme-corp-plugins"]` |
312| `promptSuggestionEnabled` | **Default**: `true`. Show [prompt suggestions](/docs/en/interactive-mode#prompt-suggestions), the grayed-out predictions that appear in your prompt input. Set to `false` or turn off **Prompt suggestions** in `/config` to disable. [`CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION`](/docs/en/env-vars) takes precedence when both are set | `false` |315| `promptSuggestionEnabled` | **Default**: `true`. Show [prompt suggestions](/docs/en/interactive-mode#prompt-suggestions), the grayed-out predictions that appear in your prompt input. Set to `false` or turn off **Prompt suggestions** in `/config` to disable. [`CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION`](/docs/en/env-vars) takes precedence when both are set | `false` |
313| `prUrlTemplate` | URL template for the PR badge shown in the footer and in tool-result summaries. Substitutes `{host}`, `{owner}`, `{repo}`, `{number}`, and `{url}` from the `gh`-reported PR URL. Use to point PR links at an internal code-review tool instead of `github.com`. Does not affect `#123` autolinks in Claude's prose | `"https://reviews.example.com/{owner}/{repo}/pull/{number}"` |316| `prUrlTemplate` | URL template for the PR badge shown in the footer and in tool-result summaries. Substitutes `{host}`, `{owner}`, `{repo}`, `{number}`, and `{url}` from the `gh`-reported PR URL. Use to point PR links at an internal code-review tool instead of `github.com`. Does not affect `#123` autolinks in Claude's prose | `"https://reviews.example.com/{owner}/{repo}/pull/{number}"` |
314| `remote.defaultEnvironmentId` | Default [cloud environment](/docs/en/cloud-environments) for cloud sessions you create from the CLI, such as with `claude --cloud`. Written to user settings when you pick an environment with [`/remote-env`](/docs/en/cloud-environments#select-an-environment-from-the-cli). For Anthropic-hosted environment IDs (`env_...`), follows the standard settings precedence, so a value in a repo's project settings overrides the user-level pick. A [self-hosted environment](/docs/en/self-hosted-environments) ID (`ccpool_...`) is honored only from user settings, managed settings, and the `--settings` CLI flag; Claude Code ignores one in a repo's project or local settings with a warning, so a checked-in file can't steer sessions onto a self-hosted environment you didn't choose | `"env_0123abcd"` |317| `remote.defaultEnvironmentId` | Default [cloud environment](/docs/en/cloud-environments) for cloud sessions you create from the CLI, such as with `claude --cloud`. Written to user settings when you pick an environment with [`/remote-env`](/docs/en/cloud-environments#select-an-environment-from-the-cli). For Anthropic-hosted environment IDs (`env_...`), follows the standard settings precedence, so a value in a repo's project settings overrides the user-level pick. A [self-hosted environment](/docs/en/self-hosted-environments) ID (`ccpool_...`) is honored only from user settings, managed settings, and the `--settings` CLI flag; Claude Code ignores one in a repo's project or local settings with a warning, so a checked-in file can't steer sessions onto a self-hosted environment you didn't choose | `"env_0123abcd"` |
315| `remoteControlAtStartup` | Connect [Remote Control](/docs/en/remote-control) automatically when each interactive session starts, instead of waiting for `/remote-control`. Set to `true` to turn auto-connect on, `false` to turn it off, or leave unset to follow your organization's admin default if one is set, and otherwise Claude Code's current default. Appears in `/config` as **Enable Remote Control for all sessions**. Claude Code ignores a `true` from project or local settings; for the full per-scope behavior, see [Enable Remote Control for all sessions](/docs/en/remote-control#enable-remote-control-for-all-sessions) and the exceptions under [Settings precedence](#settings-precedence) | `false` |318| `remoteControlAtStartup` | Connect [Remote Control](/docs/en/remote-control) automatically when each interactive session starts, instead of waiting for `/remote-control`. Set to `true` to turn auto-connect on, `false` to turn it off, or leave unset to follow your organization's admin default if one is set, and otherwise Claude Code's current default. Appears in `/config` as **Enable Remote Control for all sessions**. Claude Code ignores a `true` from project or local settings; for the full per-scope behavior, see [Enable Remote Control for all sessions](/docs/en/remote-control#enable-remote-control-for-all-sessions) and the [exceptions to managed settings precedence](#exceptions-to-managed-settings-precedence) | `false` |
316| `requiredMaximumVersion` | Managed settings only. Maximum Claude Code version allowed to start. If the running version is newer, Claude Code exits at startup and instructs the user to install an approved version through the organization's approved method; `claude install <version>` may also work. Background auto-updates and `claude update` skip versions above the ceiling, so an in-range installation stays in range. `claude update`, `claude install`, and `claude doctor` keep working above the ceiling so users can recover. Versions that predate this setting ignore it | `"2.1.150"` |319| `requiredMaximumVersion` | Managed settings only. Maximum Claude Code version allowed to start. If the running version is newer, Claude Code exits at startup and instructs the user to install an approved version through the organization's approved method; `claude install <version>` may also work. Background auto-updates and `claude update` skip versions above the ceiling, so an in-range installation stays in range. `claude update`, `claude install`, and `claude doctor` keep working above the ceiling so users can recover. Versions that predate this setting ignore it | `"2.1.150"` |
317| `requiredMinimumVersion` | Managed settings only. Minimum Claude Code version required to start. If the running version is older, Claude Code exits at startup and instructs the user to update through the organization's approved method. `claude update`, `claude install`, and `claude doctor` keep working below the floor so users can recover. Differs from `minimumVersion`, which prevents downgrades but never blocks startup. Versions that predate this setting ignore it | `"2.1.150"` |320| `requiredMinimumVersion` | Managed settings only. Minimum Claude Code version required to start. If the running version is older, Claude Code exits at startup and instructs the user to update through the organization's approved method. `claude update`, `claude install`, and `claude doctor` keep working below the floor so users can recover. Differs from `minimumVersion`, which prevents downgrades but never blocks startup. Versions that predate this setting ignore it | `"2.1.150"` |
318| `respectGitignore` | **Default**: `true`. Control whether the `@` file picker respects `.gitignore` patterns. When `true`, files matching `.gitignore` patterns are excluded from suggestions | `false` |321| `respectGitignore` | **Default**: `true`. Control whether the `@` file picker respects `.gitignore` patterns. When `true`, files matching `.gitignore` patterns are excluded from suggestions | `false` |
331| `statusLine` | Configure a custom status line to display context. The object's optional `padding`, `refreshInterval`, and `hideVimModeIndicator` fields control spacing, periodic re-runs, and whether the built-in vim mode indicator below the prompt is hidden. See [`statusLine` documentation](/docs/en/statusline#manually-configure-a-status-line) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |334| `statusLine` | Configure a custom status line to display context. The object's optional `padding`, `refreshInterval`, and `hideVimModeIndicator` fields control spacing, periodic re-runs, and whether the built-in vim mode indicator below the prompt is hidden. See [`statusLine` documentation](/docs/en/statusline#manually-configure-a-status-line) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |
332| `strictKnownMarketplaces` | (Managed settings only) Allowlist of plugin marketplace sources. Undefined = no restrictions, empty array = lockdown. Enforced on marketplace add and on plugin install, update, refresh, and auto-update, so a marketplace added before the policy was set cannot be used to fetch plugins. See [Managed marketplace restrictions](/docs/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |335| `strictKnownMarketplaces` | (Managed settings only) Allowlist of plugin marketplace sources. Undefined = no restrictions, empty array = lockdown. Enforced on marketplace add and on plugin install, update, refresh, and auto-update, so a marketplace added before the policy was set cannot be used to fetch plugins. See [Managed marketplace restrictions](/docs/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |
333| `strictPluginOnlyCustomization` | (Managed settings only) Block skills, agents, hooks, and MCP servers from user and project sources, so they can only come from plugins or managed settings. `true` locks all four surfaces; an array locks only the named ones. See [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) | `["skills", "hooks"]` |336| `strictPluginOnlyCustomization` | (Managed settings only) Block skills, agents, hooks, and MCP servers from user and project sources, so they can only come from plugins or managed settings. `true` locks all four surfaces; an array locks only the named ones. See [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) | `["skills", "hooks"]` |
337| `subagentStatusLine` | Configure a custom command that rewrites rows in the subagent task display. See [Subagent status lines](/docs/en/statusline#subagent-status-lines) | `{"type": "command", "command": "~/.claude/subagent-statusline.sh"}` |
334| `switchModelsOnFlag` | **Default**: `true`. When a [safety classifier flags a request](/docs/en/model-config#automatic-model-fallback), switch to the fallback model automatically and continue the session. Set to `false` to pause instead and choose between switching and editing the prompt. See [Ask before switching](/docs/en/model-config#ask-before-switching). Appears in `/config` as **Switch models when a message is flagged**. Requires Claude Code v2.1.170 or later | `false` |338| `switchModelsOnFlag` | **Default**: `true`. When a [safety classifier flags a request](/docs/en/model-config#automatic-model-fallback), switch to the fallback model automatically and continue the session. Set to `false` to pause instead and choose between switching and editing the prompt. See [Ask before switching](/docs/en/model-config#ask-before-switching). Appears in `/config` as **Switch models when a message is flagged**. Requires Claude Code v2.1.170 or later | `false` |
335| `syntaxHighlightingDisabled` | Disable syntax highlighting in diffs, code blocks, and file previews | `true` |339| `syntaxHighlightingDisabled` | Disable syntax highlighting in diffs, code blocks, and file previews | `true` |
336| `teammateMode` | **Default**: `in-process`. How [agent team](/docs/en/agent-teams) teammates display: `in-process`, `auto` (split panes when running inside tmux, or inside iTerm2 with `it2` on your `PATH`; in-process otherwise), `tmux` (split panes using tmux or iTerm2, detected from your terminal), or `iterm2` (iTerm2 native split panes via the `it2` CLI, added in v2.1.186). The default changed from `auto` in v2.1.179. `--teammate-mode` overrides this for one session. See [choose a display mode](/docs/en/agent-teams#choose-a-display-mode) | `"auto"` |340| `teammateMode` | **Default**: `in-process`. How [agent team](/docs/en/agent-teams) teammates display: `in-process`, `auto` (split panes when running inside tmux, or inside iTerm2 with `it2` on your `PATH`; in-process otherwise), `tmux` (split panes using tmux or iTerm2, detected from your terminal), or `iterm2` (iTerm2 native split panes via the `it2` CLI, added in v2.1.186). The default changed from `auto` in v2.1.179. `--teammate-mode` overrides this for one session. See [choose a display mode](/docs/en/agent-teams#choose-a-display-mode) | `"auto"` |
426| `credentials.files[].decode` | Format-aware [masking of encoded credentials](/docs/en/sandboxing#mask-credential-files) when `mode` is `mask`. The only value is `jwt`: Claude Code finds JWT candidates in the file with a built-in pattern, or with `extract` when set, verifies each candidate is a JWT, and replaces it with a structurally valid fake token, so code inside the sandbox that decodes the token keeps working. When no candidate verifies, `onExtractNoMatch` governs the outcome. Same macOS scoping as `extract`; accepted but ignored when `mode` is `deny`. Requires Claude Code v2.1.224 or later. | `"jwt"` |430| `credentials.files[].decode` | Format-aware [masking of encoded credentials](/docs/en/sandboxing#mask-credential-files) when `mode` is `mask`. The only value is `jwt`: Claude Code finds JWT candidates in the file with a built-in pattern, or with `extract` when set, verifies each candidate is a JWT, and replaces it with a structurally valid fake token, so code inside the sandbox that decodes the token keeps working. When no candidate verifies, `onExtractNoMatch` governs the outcome. Same macOS scoping as `extract`; accepted but ignored when `mode` is `deny`. Requires Claude Code v2.1.224 or later. | `"jwt"` |
427| `credentials.files[].maskClaims` | Top-level payload claims to mask inside each verified JWT instead of replacing the whole token. Requires `decode` and at least one non-empty claim name. Each named claim present with a string value gets its own sentinel and Claude Code rebuilds the token around the modified payload, so the other claims stay readable inside the sandbox. When no named claim matches in any verified token, `onExtractNoMatch` governs the outcome. Requires Claude Code v2.1.224 or later. | `["api_key"]` |431| `credentials.files[].maskClaims` | Top-level payload claims to mask inside each verified JWT instead of replacing the whole token. Requires `decode` and at least one non-empty claim name. Each named claim present with a string value gets its own sentinel and Claude Code rebuilds the token around the modified payload, so the other claims stay readable inside the sandbox. When no named claim matches in any verified token, `onExtractNoMatch` governs the outcome. Requires Claude Code v2.1.224 or later. | `["api_key"]` |
428| `credentials.files[].maskDuplicates` | Also replace verbatim copies of each masked credential value, an `extract` capture or a `decode`-verified token, found outside the matched spans. Matches raw substrings, so reserve it for long, high-entropy secrets. Only meaningful when `mode` is `mask` and `extract` or `decode` is set. Default: false. Requires Claude Code v2.1.221 or later. | `true` |432| `credentials.files[].maskDuplicates` | Also replace verbatim copies of each masked credential value, an `extract` capture or a `decode`-verified token, found outside the matched spans. Matches raw substrings, so reserve it for long, high-entropy secrets. Only meaningful when `mode` is `mask` and `extract` or `decode` is set. Default: false. Requires Claude Code v2.1.221 or later. | `true` |
429| `credentials.files[].injectHosts` | Hosts where the sandbox proxy substitutes the real value of a file `mask` entry. Behaves the same as `credentials.envVars[].injectHosts`: each host must be covered by `network.allowedDomains`, and when unset the proxy substitutes the value on requests to every host in `network.allowedDomains`. Accepted but ignored when `mode` is `deny`. Requires Claude Code v2.1.221 or later. | `["api.github.com"]` |433| `credentials.files[].injectHosts` | Hosts where the sandbox proxy substitutes the real value of a file `mask` entry. Behaves the same as `credentials.envVars[].injectHosts`. When unset, the proxy substitutes the value on requests to every host in `network.allowedDomains`. Accepted but ignored when `mode` is `deny`. Requires Claude Code v2.1.221 or later. | `["api.github.com"]` |
430| `credentials.envVars` | Environment variables to [protect from sandboxed commands](/docs/en/sandboxing#protect-credentials). Each entry has a `name` and a `mode`; the name must start with a letter or underscore and contain only letters, digits, and underscores. `deny` removes the variable from the environment of sandboxed commands. Requires Claude Code v2.1.187 or later. `mask` replaces the variable with a per-session sentinel value inside the sandbox while the sandbox proxy substitutes the real value on outbound requests to that entry's `injectHosts`; it requires `network.tlsTerminate` and Claude Code v2.1.199 or later. `mask` entries are only honored from user, managed, or CLI `--settings` settings, not from `.claude/settings.json` or `.claude/settings.local.json`. Arrays are merged across all settings scopes, and `deny` takes precedence when the same variable appears with both modes. | `[{ "name": "GITHUB_TOKEN", "mode": "deny" }]` |434| `credentials.envVars` | Environment variables to [protect from sandboxed commands](/docs/en/sandboxing#protect-credentials). Each entry has a `name` and a `mode`; the name must start with a letter or underscore and contain only letters, digits, and underscores. `deny` removes the variable from the environment of sandboxed commands. Requires Claude Code v2.1.187 or later. `mask` replaces the variable with a per-session sentinel value inside the sandbox while the sandbox proxy substitutes the real value on outbound requests to that entry's `injectHosts`; it requires `network.tlsTerminate` and Claude Code v2.1.199 or later. `mask` entries are only honored from user, managed, or CLI `--settings` settings, not from `.claude/settings.json` or `.claude/settings.local.json`. Arrays are merged across all settings scopes, and `deny` takes precedence when the same variable appears with both modes. | `[{ "name": "GITHUB_TOKEN", "mode": "deny" }]` |
431| `credentials.envVars[].extract` | Regular expression for [structured masking](/docs/en/sandboxing#mask-environment-variables) when `mode` is `mask`. Claude Code applies it across the variable's value and replaces only the text captured by group 1 of each match with a sentinel, so the rest of the value stays parseable, such as the password inside a `DATABASE_URL` connection string. Must contain at least one capturing group. Without `extract` or `decode`, Claude Code replaces the entire value with one sentinel. Can't be combined with `decode`. Accepted but ignored when `mode` is `deny`. Requires Claude Code v2.1.224 or later. | `"://[^:]+:([^@]+)@"` |435| `credentials.envVars[].extract` | Regular expression for [structured masking](/docs/en/sandboxing#mask-environment-variables) when `mode` is `mask`. Claude Code applies it across the variable's value and replaces only the text captured by group 1 of each match with a sentinel, so the rest of the value stays parseable, such as the password inside a `DATABASE_URL` connection string. Must contain at least one capturing group. Without `extract` or `decode`, Claude Code replaces the entire value with one sentinel. Can't be combined with `decode`. Accepted but ignored when `mode` is `deny`. Requires Claude Code v2.1.224 or later. | `"://[^:]+:([^@]+)@"` |
432| `credentials.envVars[].onExtractNoMatch` | What happens when `extract` matches nothing in the value: `warn`, the default, warns and passes the variable through unmasked; `deny` unsets the variable inside the sandbox; `error` stops sandbox setup until you fix the configuration. Only meaningful when `mode` is `mask` and `extract` is set. On an entry with `decode`, only `warn` is accepted, because a value that fails JWT verification always passes through unmasked with a warning. Requires Claude Code v2.1.224 or later. | `"deny"` |436| `credentials.envVars[].onExtractNoMatch` | What happens when `extract` matches nothing in the value: `warn`, the default, warns and passes the variable through unmasked; `deny` unsets the variable inside the sandbox; `error` stops sandbox setup until you fix the configuration. Only meaningful when `mode` is `mask` and `extract` is set. On an entry with `decode`, only `warn` is accepted, because a value that fails JWT verification always passes through unmasked with a warning. Requires Claude Code v2.1.224 or later. | `"deny"` |
433| `credentials.envVars[].decode` | Format-aware [masking of encoded credentials](/docs/en/sandboxing#mask-environment-variables) when `mode` is `mask`. The only value is `jwt`: Claude Code verifies the variable's whole value is a JWT and replaces it with a structurally valid fake token, so code inside the sandbox that decodes the token keeps working, and the proxy substitutes the whole real token on egress. A value that doesn't verify passes through unmasked with a warning. Can't be combined with `extract`. Accepted but ignored when `mode` is `deny`. Requires Claude Code v2.1.224 or later. | `"jwt"` |437| `credentials.envVars[].decode` | Format-aware [masking of encoded credentials](/docs/en/sandboxing#mask-environment-variables) when `mode` is `mask`. The only value is `jwt`: Claude Code verifies the variable's whole value is a JWT and replaces it with a structurally valid fake token, so code inside the sandbox that decodes the token keeps working, and the proxy substitutes the whole real token on egress. A value that doesn't verify passes through unmasked with a warning. Can't be combined with `extract`. Accepted but ignored when `mode` is `deny`. Requires Claude Code v2.1.224 or later. | `"jwt"` |
434| `credentials.envVars[].maskClaims` | Top-level payload claims to mask inside the decoded JWT instead of replacing the whole token. Requires `decode` and at least one non-empty claim name. Behaves like `credentials.files[].maskClaims`, except that when no named claim matches, the variable passes through unmasked with a warning. Requires Claude Code v2.1.224 or later. | `["api_key"]` |438| `credentials.envVars[].maskClaims` | Top-level payload claims to mask inside the decoded JWT instead of replacing the whole token. Requires `decode` and at least one non-empty claim name. Behaves like `credentials.files[].maskClaims`, except that when no named claim matches, the variable passes through unmasked with a warning. Requires Claude Code v2.1.224 or later. | `["api_key"]` |
435| `credentials.envVars[].injectHosts` | Hosts where the sandbox proxy substitutes the real value of a `mask` entry. Each host must also be covered by `network.allowedDomains`, either exactly or by a wildcard. When unset, the proxy substitutes the value on requests to every host in `network.allowedDomains`. Accepted but ignored when `mode` is `deny`. Requires Claude Code v2.1.199 or later. | `["api.github.com"]` |439| `credentials.envVars[].injectHosts` | Hosts where the sandbox proxy substitutes the real value of a `mask` entry. The proxy injects only on connections `network.allowedDomains` admits, so each destination must also pass that list. When unset, the proxy substitutes the value on requests to every host in `network.allowedDomains`. Write an IPv6 destination as the bare canonical compressed address, such as `"::1"`, not the bracketed form. See [IPv6 destinations in `injectHosts`](/docs/en/sandboxing#ipv6-destinations-in-injecthosts) for what each list matches. Accepted but ignored when `mode` is `deny`. Requires Claude Code v2.1.199 or later. | `["api.github.com"]` |
436| `credentials.allowPlaintextInject` | Allow `mask` substitution on plain HTTP requests as well as TLS-terminated HTTPS. On plain HTTP the upstream identity is unverified and the credential travels in cleartext, so leave this off outside trusted test networks. Only honored from user, managed, or CLI `--settings` settings, not from `.claude/settings.json` or `.claude/settings.local.json`. Default: false. Requires Claude Code v2.1.199 or later. | `true` |440| `credentials.allowPlaintextInject` | Allow `mask` substitution on plain HTTP requests as well as TLS-terminated HTTPS. On plain HTTP the upstream identity is unverified and the credential travels in cleartext, so leave this off outside trusted test networks. Only honored from user, managed, or CLI `--settings` settings, not from `.claude/settings.json` or `.claude/settings.local.json`. Default: false. Requires Claude Code v2.1.199 or later. | `true` |
437| `credentials.awsPairs` | Groups of masked environment variables that form one AWS credential for [SigV4 re-signing](/docs/en/sandboxing#re-sign-aws-requests), for non-standard variable names; Claude Code links the conventional `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` trio automatically when those variables are masked whole-value. Each entry names the `credentials.envVars` entry holding each part in `accessKeyIdVar`, `secretAccessKeyVar`, and optionally `sessionTokenVar`. Each named variable must be a whole-value `mask` entry, without `extract` or `decode`, and can fill only one slot across all pairs. Only honored from user, managed, or CLI `--settings` settings. Requires Claude Code v2.1.224 or later. | `[{ "accessKeyIdVar": "MY_KEY_ID", "secretAccessKeyVar": "MY_SECRET_KEY" }]` |441| `credentials.awsPairs` | Groups of masked environment variables that form one AWS credential for [SigV4 re-signing](/docs/en/sandboxing#re-sign-aws-requests), for non-standard variable names; Claude Code links the conventional `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` trio automatically when those variables are masked whole-value. Each entry names the `credentials.envVars` entry holding each part in `accessKeyIdVar`, `secretAccessKeyVar`, and optionally `sessionTokenVar`. Each named variable must be a whole-value `mask` entry, without `extract` or `decode`, and can fill only one slot across all pairs. Only honored from user, managed, or CLI `--settings` settings. Requires Claude Code v2.1.224 or later. | `[{ "accessKeyIdVar": "MY_KEY_ID", "secretAccessKeyVar": "MY_SECRET_KEY" }]` |
438| `credentials.sigv4` | Policies for AWS request forms the sandbox proxy [can't re-sign](/docs/en/sandboxing#re-sign-aws-requests): `streaming` for aws-chunked streaming uploads, `presigned` for presigned URLs, and `sigv4a` for SigV4A asymmetric signatures. Each accepts `deny`, the default, which fails the request at the proxy, or `passthrough`, which forwards the request with its signature computed from the masked placeholder, so AWS rejects it. Applies only to requests signed with a masked pair's placeholder access key ID. Only honored from user, managed, or CLI `--settings` settings. Requires Claude Code v2.1.224 or later. | `{ "streaming": "passthrough" }` |442| `credentials.sigv4` | Policies for AWS request forms the sandbox proxy [can't re-sign](/docs/en/sandboxing#re-sign-aws-requests): `streaming` for aws-chunked streaming uploads, `presigned` for presigned URLs, and `sigv4a` for SigV4A asymmetric signatures. Each accepts `deny`, the default, which fails the request at the proxy, or `passthrough`, which forwards the request with its signature computed from the masked placeholder, so AWS rejects it. Applies only to requests signed with a masked pair's placeholder access key ID. Only honored from user, managed, or CLI `--settings` settings. Requires Claude Code v2.1.224 or later. | `{ "streaming": "passthrough" }` |
440| `network.allowAllUnixSockets` | Allow all Unix socket connections in sandbox. On Linux and WSL2, when the optional [seccomp filter](/docs/en/sandboxing#set-up-linux-and-wsl2) is installed, this is the only way to permit Unix sockets, since it skips the filter that otherwise blocks `socket(AF_UNIX, ...)` calls; without the filter, the sandbox doesn't block Unix-socket calls. On WSL2, `true` also reopens the interop socket that launches Windows binaries. Default: false | `true` |444| `network.allowAllUnixSockets` | Allow all Unix socket connections in sandbox. On Linux and WSL2, when the optional [seccomp filter](/docs/en/sandboxing#set-up-linux-and-wsl2) is installed, this is the only way to permit Unix sockets, since it skips the filter that otherwise blocks `socket(AF_UNIX, ...)` calls; without the filter, the sandbox doesn't block Unix-socket calls. On WSL2, `true` also reopens the interop socket that launches Windows binaries. Default: false | `true` |
441| `network.allowLocalBinding` | Allow binding to localhost ports (macOS only). Default: false | `true` |445| `network.allowLocalBinding` | Allow binding to localhost ports (macOS only). Default: false | `true` |
442| `network.allowMachLookup` | Additional XPC/Mach service names the sandbox may look up (macOS only). Supports a single trailing `*` for prefix matching. Needed for tools that communicate via XPC such as the iOS Simulator or Playwright. | `["com.apple.coresimulator.*"]` |446| `network.allowMachLookup` | Additional XPC/Mach service names the sandbox may look up (macOS only). Supports a single trailing `*` for prefix matching. Needed for tools that communicate via XPC such as the iOS Simulator or Playwright. | `["com.apple.coresimulator.*"]` |
443| `network.allowedDomains` | Array of domains to allow for outbound network traffic. Supports wildcards (e.g., `*.example.com`). | `["github.com", "*.npmjs.org"]` |447| `network.allowedDomains` | Array of domains to allow for outbound network traffic. Supports wildcards, such as `*.example.com`. Write IPv6 literals bracketed, with an optional port: `"[::1]"` allows every port and `"[::1]:443"` one port. The bracketed form requires Claude Code v2.1.229 or later. See [IPv6 addresses in domain lists](/docs/en/sandboxing#ipv6-addresses-in-domain-lists). | `["github.com", "*.npmjs.org"]` |
444| `network.deniedDomains` | Array of domains to block for outbound network traffic. Supports the same wildcard syntax as `allowedDomains`. Takes precedence over `allowedDomains` when both match. Merged from all settings sources regardless of `allowManagedDomainsOnly`. | `["sensitive.cloud.example.com"]` |448| `network.deniedDomains` | Array of domains to block for outbound network traffic. Supports the same wildcard syntax as `allowedDomains`. For IPv6 literals, see [IPv6 addresses in domain lists](/docs/en/sandboxing#ipv6-addresses-in-domain-lists). Takes precedence over `allowedDomains` when both match. Merged from all settings sources regardless of `allowManagedDomainsOnly`. | `["sensitive.cloud.example.com"]` |
445| `network.strictAllowlist` | Deny sandboxed commands access to hosts outside the allowlist instead of prompting for approval. The allowlist is `allowedDomains` plus domains from `WebFetch(domain:...)` allow rules, or only the managed settings entries when `allowManagedDomainsOnly` is set. Enforced for sandboxed commands only; in-process tools such as `WebFetch` aren't gated by this setting. Only honored from user, managed, or CLI `--settings` settings, not from `.claude/settings.json` or `.claude/settings.local.json`. Default: false. Requires Claude Code v2.1.219 or later. See [Network isolation](/docs/en/sandboxing#network-isolation) | `true` |449| `network.strictAllowlist` | Deny sandboxed commands access to hosts outside the allowlist instead of prompting for approval. The allowlist is `allowedDomains` plus domains from `WebFetch(domain:...)` allow rules, or only the managed settings entries when `allowManagedDomainsOnly` is set. Enforced for sandboxed commands only; in-process tools such as `WebFetch` aren't gated by this setting. Only honored from user, managed, or CLI `--settings` settings, not from `.claude/settings.json` or `.claude/settings.local.json`. Default: false. Requires Claude Code v2.1.219 or later. See [Network isolation](/docs/en/sandboxing#network-isolation) | `true` |
446| `network.allowManagedDomainsOnly` | (Managed settings only) Only `allowedDomains` and `WebFetch(domain:...)` allow rules from managed settings are respected. Domains from user, project, and local settings are ignored. Non-allowed domains are blocked automatically without prompting the user. Denied domains are still respected from all sources. Default: false | `true` |450| `network.allowManagedDomainsOnly` | (Managed settings only) Only `allowedDomains` and `WebFetch(domain:...)` allow rules from managed settings are respected. Domains from user, project, and local settings are ignored. Non-allowed domains are blocked automatically without prompting the user. Denied domains are still respected from all sources. Default: false | `true` |
447| `network.httpProxyPort` | HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8080` |451| `network.httpProxyPort` | HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8080` |
549 553
550Configure a custom command for `@` file path autocomplete. The built-in file suggestion uses fast filesystem traversal, but large monorepos may benefit from project-specific indexing such as a pre-built file index or custom tooling.554Configure a custom command for `@` file path autocomplete. The built-in file suggestion uses fast filesystem traversal, but large monorepos may benefit from project-specific indexing such as a pre-built file index or custom tooling.
551 555
556Claude Code can skip your custom command without warning and serve `@` autocomplete from the built-in file suggestion instead. The [Hook configuration](#hook-configuration) section describes the gates.
557
552```json theme={null}558```json theme={null}
553{559{
554 "fileSuggestion": {560 "fileSuggestion": {
627 633
628* Managed hooks and SDK hooks are loaded634* Managed hooks and SDK hooks are loaded
629* Hooks from plugins force-enabled in managed settings `enabledPlugins` are loaded. This lets administrators distribute vetted hooks through an organization marketplace while blocking everything else. Trust is granted by full `plugin@marketplace` ID, so a plugin with the same name from a different marketplace stays blocked635* Hooks from plugins force-enabled in managed settings `enabledPlugins` are loaded. This lets administrators distribute vetted hooks through an organization marketplace while blocking everything else. Trust is granted by full `plugin@marketplace` ID, so a plugin with the same name from a different marketplace stays blocked
630* User hooks, project hooks, and all other plugin hooks are blocked636* User hooks, project hooks, local hooks, and all other plugin hooks are blocked
637* Claude Code also disables plugins with a [`command` source](/docs/en/plugin-marketplaces#command-sources), including plugins force-enabled in managed settings `enabledPlugins`, unless [`disableCommandPluginSources`](#available-settings) is explicitly set to `false`
638* Claude Code also narrows [`statusLine`](/docs/en/statusline), [`fileSuggestion`](#file-suggestion-settings), and [`subagentStatusLine`](/docs/en/statusline#subagent-status-lines) to managed settings, following the two decisions below
639
640**Status line and file suggestion gates:** Claude Code makes two decisions for `statusLine`, `fileSuggestion`, and `subagentStatusLine`. It turns the feature off entirely when managed settings set `disableAllHooks`, or when the folder isn't trusted under the same [workspace trust rule as hooks in settings files](/docs/en/permissions#what-runs-before-you-trust-a-folder). It narrows the source to managed settings when `allowManagedHooksOnly` is set or when `disableAllHooks` is `true` outside managed settings after [settings precedence](/docs/en/hooks#disable-or-remove-hooks) applies. Under narrowing, Claude Code runs a managed value if one is deployed; otherwise it skips your value without warning, the status line is disabled, and `@` autocomplete falls back to the built-in file suggestion.
631 641
632**Restrict HTTP hook URLs:**642**Restrict HTTP hook URLs:**
633 643
673}683}
674```684```
675 685
676When the helper emits `managedSettings`, that object becomes the only managed settings source for the run, taking precedence over remote, MDM, and file-based sources. When the helper exits non-zero at startup, Claude Code prints the error and refuses to start, so a helper that needs outage resilience should serve from its own cache and exit `0`.686When the helper emits `managedSettings`, that object becomes the only managed settings source for the run: Claude Code ignores remote, MDM, and file-based sources, reads the [cross-source keys](#precedence-within-the-managed-tier) from the helper's output alone, and never merges [parent settings](#parent-settings-from-embedding-hosts). A helper that exits 0 without emitting `managedSettings` contributes no managed settings, and the other sources apply as usual. When the helper exits non-zero at startup, Claude Code prints the error and refuses to start, so a helper that needs outage resilience should serve from its own cache and exit `0`.
677 687
678### Settings precedence688### Settings precedence
679 689
680Settings apply in order of precedence. From highest to lowest:690Claude Code reads settings from these levels, highest precedence first. A few security-sensitive keys and one host-integration case don't follow this order, in either direction; [Exceptions to managed settings precedence](#exceptions-to-managed-settings-precedence) lists them.
681 691
6821. **Managed settings** ([server-managed](/docs/en/server-managed-settings), [MDM/OS-level policies](#configuration-scopes), or [managed settings](/docs/en/settings#settings-files))6921. **Managed settings** ([server-managed](/docs/en/server-managed-settings), [MDM/OS-level policies](#configuration-scopes), or [managed settings files](/docs/en/settings#settings-files))
683 * Policies deployed by IT through server delivery, MDM configuration profiles, registry policies, or managed settings files693 * Your organization deploys these through server delivery, MDM configuration profiles, registry policies, or managed settings files
684 * Cannot be overridden by any other level, including command line arguments, apart from the exceptions in the bullets below694 * No other level overrides them, including command line arguments, apart from the [exceptions to managed settings precedence](#exceptions-to-managed-settings-precedence)
685 * A few security-sensitive settings honor a restrictive value from scopes that otherwise couldn't override them:695 * When your organization delivers more than one managed source, [precedence within the managed tier](#precedence-within-the-managed-tier) determines what Claude Code reads from each
686 * A `true` for [`disableClaudeAiConnectors`](#available-settings) applies from any scope, even when a managed source sets `false`
687 * A `false` for [`remoteControlAtStartup`](#available-settings) in project or local settings (`.claude/settings.json`, `.claude/settings.local.json`) applies even when a managed source sets `true`. Claude Code ignores a `true` there; only user settings, the `--settings` flag, and managed sources can turn auto-connect on, and a user `false` doesn't override a managed `true`
688 * A `true` for [`isolatePeerMachines`](#available-settings) applies from any scope, even when a managed source sets `false`
689 * A stricter [`crossSessionInbound`](#available-settings) value in project or local settings (`.claude/settings.json`, `.claude/settings.local.json`), on the `accept` \< `hold` \< `refuse` ladder, applies over the value managed settings, the `--settings` flag, or user settings give. Claude Code ignores a project or local value that isn't stricter, so for this key a checked-in `accept` never overrides your user `hold` or `refuse`
690 * Host platforms that embed Claude Code and set [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/en/env-vars) are also an exception. The host's model configuration takes precedence over the `model`, `fallbackModel`, and `modelOverrides` keys from every managed source, and over the model-selection environment variables in a managed `env` block, such as `ANTHROPIC_MODEL` and the `ANTHROPIC_DEFAULT_*_MODEL` family. A managed [`availableModels`](#available-settings) allowlist stays in force unless the host supplies its own
691 * Within the managed tier, apart from the exception keys listed after the ranking, only one source is used and the others are ignored rather than merged. Precedence, highest first:
692 * [`policyHelper`](#compute-managed-settings-with-a-policy-helper) output: when configured, this is the only managed source used
693 * Remote (claude.ai [server-managed](/docs/en/server-managed-settings) or [Claude apps gateway](/docs/en/claude-apps-gateway)-delivered)
694 * MDM/OS-level policies
695 * File-based (`managed-settings.d/*.json` and `managed-settings.json`, merged together)
696 * HKCU registry (Windows only)
697 * A few keys are honored when any admin-controlled managed source sets them, rather than only the winning source. The user-writable HKCU registry source is excluded, and when a [`policyHelper`](#compute-managed-settings-with-a-policy-helper) is configured, its output is the only source these checks read. The exception keys are:
698 * the sandbox lock keys `sandbox.network.allowManagedDomainsOnly` and `sandbox.filesystem.allowManagedReadPathsOnly`, with their associated allowlists
699 * `allowAllClaudeAiMcps`
700 * the sandbox binary paths `sandbox.bwrapPath` and `sandbox.socatPath`
701 * [`forceRemoteSettingsRefresh`](/docs/en/server-managed-settings)
702 * `env`, which merges per key across the admin-controlled sources: for each environment variable, the highest-priority source defining it wins, and lower admin sources fill in variables the higher sources leave unset, or for which a cached server value is [withheld pending server confirmation](/docs/en/server-managed-settings#fetch-and-caching-behavior). The telemetry unit and credential-paired routing variables follow their own rules; see [Per-key exceptions across managed sources](/docs/en/server-managed-settings#per-key-exceptions-across-managed-sources). Requires Claude Code v2.1.223 or later. Before v2.1.223, Claude Code applies the winning source's whole `env` block only.
703 * Embedding hosts such as Claude Desktop can supply policy via the SDK `managedSettings` option. By default this is ignored when an admin-deployed managed source is present: server-managed settings, an MDM or OS-level policy, or a managed settings file. The user-writable HKCU registry fallback does not count as an admin-deployed source. Administrators can opt in by setting [`parentSettingsBehavior`](#available-settings) to `"merge"` in the highest-priority managed source; only that source's value is read. The embedder's values pass through a restrictive-only filter, but the filter isn't strictly tighten-only: unless the `allowManaged*Only` locks are set, allow-direction settings such as permission allow rules and sandbox allowlists still apply. See [Restrict parent settings](/docs/en/claude-apps-gateway#restrict-parent-settings) for the locks. While a [`policyHelper`](#compute-managed-settings-with-a-policy-helper) is configured, parent settings are never merged, regardless of this key.
704 * When any admin-controlled managed source sets `allowManagedPermissionRulesOnly`, Claude Code drops [parent-supplied](/docs/en/claude-apps-gateway#restrict-parent-settings) permission allow rules and `additionalDirectories` as it reads them, even when a higher-priority source leaves the key unset; the key's effect on the developer's own permission rules comes from the highest-priority source only
705 * A `forceLoginOrgUUID` or `allowedMcpServers` value in the highest-priority admin source blocks a parent-supplied one and is the value Claude Code enforces. A value in a non-winning admin source neither applies nor blocks the parent's. Before v2.1.223, a value in any admin source blocked the parent's
706 696
7072. **Command line arguments**6972. **Command line arguments**
708 * Temporary overrides for a specific session. JSON passed via `--settings <file-or-json>` merges with file-based settings using the same rules as the other layers: a key set here overrides the same key in local, project, or user settings, and omitting a key leaves the lower-layer value in place698 * Values you pass for one session. JSON you pass with `--settings <file-or-json>` merges with your settings files by the same rules as the other levels: a key you set here overrides the same key in local, project, or user settings, and a key you omit keeps its lower-level value
709 699
7103. **Local project settings** (`.claude/settings.local.json`)7003. **Local project settings** (`.claude/settings.local.json`)
711 * Personal project-specific settings701 * Your personal settings for this project
712 702
7134. **Shared project settings** (`.claude/settings.json`)7034. **Shared project settings** (`.claude/settings.json`)
714 * Team-shared project settings in source control704 * Settings your team checks into source control
715 705
7165. **User settings** (`~/.claude/settings.json`)7065. **User settings** (`~/.claude/settings.json`)
717 * Personal global settings707 * Your personal settings for every project
718 708
719This hierarchy applies organizational policies first, apart from the exceptions under [Settings precedence](#settings-precedence), 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](/docs/en/vs-code), or a [JetBrains IDE](/docs/en/jetbrains).709The same order applies whether you run Claude Code from the CLI, the [VS Code extension](/docs/en/vs-code), or a [JetBrains IDE](/docs/en/jetbrains). For example, if you set `spinnerTipsEnabled` to `true` in your user settings and your team sets it to `false` in the project's shared settings, the project value applies.
720
721For example, if your user settings set `permissions.defaultMode` to `acceptEdits` and a project's shared settings set it to `default`, the project value applies. The example below covers how array-valued settings such as permission rules combine instead.
722 710
723<Note>711<Note>
724 **Array settings merge across scopes.** When the same array-valued setting (such as `sandbox.filesystem.allowWrite` or `permissions.allow`) appears in multiple scopes, the arrays are **concatenated and deduplicated**, not replaced. This means lower-priority scopes can add entries without overriding those set by higher-priority scopes, and vice versa. For example, if managed settings set `allowWrite` to `["/opt/company-tools"]` and a user adds `["~/.kube"]`, both paths are included in the final configuration.712 **Array settings merge across scopes.** When you set the same array-valued key, such as `sandbox.filesystem.allowWrite` or `permissions.allow`, in more than one scope, Claude Code concatenates and deduplicates the arrays instead of replacing one with another, so each scope can add entries without removing another scope's. For example, if managed settings set `allowWrite` to `["/opt/company-tools"]` and you add `["~/.kube"]` in your user settings, Claude Code allows writes to both paths.
725 713
726 Two array settings do not merge this way:714 Two array keys don't merge this way:
727 715
728 * [`fallbackModel`](#available-settings) is an ordered chain where position carries meaning: the highest-precedence file that defines it supplies the entire value.716 * [`fallbackModel`](#available-settings) is an ordered chain where position carries meaning, so Claude Code takes the whole value from the highest-precedence file that defines it.
729 * [`availableModels`](#available-settings): when the [highest-precedence managed source](/docs/en/server-managed-settings#settings-precedence) defines it, that list applies as-is, apart from a [host platform that supplies its own](#settings-precedence), and user, project, and local entries cannot extend it. Across non-managed scopes the arrays merge as usual. See [Merge behavior](/docs/en/model-config#merge-behavior).717 * [`availableModels`](#available-settings): when the [highest-precedence managed source](#precedence-within-the-managed-tier) defines it, Claude Code applies that list as-is, apart from a [host platform that supplies its own](#exceptions-to-managed-settings-precedence), and ignores entries you add in user, project, or local settings. Across non-managed scopes the arrays merge as usual. See [Merge behavior](/docs/en/model-config#merge-behavior).
730</Note>718</Note>
731 719
720#### Exceptions to managed settings precedence
721
722For a few security-sensitive keys, Claude Code honors a restrictive value from a scope that otherwise couldn't override managed settings. Find the key in this table to see which value it honors and from where.
723
724| Key | Value Claude Code honors | Notes |
725| :------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
726| [`disableClaudeAiConnectors`](#available-settings) | `true` from any scope | Honored even when a managed source sets `false` |
727| [`isolatePeerMachines`](#available-settings) | `true` from any scope | Honored even when a managed source sets `false` |
728| [`remoteControlAtStartup`](#available-settings) | `false` from `.claude/settings.json` or `.claude/settings.local.json` | Honored even when a managed source sets `true`. Claude Code ignores a `true` in those two files: you can turn auto-connect on only from user settings, the `--settings` flag, or managed settings, and a `false` in your user settings doesn't override a managed `true` |
729| [`crossSessionInbound`](#available-settings) | A stricter value from `.claude/settings.json` or `.claude/settings.local.json`, on the `accept` \< `hold` \< `refuse` ladder | Honored over the value from managed settings, the `--settings` flag, or user settings. Claude Code ignores a project or local value that isn't stricter, so a checked-in `accept` never overrides the `hold` or `refuse` in your user settings |
730
731A host platform that embeds Claude Code and sets [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/en/env-vars) is also an exception. Claude Code takes the host's model configuration over the `model`, `fallbackModel`, and `modelOverrides` keys from every managed source, and over the model-selection variables in a managed `env` block, such as `ANTHROPIC_MODEL` and the `ANTHROPIC_DEFAULT_*_MODEL` family. A managed [`availableModels`](#available-settings) allowlist stays in force unless the host supplies its own.
732
733#### Precedence within the managed tier
734
735A [`policyHelper`](#compute-managed-settings-with-a-policy-helper) can replace every source in this list; that section says when. Otherwise, apart from the cross-source keys listed after the ranking, Claude Code uses the first of these sources that delivers a non-empty configuration and ignores the rest rather than merging them:
736
7371. Remote settings, delivered from claude.ai as [server-managed settings](/docs/en/server-managed-settings) or by a [Claude apps gateway](/docs/en/claude-apps-gateway)
7382. MDM or OS-level policies
7393. Managed settings files, `managed-settings.d/*.json` and `managed-settings.json` merged together
7404. The HKCU registry, on Windows only
741
742Claude Code honors a few keys from any admin-controlled managed source, not only the one it selected above. The user-writable HKCU registry source is excluded from these checks. These cross-source keys are:
743
744* The sandbox lock keys `sandbox.network.allowManagedDomainsOnly` and `sandbox.filesystem.allowManagedReadPathsOnly`, with their associated allowlists
745* `allowAllClaudeAiMcps`
746* The sandbox binary paths `sandbox.bwrapPath` and `sandbox.socatPath`
747* [`forceRemoteSettingsRefresh`](/docs/en/server-managed-settings)
748* `env`, which Claude Code merges per variable across the admin-controlled sources: each variable comes from the highest-priority source that defines it, so lower sources fill in variables the higher ones leave unset, or whose cached server value Claude Code is [withholding pending server confirmation](/docs/en/server-managed-settings#fetch-and-caching-behavior). The telemetry unit and credential-paired routing variables follow their own rules; see [Per-key exceptions across managed sources](/docs/en/server-managed-settings#per-key-exceptions-across-managed-sources). Requires Claude Code v2.1.223 or later. Before v2.1.223, Claude Code applied the selected source's whole `env` block only
749
750#### Parent settings from embedding hosts
751
752An embedding host such as Claude Desktop can supply policy through the SDK `managedSettings` option. By default, Claude Code ignores those parent settings whenever an admin-deployed managed source is present: server-managed settings, an MDM or OS-level policy, or a managed settings file. The user-writable HKCU registry source doesn't count as admin-deployed.
753
754To have Claude Code merge parent settings alongside an admin-deployed source, set [`parentSettingsBehavior`](#available-settings) to `"merge"` in the highest-priority managed source; Claude Code reads the key from that source only. It then passes the host's values through a restrictive-only filter, with one gap to know about: unless you also set the `allowManaged*Only` locks, allow-direction settings from the host, such as permission allow rules and sandbox allowlists, still apply. See [Restrict parent settings](/docs/en/claude-apps-gateway#restrict-parent-settings) for the locks. A [`policyHelper`](#compute-managed-settings-with-a-policy-helper) can turn parent merging off regardless of this key; that section says when.
755
756Claude Code also applies these checks to specific parent-supplied values:
757
758* When any admin-controlled managed source sets `allowManagedPermissionRulesOnly`, Claude Code drops [parent-supplied](/docs/en/claude-apps-gateway#restrict-parent-settings) permission allow rules and `additionalDirectories` as it reads them, even when a higher-priority source leaves the key unset. The key's effect on your own permission rules still comes from the highest-priority source only
759* A `forceLoginOrgUUID` or `allowedMcpServers` value in the highest-priority admin source blocks a parent-supplied one, and Claude Code enforces the admin value. A value in a non-selected admin source neither applies nor blocks the parent's. Before v2.1.223, a value in any admin source blocked the parent's
760
732### Verify active settings761### Verify active settings
733 762
734Run `/status` inside Claude Code to see which settings sources are active. Inside the menu, the **Status** tab includes a `Setting sources` line that lists each layer Claude Code loaded for the current session, such as `User settings` or `Project local settings`. When [managed settings](/docs/en/admin-setup#decide-how-settings-reach-devices) are in effect, the entry shows the delivery channel in parentheses, for example `Enterprise managed settings (remote)`, `(plist)`, `(HKLM)`, `(HKCU)`, or `(file)`. The `remote` channel covers both claude.ai server-managed settings and [Claude apps gateway](/docs/en/claude-apps-gateway)-delivered policies. A layer appears in the list only when that source is loaded with at least one key, so an empty list means no settings sources were found.763Run `/status` inside Claude Code to see which settings sources are active. Inside the menu, the **Status** tab includes a `Setting sources` line that lists each layer Claude Code loaded for the current session, such as `User settings` or `Project local settings`. When [managed settings](/docs/en/admin-setup#decide-how-settings-reach-devices) are in effect, the entry shows the delivery channel in parentheses, for example `Enterprise managed settings (remote)`, `(plist)`, `(HKLM)`, `(HKCU)`, or `(file)`. The `remote` channel covers both claude.ai server-managed settings and [Claude apps gateway](/docs/en/claude-apps-gateway)-delivered policies. A layer appears in the list only when that source is loaded with at least one key, so an empty list means no settings sources were found.
747* **Settings files (JSON)**: Configure permissions, environment variables, and tool behavior776* **Settings files (JSON)**: Configure permissions, environment variables, and tool behavior
748* **Skills**: Custom prompts that can be invoked with `/skill-name` or loaded by Claude automatically777* **Skills**: Custom prompts that can be invoked with `/skill-name` or loaded by Claude automatically
749* **MCP servers**: Extend Claude Code with additional tools and integrations778* **MCP servers**: Extend Claude Code with additional tools and integrations
750* **Precedence**: Higher-level configurations (Managed) override lower-level ones (User/Project), apart from the exceptions under [Settings precedence](#settings-precedence)779* **Precedence**: Higher-level configurations (Managed) override lower-level ones (User/Project)
751* **Inheritance**: Settings merge across scopes; scalar values from higher-priority scopes override and arrays concatenate, each with the exceptions described under [Settings precedence](#settings-precedence)780* **Inheritance**: Settings merge across scopes; scalar values from higher-priority scopes override and arrays concatenate, each with the exceptions described under [Settings precedence](#settings-precedence)
752 781
753### System prompt782### System prompt
825 854
826 Plugins force-enabled by managed settings cannot be disabled this way, since managed settings override local settings.855 Plugins force-enabled by managed settings cannot be disabled this way, since managed settings override local settings.
827 856
828 Enabling a plugin from an external source such as a GitHub repository or npm package in a project's `.claude/settings.json` doesn't install it for other people. As of Claude Code v2.1.195, every path that loads plugins asks each user to [install and trust the plugin](/docs/en/discover-plugins#configure-team-marketplaces) before it runs.857 Enabling a plugin from an external source such as a GitHub repository or npm package in a project's `.claude/settings.json` doesn't install it for other people. On every path that loads plugins, Claude Code reports the plugin as not installed until each user [installs it themselves](/docs/en/discover-plugins#configure-team-marketplaces).
829</Note>858</Note>
830 859
831**Example**:860**Example**:
864 893
865Defines additional marketplaces that should be made available for the repository. Typically used in repository-level settings to ensure team members have access to required plugin sources.894Defines additional marketplaces that should be made available for the repository. Typically used in repository-level settings to ensure team members have access to required plugin sources.
866 895
867**When a repository includes `extraKnownMarketplaces`**:896When a repository's `.claude/settings.json` includes `extraKnownMarketplaces`, Claude Code adds those marketplaces for a team member after they accept the workspace trust dialog for that repository, with no separate prompt. In a folder they haven't trusted, including a `-p` run there or a repository under a parent folder they trusted earlier, Claude Code ignores the entries without a message. [What runs before you trust a folder](/docs/en/permissions#what-runs-before-you-trust-a-folder) compares this with the other content a repository can supply.
868
8691. Team members are prompted to install the marketplace when they trust the folder
8702. Team members are then prompted to install plugins from that marketplace
8713. Users can skip unwanted marketplaces or plugins (stored in user settings)
8724. Installation respects trust boundaries and requires explicit consent
873 897
874**Example**:898**Example**:
875 899
994Fields: `url` (required), `headers` (optional: HTTP headers for authenticated access)1018Fields: `url` (required), `headers` (optional: HTTP headers for authenticated access)
995 1019
996<Note>1020<Note>
997 URL-based marketplaces only download the `marketplace.json` file. They do not download plugin files from the server. Plugins in URL-based marketplaces must use external sources (GitHub, npm, git URL, or archive) rather than relative paths. For plugins with relative paths, use a Git-based marketplace instead. See [Troubleshooting](/docs/en/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces) for details.1021 URL-based marketplaces only download the `marketplace.json` file. They don't download plugin files from the server. Plugins in URL-based marketplaces must use a [plugin source](/docs/en/plugin-marketplaces#plugin-sources) other than a relative path. For plugins with relative paths, use a Git-based marketplace instead. See [Troubleshooting](/docs/en/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces) for details.
998</Note>1022</Note>
999 1023
10004. **NPM packages**:10244. **NPM packages**:
