settings diff — Spybara

settings.md +29 −37

Details

11### Available scopes11### Available scopes

12 12

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

16| **User** | `~/.claude/` directory | You, across all projects | No |16| **User** | `~/.claude/` directory | You, across all projects | No |

18| **Local** | `.claude/*.local.*` files | You, in this repository only | No (gitignored) |18| **Local** | `.claude/*.local.*` files | You, in this repository only | No (gitignored) |

19 19

20### When to use each scope20### When to use each scope

21 21

~~22**Enterprise scope** is for:~~22**Managed scope** is for:

23 23

24* Security policies that must be enforced organization-wide24* Security policies that must be enforced organization-wide

25* Compliance requirements that can't be overridden25* Compliance requirements that can't be overridden

47 47

48When the same setting is configured in multiple scopes, more specific scopes take precedence:48When the same setting is configured in multiple scopes, more specific scopes take precedence:

49 49

~~501. **Enterprise** (highest) - can't be overridden by anything~~501. **Managed** (highest) - can't be overridden by anything

512. **Command line arguments** - temporary session overrides512. **Command line arguments** - temporary session overrides

523. **Local** - overrides project and user settings523. **Local** - overrides project and user settings

534. **Project** - overrides user settings534. **Project** - overrides user settings

79* **Project settings** are saved in your project directory:79* **Project settings** are saved in your project directory:

80 * `.claude/settings.json` for settings that are checked into source control and shared with your team80 * `.claude/settings.json` for settings that are checked into source control and shared with your team

81 * `.claude/settings.local.json` for settings that are not checked in, useful for personal preferences and experimentation. Claude Code will configure git to ignore `.claude/settings.local.json` when it is created.81 * `.claude/settings.local.json` for settings that are not checked in, useful for personal preferences and experimentation. Claude Code will configure git to ignore `.claude/settings.local.json` when it is created.

82* **Managed settings** (Enterprise): Enterprise administrators can configure and distribute Claude Code settings to their organization through the [Claude.ai admin console](https://claude.ai/admin-settings/claude-code). These settings are fetched automatically when users authenticate, take precedence over user and project settings, and cannot be overridden locally. This feature is available to Claude for Enterprise customers. If you don't see this option in your admin console, contact your Anthropic account team to have the feature enabled.82* **Managed settings**: For organizations that need centralized control, Claude Code supports `managed-settings.json` and `managed-mcp.json` files that can be deployed to system directories:

~~84 For organizations that prefer file-based policy distribution, Claude Code also supports `managed-settings.json` and `managed-mcp.json` files that can be deployed to system directories:~~

85 83

86 * macOS: `/Library/Application Support/ClaudeCode/`84 * macOS: `/Library/Application Support/ClaudeCode/`

87 * Linux and WSL: `/etc/claude-code/`85 * Linux and WSL: `/etc/claude-code/`

91 These are system-wide paths (not user home directories like `~/Library/...`) that require administrator privileges. They are designed to be deployed by IT administrators.89 These are system-wide paths (not user home directories like `~/Library/...`) that require administrator privileges. They are designed to be deployed by IT administrators.

92 </Note>90 </Note>

93 91

~~94 See [Enterprise managed settings](/en/iam#enterprise-managed-settings) and [Enterprise MCP configuration](/en/mcp#enterprise-mcp-configuration) for details.~~92 See [Managed settings](/en/iam#managed-settings) and [Managed MCP configuration](/en/mcp#managed-mcp-configuration) for details.

95 93

96 <Note>94 <Note>

~~97 Enterprise deployments can also restrict **plugin marketplace additions** using~~95 Managed deployments can also restrict **plugin marketplace additions** using

~~98 `strictKnownMarketplaces`. For more information, see [Enterprise marketplace restrictions](/en/plugin-marketplaces#enterprise-marketplace-restrictions).~~96 `strictKnownMarketplaces`. For more information, see [Managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions).

99 </Note>97 </Note>

100* **Other configuration** is stored in `~/.claude.json`. This file contains your preferences (theme, notification settings, editor mode), OAuth session, [MCP server](/en/mcp) configurations for user and local scopes, per-project state (allowed tools, trust settings), and various caches. Project-scoped MCP servers are stored separately in `.mcp.json`.98* **Other configuration** is stored in `~/.claude.json`. This file contains your preferences (theme, notification settings, editor mode), OAuth session, [MCP server](/en/mcp) configurations for user and local scopes, per-project state (allowed tools, trust settings), and various caches. Project-scoped MCP servers are stored separately in `.mcp.json`.

101 99

131`settings.json` supports a number of options:129`settings.json` supports a number of options:

132 130

133| Key | Description | Example |131| Key | Description | Example |

134| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------- |132| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------- |

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

136| `cleanupPeriodDays` | Sessions inactive for longer than this period are deleted at startup. Setting to `0` immediately deletes all sessions. (default: 30 days) | `20` |134| `cleanupPeriodDays` | Sessions inactive for longer than this period are deleted at startup. Setting to `0` immediately deletes all sessions. (default: 30 days) | `20` |

137| `companyAnnouncements` | Announcement to display to users at startup. If multiple announcements are provided, they will be cycled through at random. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |135| `companyAnnouncements` | Announcement to display to users at startup. If multiple announcements are provided, they will be cycled through at random. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |

142| `hooks` | Configure custom commands to run before or after tool executions. See [hooks documentation](/en/hooks) | `{"PreToolUse": {"Bash": "echo 'Running command...'"}}` |140| `hooks` | Configure custom commands to run before or after tool executions. See [hooks documentation](/en/hooks) | `{"PreToolUse": {"Bash": "echo 'Running command...'"}}` |

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

146| `otelHeadersHelper` | Script to generate dynamic OpenTelemetry headers. Runs at startup and periodically (see [Dynamic headers](/en/monitoring-usage#dynamic-headers)) | `/bin/generate_otel_headers.sh` |144| `otelHeadersHelper` | Script to generate dynamic OpenTelemetry headers. Runs at startup and periodically (see [Dynamic headers](/en/monitoring-usage#dynamic-headers)) | `/bin/generate_otel_headers.sh` |

147| `statusLine` | Configure a custom status line to display context. See [`statusLine` documentation](/en/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |145| `statusLine` | Configure a custom status line to display context. See [`statusLine` documentation](/en/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |

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

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

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

158| `awsAuthRefresh` | Custom script that modifies the `.aws` directory (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |156| `awsAuthRefresh` | Custom script that modifies the `.aws` directory (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |

159| `awsCredentialExport` | Custom script that outputs JSON with AWS credentials (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |157| `awsCredentialExport` | Custom script that outputs JSON with AWS credentials (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |

160| `alwaysThinkingEnabled` | Enable [extended thinking](/en/common-workflows#use-extended-thinking) by default for all sessions. Typically configured via the `/config` command rather than editing directly | `true` |158| `alwaysThinkingEnabled` | Enable [extended thinking](/en/common-workflows#use-extended-thinking) by default for all sessions. Typically configured via the `/config` command rather than editing directly | `true` |

168| `deny` | Array of [permission rules](/en/iam#configuring-permissions) to deny tool use. Use this to also exclude sensitive files from Claude Code access. **Note:** Bash patterns are prefix matches and can be bypassed (see [Bash permission limitations](/en/iam#tool-specific-permission-rules)) | `[ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ]` |166| `deny` | Array of [permission rules](/en/iam#configuring-permissions) to deny tool use. Use this to also exclude sensitive files from Claude Code access. **Note:** Bash patterns are prefix matches and can be bypassed (see [Bash permission limitations](/en/iam#tool-specific-permission-rules)) | `[ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ]` |

171| `disableBypassPermissionsMode` | Set to `"disable"` to prevent `bypassPermissions` mode from being activated. This disables the `--dangerously-skip-permissions` command-line flag. See [managed settings](/en/iam#enterprise-managed-settings) | `"disable"` |169| `disableBypassPermissionsMode` | Set to `"disable"` to prevent `bypassPermissions` mode from being activated. This disables the `--dangerously-skip-permissions` command-line flag. See [managed settings](/en/iam#managed-settings) | `"disable"` |

172 170

173### Sandbox settings171### Sandbox settings

174 172

297 295

298### Hook configuration296### Hook configuration

299 297

300**Enterprise-only setting**: Controls which hooks are allowed to run. This setting can only be configured in [managed settings](#settings-files) and provides enterprise administrators with strict control over hook execution.298**Managed settings only**: Controls which hooks are allowed to run. This setting can only be configured in [managed settings](#settings-files) and provides administrators with strict control over hook execution.

301 299

302**Behavior when `allowManagedHooksOnly` is `true`:**300**Behavior when `allowManagedHooksOnly` is `true`:**

303 301

316 314

317Settings apply in order of precedence. From highest to lowest:315Settings apply in order of precedence. From highest to lowest:

318 316

3191. **Managed settings** (Enterprise)3171. **Managed settings** (`managed-settings.json`)

320 * Remote settings configured via the [Claude.ai admin console](https://claude.ai/admin-settings/claude-code)

321 * Fetched automatically when users authenticate

322 * Cannot be overridden

~~323~~

3242. **File-based managed settings** (`managed-settings.json`)

325 * Policies deployed by IT/DevOps to system directories318 * Policies deployed by IT/DevOps to system directories

326 * Cannot be overridden by user or project settings319 * Cannot be overridden by user or project settings

327 * Ignored when remote managed settings are configured

328 320

3293. **Command line arguments**3212. **Command line arguments**

330 * Temporary overrides for a specific session322 * Temporary overrides for a specific session

331 323

3324. **Local project settings** (`.claude/settings.local.json`)3243. **Local project settings** (`.claude/settings.local.json`)

333 * Personal project-specific settings325 * Personal project-specific settings

334 326

3355. **Shared project settings** (`.claude/settings.json`)3274. **Shared project settings** (`.claude/settings.json`)

336 * Team-shared project settings in source control328 * Team-shared project settings in source control

337 329

3386. **User settings** (`~/.claude/settings.json`)3305. **User settings** (`~/.claude/settings.json`)

339 * Personal global settings331 * Personal global settings

340 332

341This hierarchy ensures that enterprise security policies are always enforced while still allowing teams and individuals to customize their experience.333This hierarchy ensures that organizational policies are always enforced while still allowing teams and individuals to customize their experience.

342 334

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

344 336

348* **Settings files (JSON)**: Configure permissions, environment variables, and tool behavior340* **Settings files (JSON)**: Configure permissions, environment variables, and tool behavior

349* **Slash commands**: Custom commands that can be invoked during a session with `/command-name`341* **Slash commands**: Custom commands that can be invoked during a session with `/command-name`

350* **MCP servers**: Extend Claude Code with additional tools and integrations342* **MCP servers**: Extend Claude Code with additional tools and integrations

351* **Precedence**: Higher-level configurations (Enterprise) override lower-level ones (User/Project)343* **Precedence**: Higher-level configurations (Managed) override lower-level ones (User/Project)

352* **Inheritance**: Settings are merged, with more specific settings adding to or overriding broader ones344* **Inheritance**: Settings are merged, with more specific settings adding to or overriding broader ones

353 345

354### System prompt346### System prompt

470 462

471#### `strictKnownMarketplaces`463#### `strictKnownMarketplaces`

472 464

473**Enterprise-only setting**: Controls which plugin marketplaces users are allowed to add. This setting can only be configured in [`managed-settings.json`](/en/iam#enterprise-managed-settings) and provides enterprise administrators with strict control over marketplace sources.465**Managed settings only**: Controls which plugin marketplaces users are allowed to add. This setting can only be configured in [`managed-settings.json`](/en/iam#managed-settings) and provides administrators with strict control over marketplace sources.

474 466

475**Managed settings file locations**:467**Managed settings file locations**:

476 468

480 472

481**Key characteristics**:473**Key characteristics**:

482 474

483* Only available in enterprise managed settings (`managed-settings.json`)475* Only available in managed settings (`managed-settings.json`)

484* Cannot be overridden by user or project settings (highest precedence)476* Cannot be overridden by user or project settings (highest precedence)

485* Enforced BEFORE network/filesystem operations (blocked sources never execute)477* Enforced BEFORE network/filesystem operations (blocked sources never execute)

486* Uses exact matching for source specifications (including `ref`, `path` for git sources)478* Uses exact matching for source specifications (including `ref`, `path` for git sources)

611 603

613| --------------------- | ------------------------------------ | ------------------------------------ |605| --------------------- | ------------------------------------ | ------------------------------------ |

646**Important notes**:638**Important notes**:

647 639

648* Restrictions are checked BEFORE any network requests or filesystem operations640* Restrictions are checked BEFORE any network requests or filesystem operations

649* When blocked, users see clear error messages indicating the source is blocked by enterprise policy641* When blocked, users see clear error messages indicating the source is blocked by managed policy

650* The restriction applies only to adding NEW marketplaces; previously installed marketplaces remain accessible642* The restriction applies only to adding NEW marketplaces; previously installed marketplaces remain accessible

651* Enterprise managed settings have the highest precedence and cannot be overridden643* Managed settings have the highest precedence and cannot be overridden

652 644

653See [Enterprise marketplace restrictions](/en/plugin-marketplaces#enterprise-marketplace-restrictions) for user-facing documentation.645See [Managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions) for user-facing documentation.

654 646

655### Managing plugins647### Managing plugins

656 648

833## See also825## See also

834 826

835* [Identity and Access Management](/en/iam#configuring-permissions) - Learn about Claude Code's permission system827* [Identity and Access Management](/en/iam#configuring-permissions) - Learn about Claude Code's permission system

836* [IAM and access control](/en/iam#enterprise-managed-settings) - Enterprise policy management828* [IAM and access control](/en/iam#managed-settings) - Managed policy configuration

837* [Troubleshooting](/en/troubleshooting#auto-updater-issues) - Solutions for common configuration issues829* [Troubleshooting](/en/troubleshooting#auto-updater-issues) - Solutions for common configuration issues

838 830

839 831

settings.md Claude Code Docs, 2026-01-07 18:02 UTC → 2026-01-07 21:01 UTC