settings diff — Spybara

settings.md +692 −176

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

1# Claude Code settings5# Claude Code settings

2 6

3> Configure Claude Code with global and project-level settings, and environment variables.7> Configure Claude Code with global and project-level settings, and environment variables.

4 8

5Claude Code offers a variety of settings to configure its behavior to meet your needs. You can configure Claude Code by running the `/config` command when using the interactive REPL, which opens a tabbed Settings interface where you can view status information and modify configuration options.9Claude Code offers a variety of settings to configure its behavior to meet your needs. You can configure Claude Code by running the `/config` command when using the interactive REPL, which opens a tabbed Settings interface where you can view status information and modify configuration options.

6 10

11## Configuration scopes

13Claude Code uses a **scope system** to determine where configurations apply and who they're shared with. Understanding scopes helps you decide how to configure Claude Code for personal use, team collaboration, or enterprise deployment.

15### Available scopes

18| :---------- | :--------------------------------------------------------------------------------- | :----------------------------------- | :--------------------- |

24### When to use each scope

26**Managed scope** is for:

28* Security policies that must be enforced organization-wide

29* Compliance requirements that can't be overridden

30* Standardized configurations deployed by IT/DevOps

32**User scope** is best for:

34* Personal preferences you want everywhere (themes, editor settings)

35* Tools and plugins you use across all projects

36* API keys and authentication (stored securely)

38**Project scope** is best for:

40* Team-shared settings (permissions, hooks, MCP servers)

41* Plugins the whole team should have

42* Standardizing tooling across collaborators

44**Local scope** is best for:

46* Personal overrides for a specific project

47* Testing configurations before sharing with the team

48* Machine-specific settings that won't work for others

50### How scopes interact

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

541. **Managed** (highest) - can't be overridden by anything

552. **Command line arguments** - temporary session overrides

563. **Local** - overrides project and user settings

574. **Project** - overrides user settings

585. **User** (lowest) - applies when nothing else specifies the setting

60For example, if a permission is allowed in user settings but denied in project settings, the project setting takes precedence and the permission is blocked.

62### What uses scopes

64Scopes apply to many Claude Code features:

67| :-------------- | :------------------------ | :--------------------------------- | :----------------------------- |

74***

7## Settings files76## Settings files

8 77

~~9The `settings.json` file is our official mechanism for configuring Claude~~78The `settings.json` file is the official mechanism for configuring Claude

10Code through hierarchical settings:79Code through hierarchical settings:

11 80

12* **User settings** are defined in `~/.claude/settings.json` and apply to all81* **User settings** are defined in `~/.claude/settings.json` and apply to all

14* **Project settings** are saved in your project directory:83* **Project settings** are saved in your project directory:

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

16 * `.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.85 * `.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.

~~17* For enterprise deployments of Claude Code, we also support **enterprise~~86* **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:

~~18 managed policy settings**. These take precedence over user and project~~87

~~19 settings. System administrators can deploy policies to:~~88 * **Server-managed settings**: delivered from Anthropic's servers via the Claude.ai admin console. See [server-managed settings](/en/server-managed-settings).

~~20 * macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`~~89 * **MDM/OS-level policies**: delivered through native device management on macOS and Windows:

~~21 * Linux and WSL: `/etc/claude-code/managed-settings.json`~~90 * macOS: `com.anthropic.claudecode` managed preferences domain. The plist's top-level keys mirror `managed-settings.json`, with nested settings as dictionaries and arrays as plist arrays. Deploy via configuration profiles in Jamf, Iru (Kandji), or similar MDM tools.

~~22 * Windows: `C:\ProgramData\ClaudeCode\managed-settings.json`~~91 * Windows: `HKLM\SOFTWARE\Policies\ClaudeCode` registry key with a `Settings` value (REG\_SZ or REG\_EXPAND\_SZ) containing JSON (deployed via Group Policy or Intune)

~~23* Enterprise deployments can also configure **managed MCP servers** that override~~92 * Windows (user-level): `HKCU\SOFTWARE\Policies\ClaudeCode` (lowest policy priority, only used when no admin-level source exists)

~~24 user-configured servers. See [Enterprise MCP configuration](/en/docs/claude-code/mcp#enterprise-mcp-configuration):~~93 * **File-based**: `managed-settings.json` and `managed-mcp.json` deployed to system directories:

~~25 * macOS: `/Library/Application Support/ClaudeCode/managed-mcp.json`~~94

~~26 * Linux and WSL: `/etc/claude-code/managed-mcp.json`~~95 * macOS: `/Library/Application Support/ClaudeCode/`

~~27 * Windows: `C:\ProgramData\ClaudeCode\managed-mcp.json`~~96 * Linux and WSL: `/etc/claude-code/`

97 * Windows: `C:\Program Files\ClaudeCode\`

99 <Warning>

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

101 </Warning>

102

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

104

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

106

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

108

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

110

111 This [repository](https://github.com/anthropics/claude-code/tree/main/examples/mdm) includes starter deployment templates for Jamf, Iru (Kandji), Intune, and Group Policy. Use these as starting points and adjust them to fit your needs.

112

113 <Note>

114 Managed deployments can also restrict **plugin marketplace additions** using

115 `strictKnownMarketplaces`. For more information, see [Managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions).

116 </Note>

117* **Other configuration** is stored in `~/.claude.json`. This file contains your 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`.

118

119<Note>

120 Claude Code automatically creates timestamped backups of configuration files and retains the five most recent backups to prevent data loss.

121</Note>

28 122

29```JSON Example settings.json theme={null}123```JSON Example settings.json theme={null}

30{124{

125 "$schema": "https://json.schemastore.org/claude-code-settings.json",

31 "permissions": {126 "permissions": {

32 "allow": [127 "allow": [

33 "Bash(npm run lint)",128 "Bash(npm run lint)",

~~34 "Bash(npm run test:*)",~~129 "Bash(npm run test *)",

35 "Read(~/.zshrc)"130 "Read(~/.zshrc)"

36 ],131 ],

37 "deny": [132 "deny": [

~~38 "Bash(curl:*)",~~133 "Bash(curl *)",

39 "Read(./.env)",134 "Read(./.env)",

40 "Read(./.env.*)",135 "Read(./.env.*)",

41 "Read(./secrets/**)"136 "Read(./secrets/**)"

44 "env": {139 "env": {

45 "CLAUDE_CODE_ENABLE_TELEMETRY": "1",140 "CLAUDE_CODE_ENABLE_TELEMETRY": "1",

46 "OTEL_METRICS_EXPORTER": "otlp"141 "OTEL_METRICS_EXPORTER": "otlp"

~~47 }~~142 },

143 "companyAnnouncements": [

144 "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",

145 "Reminder: Code reviews required for all PRs",

146 "New security policy in effect"

147 ]

48}148}

49```149```

50 150

151The `$schema` line in the example above points to the [official JSON schema](https://json.schemastore.org/claude-code-settings.json) for Claude Code settings. Adding it to your `settings.json` enables autocomplete and inline validation in VS Code, Cursor, and any other editor that supports JSON schema validation.

152

153The published schema is updated periodically and may not include settings added in the most recent CLI releases, so a validation warning on a recently documented field does not necessarily mean your configuration is invalid.

154

51### Available settings155### Available settings

52 156

53`settings.json` supports a number of options:157`settings.json` supports a number of options:

54 158

55| Key | Description | Example |159| Key | Description | Example |

56| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------- |160| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- |

161| `agent` | Run the main thread as a named subagent. Applies that subagent's system prompt, tool restrictions, and model. See [Invoke subagents explicitly](/en/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |

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

163| `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 restriction, empty array = block all HTTP hooks. Arrays merge across settings sources. See [Hook configuration](#hook-configuration) | `["https://hooks.example.com/*"]` |

164| `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" }]` |

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

166| `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](/en/mcp#managed-mcp-configuration) | `true` |

167| `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](/en/permissions#managed-only-settings) | `true` |

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

57| `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` |169| `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` |

58| `cleanupPeriodDays` | How long to locally retain chat transcripts based on last activity date (default: 30 days) | `20` |170| `attribution` | Customize attribution for git commits and pull requests. See [Attribution settings](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |

59| `env` | Environment variables that will be applied to every session | `{"FOO": "bar"}` |171| `autoMemoryDirectory` | Custom directory for [auto memory](/en/memory#storage-location) storage. Accepts `~/`-expanded paths. Not accepted in project settings (`.claude/settings.json`) to prevent shared repos from redirecting memory writes to sensitive locations. Accepted from policy, local, and user settings | `"~/my-memory-dir"` |

60| `includeCoAuthoredBy` | Whether to include the `co-authored-by Claude` byline in git commits and pull requests (default: `true`) | `false` |172| `autoMode` | Customize what the [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) classifier blocks and allows. Contains `environment`, `allow`, and `soft_deny` arrays of prose rules. Include the literal string `"$defaults"` in an array to inherit the built-in rules at that position. See [Configure auto mode](/en/auto-mode-config). Not read from shared project settings | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |

61| `permissions` | See table below for structure of permissions. | |173| `autoScrollEnabled` | In [fullscreen rendering](/en/fullscreen), follow new output to the bottom of the conversation. Default: `true`. Appears in `/config` as **Auto-scroll**. Permission prompts still scroll into view when this is off | `false` |

62| `hooks` | Configure custom commands to run before or after tool executions. See [hooks documentation](hooks) | `{"PreToolUse": {"Bash": "echo 'Running command...'"}}` |174| `autoUpdatesChannel` | Release channel to follow for updates. Use `"stable"` for a version that is typically about one week old and skips versions with major regressions, or `"latest"` (default) for the most recent release | `"stable"` |

64| `model` | Override the default model to use for Claude Code | `"claude-sonnet-4-5-20250929"` |176| `awaySummaryEnabled` | Show a one-line session recap when you return to the terminal after a few minutes away. Set to `false` or turn off Session recap in `/config` to disable. Same as [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](/en/env-vars) | `true` |

65| `statusLine` | Configure a custom status line to display context. See [statusLine documentation](statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |177| `awsAuthRefresh` | Custom script that modifies the `.aws` directory (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |

66| `outputStyle` | Configure an output style to adjust the system prompt. See [output styles documentation](output-styles) | `"Explanatory"` |178| `awsCredentialExport` | Custom script that outputs JSON with AWS credentials (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |

67| `forceLoginMethod` | Use `claudeai` to restrict login to Claude.ai accounts, `console` to restrict login to Claude Console (API usage billing) accounts | `claudeai` |179| `blockedMarketplaces` | (Managed settings only) Blocklist of marketplace sources. 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. Blocked sources are checked before downloading, so they never touch the filesystem. See [Managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |

68| `forceLoginOrgUUID` | Specify the UUID of an organization to automatically select it during login, bypassing the organization selection step. Requires `forceLoginMethod` to be set | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` |180| `channelsEnabled` | (Managed settings only) Allow [channels](/en/channels) for Team and Enterprise users. Unset or `false` blocks channel message delivery regardless of what users pass to `--channels` | `true` |

181| `cleanupPeriodDays` | Session files older than this period are deleted at startup (default: 30 days, minimum 1). Setting to `0` is rejected with a validation error. Also controls the age cutoff for automatic removal of [orphaned subagent worktrees](/en/common-workflows#worktree-cleanup) at startup. To disable transcript writes entirely, set the [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/en/env-vars) environment variable, or in non-interactive mode (`-p`) use the `--no-session-persistence` flag or the `persistSession: false` SDK option. | `20` |

182| `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"]` |

183| `defaultShell` | Default shell for input-box `!` commands. Accepts `"bash"` (default) or `"powershell"`. Setting `"powershell"` routes interactive `!` commands through PowerShell on Windows. Requires `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. See [PowerShell tool](/en/tools-reference#powershell-tool) | `"powershell"` |

184| `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" }]` |

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

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

187| `disableDeepLinkRegistration` | Set to `"disable"` to prevent Claude Code from registering the `claude-cli://` protocol handler with the operating system on startup. Deep links let external tools open a Claude Code session with a pre-filled prompt via `claude-cli://open?q=...`. The `q` parameter supports multi-line prompts using URL-encoded newlines (`%0A`). Useful in environments where protocol handler registration is restricted or managed separately | `"disable"` |

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

189| `disableSkillShellExecution` | Disable inline shell execution for `` !`...` `` and ` ```! ` blocks in [skills](/en/skills) and custom commands from user, project, plugin, or additional-directory sources. Commands are replaced with `[shell command execution disabled by policy]` instead of being run. Bundled and managed skills are not affected. Most useful in [managed settings](/en/permissions#managed-settings) where users cannot override it | `true` |

190| `editorMode` | Key binding mode for the input prompt: `"normal"` or `"vim"`. Default: `"normal"`. Appears in `/config` as **Editor mode** | `"vim"` |

191| `effortLevel` | Persist the [effort level](/en/model-config#adjust-effort-level) across sessions. Accepts `"low"`, `"medium"`, `"high"`, or `"xhigh"`. Written automatically when you run `/effort` with one of those values. See [Adjust effort level](/en/model-config#adjust-effort-level) for supported models | `"xhigh"` |

71| `disabledMcpjsonServers` | List of specific MCP servers from `.mcp.json` files to reject | `["filesystem"]` |194| `env` | Environment variables that will be applied to every session | `{"FOO": "bar"}` |

72| `useEnterpriseMcpConfigOnly` | When set in managed-settings.json, restricts MCP servers to only those defined in managed-mcp.json. See [Enterprise MCP configuration](/en/docs/claude-code/mcp#enterprise-mcp-configuration) | `true` |195| `fastModePerSessionOptIn` | When `true`, fast mode does not persist across sessions. Each session starts with fast mode off, requiring users to enable it with `/fast`. The user's fast mode preference is still saved. See [Require per-session opt-in](/en/fast-mode#require-per-session-opt-in) | `true` |

73| `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/docs/claude-code/mcp#enterprise-mcp-configuration) | `[{ "serverName": "github" }]` |196| `feedbackSurveyRate` | Probability (0–1) that the [session quality survey](/en/data-usage#session-quality-surveys) appears when eligible. Set to `0` to suppress entirely. Useful when using Bedrock, Vertex, or Foundry where the default sample rate does not apply | `0.05` |

74| `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/docs/claude-code/mcp#enterprise-mcp-configuration) | `[{ "serverName": "filesystem" }]` |197| `fileSuggestion` | Configure a custom script for `@` file autocomplete. See [File suggestion settings](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |

75| `awsAuthRefresh` | Custom script that modifies the `.aws` directory (see [advanced credential configuration](/en/docs/claude-code/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |198| `forceLoginMethod` | Use `claudeai` to restrict login to Claude.ai accounts, `console` to restrict login to Claude Console (API usage billing) accounts | `claudeai` |

76| `awsCredentialExport` | Custom script that outputs JSON with AWS credentials (see [advanced credential configuration](/en/docs/claude-code/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |199| `forceLoginOrgUUID` | Require login to belong to a specific organization. Accepts a single UUID string, which also pre-selects that organization during login, or an array of UUIDs where any listed organization is accepted without pre-selection. When set in managed settings, login fails if the authenticated account does not belong to a listed organization; an empty array fails closed and blocks login with a misconfiguration message | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` or `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |

200| `forceRemoteSettingsRefresh` | (Managed settings only) Block CLI startup until remote managed settings are freshly fetched from the server. If the fetch fails, the CLI exits rather than continuing with cached or no settings. When not set, startup continues without waiting for remote settings. See [fail-closed enforcement](/en/server-managed-settings#enforce-fail-closed-startup) | `true` |

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

202| `httpHookAllowedEnvVars` | Allowlist of environment variable names HTTP hooks may interpolate into headers. When set, each hook's effective `allowedEnvVars` is the intersection with this list. Undefined = no restriction. Arrays merge across settings sources. See [Hook configuration](#hook-configuration) | `["MY_TOKEN", "HOOK_SECRET"]` |

203| `includeCoAuthoredBy` | **Deprecated**: Use `attribution` instead. Whether to include the `co-authored-by Claude` byline in git commits and pull requests (default: `true`) | `false` |

204| `includeGitInstructions` | Include built-in commit and PR workflow instructions and the git status snapshot in Claude's system prompt (default: `true`). Set to `false` to remove both, for example when using your own git workflow skills. The `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` environment variable takes precedence over this setting when set | `false` |

205| `language` | Configure Claude's preferred response language (e.g., `"japanese"`, `"spanish"`, `"french"`). Claude will respond in this language by default. Also sets the [voice dictation](/en/voice-dictation#change-the-dictation-language) language | `"japanese"` |

206| `minimumVersion` | Floor that prevents background auto-updates and `claude update` from installing a version below this one. Switching from the `"latest"` channel to `"stable"` via `/config` prompts you to stay on the current version or allow the downgrade. Choosing to stay sets this value. Also useful in [managed settings](/en/permissions#managed-settings) to pin an organization-wide minimum | `"2.1.100"` |

207| `model` | Override the default model to use for Claude Code | `"claude-sonnet-4-6"` |

208| `modelOverrides` | Map Anthropic model IDs to provider-specific model IDs such as Bedrock inference profile ARNs. Each model picker entry uses its mapped value when calling the provider API. See [Override model IDs per version](/en/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |

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

210| `outputStyle` | Configure an output style to adjust the system prompt. See [output styles documentation](/en/output-styles) | `"Explanatory"` |

211| `permissions` | See table below for structure of permissions. | |

212| `plansDirectory` | Customize where plan files are stored. Path is relative to project root. Default: `~/.claude/plans` | `"./plans"` |

213| `pluginTrustMessage` | (Managed settings only) Custom message appended to the plugin trust warning shown before installation. Use this to add organization-specific context, for example to confirm that plugins from your internal marketplace are vetted. | `"All plugins from our marketplace are approved by IT"` |

214| `preferredNotifChannel` | Method for task-complete and permission-prompt notifications: `"auto"`, `"terminal_bell"`, `"iterm2"`, `"iterm2_with_bell"`, `"kitty"`, `"ghostty"`, or `"notifications_disabled"`. Default: `"auto"`, which sends a desktop notification in iTerm2, Ghostty, and Kitty and does nothing in other terminals. Set `"terminal_bell"` to ring the bell character in any terminal. Appears in `/config` as **Notifications**. See [Get a terminal bell or notification](/en/terminal-config#get-a-terminal-bell-or-notification) | `"terminal_bell"` |

215| `prefersReducedMotion` | Reduce or disable UI animations (spinners, shimmer, flash effects) for accessibility | `true` |

216| `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}"` |

217| `respectGitignore` | Control whether the `@` file picker respects `.gitignore` patterns. When `true` (default), files matching `.gitignore` patterns are excluded from suggestions | `false` |

218| `showClearContextOnPlanAccept` | Show the "clear context" option on the plan accept screen. Defaults to `false`. Set to `true` to restore the option | `true` |

219| `showThinkingSummaries` | Show [extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) summaries in interactive sessions. When unset or `false` (default in interactive mode), thinking blocks are redacted by the API and shown as a collapsed stub. Redaction only changes what you see, not what the model generates: to reduce thinking spend, [lower the budget or disable thinking](/en/common-workflows#use-extended-thinking-thinking-mode) instead. Non-interactive mode (`-p`) and SDK callers always receive summaries regardless of this setting | `true` |

220| `showTurnDuration` | Show turn duration messages after responses, e.g. "Cooked for 1m 6s". Default: `true`. Appears in `/config` as **Show turn duration** | `false` |

221| `skipWebFetchPreflight` | Skip the [WebFetch domain safety check](/en/data-usage#webfetch-domain-safety-check) that sends each requested hostname to `api.anthropic.com` before fetching. Set to `true` in environments that block traffic to Anthropic, such as Bedrock, Vertex AI, or Foundry deployments with restrictive egress. When skipped, WebFetch attempts any URL without consulting the blocklist | `true` |

222| `spinnerTipsEnabled` | Show tips in the spinner while Claude is working. Set to `false` to disable tips (default: `true`) | `false` |

223| `spinnerTipsOverride` | Override spinner tips with custom strings. `tips`: array of tip strings. `excludeDefault`: if `true`, only show custom tips; if `false` or absent, custom tips are merged with built-in tips | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |

224| `spinnerVerbs` | Customize the action verbs shown in the spinner and turn duration messages. Set `mode` to `"replace"` to use only your verbs, or `"append"` to add them to the defaults | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |

225| `sshConfigs` | SSH connections to show in the [Desktop](/en/desktop#pre-configure-ssh-connections-for-your-team) environment dropdown. Each entry requires `id`, `name`, and `sshHost`; `sshPort`, `sshIdentityFile`, and `startDirectory` are optional. When set in managed settings, connections are read-only for users. Read from managed and user settings only | `[{"id": "dev-vm", "name": "Dev VM", "sshHost": "user@dev.example.com"}]` |

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

227| `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](/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |

228| `teammateMode` | How [agent team](/en/agent-teams) teammates display: `auto` (picks split panes in tmux or iTerm2, in-process otherwise), `in-process`, or `tmux`. See [choose a display mode](/en/agent-teams#choose-a-display-mode) | `"in-process"` |

229| `terminalProgressBarEnabled` | Show the terminal progress bar in supported terminals: ConEmu, Ghostty 1.2.0+, and iTerm2 3.6.6+. Default: `true`. Appears in `/config` as **Terminal progress bar** | `false` |

230| `tui` | Terminal UI renderer. Use `"fullscreen"` for the flicker-free [alt-screen renderer](/en/fullscreen) with virtualized scrollback. Use `"default"` for the classic main-screen renderer. Set via `/tui` | `"fullscreen"` |

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

232| `viewMode` | Default transcript view mode on startup: `"default"`, `"verbose"`, or `"focus"`. Overrides the sticky `/focus` selection when set | `"verbose"` |

233| `voice` | [Voice dictation](/en/voice-dictation) settings: `enabled` turns dictation on, `mode` selects `"hold"` or `"tap"`, and `autoSubmit` sends the prompt on key release in hold mode. Written automatically when you run `/voice`. Requires a Claude.ai account | `{ "enabled": true, "mode": "tap" }` |

234| `voiceEnabled` | Legacy alias for `voice.enabled`. Prefer the `voice` object | `true` |

235| `wslInheritsWindowsSettings` | (Windows managed settings only) When `true`, Claude Code on WSL reads managed settings from the Windows policy chain in addition to `/etc/claude-code`, with Windows sources taking priority. Only honored when set in the HKLM registry key or `C:\Program Files\ClaudeCode\managed-settings.json`, both of which require Windows admin to write. For HKCU policy to also apply on WSL, the flag must additionally be set in HKCU itself. Has no effect on native Windows | `true` |

236

237### Global config settings

238

239These settings are stored in `~/.claude.json` rather than `settings.json`. Adding them to `settings.json` will trigger a schema validation error.

240

241<Note>

242 Versions before v2.1.119 also store `autoScrollEnabled`, `editorMode`, `showTurnDuration`, `teammateMode`, and `terminalProgressBarEnabled` here instead of in `settings.json`.

243</Note>

244

245| Key | Description | Example |

246| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |

247| `autoConnectIde` | Automatically connect to a running IDE when Claude Code starts from an external terminal. Default: `false`. Appears in `/config` as **Auto-connect to IDE (external terminal)** when running outside a VS Code or JetBrains terminal | `true` |

248| `autoInstallIdeExtension` | Automatically install the Claude Code IDE extension when running from a VS Code terminal. Default: `true`. Appears in `/config` as **Auto-install IDE extension** when running inside a VS Code or JetBrains terminal. You can also set the [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/en/env-vars) environment variable | `false` |

249| `externalEditorContext` | Prepend Claude's previous response as `#`-commented context when you open the external editor with `Ctrl+G`. Default: `false`. Appears in `/config` as **Show last response in external editor** | `true` |

250

251### Worktree settings

252

253Configure how `--worktree` creates and manages git worktrees. Use these settings to reduce disk usage and startup time in large monorepos.

254

255| Key | Description | Example |

256| :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |

257| `worktree.symlinkDirectories` | Directories to symlink from the main repository into each worktree to avoid duplicating large directories on disk. No directories are symlinked by default | `["node_modules", ".cache"]` |

258| `worktree.sparsePaths` | Directories to check out in each worktree via git sparse-checkout (cone mode). Only the listed paths are written to disk, which is faster in large monorepos | `["packages/my-app", "shared/utils"]` |

259

260To copy gitignored files like `.env` into new worktrees, use a [`.worktreeinclude` file](/en/common-workflows#copy-gitignored-files-to-worktrees) in your project root instead of a setting.

77 261

78### Permission settings262### Permission settings

79 263

81| :----------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |265| :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |

82| `allow` | Array of [permission rules](/en/docs/claude-code/iam#configuring-permissions) to allow tool use. **Note:** Bash rules use prefix matching, not regex | `[ "Bash(git diff:*)" ]` |266| `allow` | Array of permission rules to allow tool use. See [Permission rule syntax](#permission-rule-syntax) below for pattern matching details | `[ "Bash(git diff *)" ]` |

83| `ask` | Array of [permission rules](/en/docs/claude-code/iam#configuring-permissions) to ask for confirmation upon tool use. | `[ "Bash(git push:*)" ]` |267| `ask` | Array of permission rules to ask for confirmation upon tool use. See [Permission rule syntax](#permission-rule-syntax) below | `[ "Bash(git push *)" ]` |

84| `deny` | Array of [permission rules](/en/docs/claude-code/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/docs/claude-code/iam#tool-specific-permission-rules)) | `[ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ]` |268| `deny` | Array of permission rules to deny tool use. Use this to exclude sensitive files from Claude Code access. See [Permission rule syntax](#permission-rule-syntax) and [Bash permission limitations](/en/permissions#tool-specific-permission-rules) | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |

85| `additionalDirectories` | Additional [working directories](iam#working-directories) that Claude has access to | `[ "../docs/" ]` |269| `additionalDirectories` | Additional [working directories](/en/permissions#working-directories) for file access. Most `.claude/` configuration is [not discovered](/en/permissions#additional-directories-grant-file-access-not-configuration) from these directories | `[ "../docs/" ]` |

86| `defaultMode` | Default [permission mode](iam#permission-modes) when opening Claude Code | `"acceptEdits"` |270| `defaultMode` | Default [permission mode](/en/permission-modes) when opening Claude Code. Valid values: `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`. The `--permission-mode` CLI flag overrides this setting for a single session | `"acceptEdits"` |

87| `disableBypassPermissionsMode` | Set to `"disable"` to prevent `bypassPermissions` mode from being activated. This disables the `--dangerously-skip-permissions` command-line flag. See [managed policy settings](iam#enterprise-managed-policy-settings) | `"disable"` |271| `disableBypassPermissionsMode` | Set to `"disable"` to prevent `bypassPermissions` mode from being activated. This disables the `--dangerously-skip-permissions` command-line flag. Typically placed in [managed settings](/en/permissions#managed-settings) to enforce organizational policy, but works from any scope | `"disable"` |

272| `skipDangerousModePermissionPrompt` | Skip the confirmation prompt shown before entering bypass permissions mode via `--dangerously-skip-permissions` or `defaultMode: "bypassPermissions"`. Ignored when set in project settings (`.claude/settings.json`) to prevent untrusted repositories from auto-bypassing the prompt | `true` |

88 273

~~89### Sandbox settings~~274### Permission rule syntax

90 275

~~91Configure advanced sandboxing behavior. Sandboxing isolates bash commands from your filesystem and network. See [Sandboxing](/en/docs/claude-code/sandboxing) for details.~~276Permission rules follow the format `Tool` or `Tool(specifier)`. Rules are evaluated in order: deny rules first, then ask, then allow. The first matching rule wins.

92 277

~~93**Filesystem and network restrictions** are configured via Read, Edit, and WebFetch permission rules, not via these sandbox settings.~~278Quick examples:

279

280| Rule | Effect |

281| :----------------------------- | :--------------------------------------- |

282| `Bash` | Matches all Bash commands |

283| `Bash(npm run *)` | Matches commands starting with `npm run` |

284| `Read(./.env)` | Matches reading the `.env` file |

285| `WebFetch(domain:example.com)` | Matches fetch requests to example.com |

286

287For the complete rule syntax reference, including wildcard behavior, tool-specific patterns for Read, Edit, WebFetch, MCP, and Agent rules, and security limitations of Bash patterns, see [Permission rule syntax](/en/permissions#permission-rule-syntax).

288

289### Sandbox settings

290

291Configure advanced sandboxing behavior. Sandboxing isolates bash commands from your filesystem and network. See [Sandboxing](/en/sandboxing) for details.

94 292

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

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

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

101| `network.allowUnixSockets` | Unix socket paths accessible in sandbox (for SSH agents, etc.) | `["~/.ssh/agent-socket"]` |300| `filesystem.allowWrite` | Additional paths where sandboxed commands can write. Arrays are merged across all settings scopes: user, project, and managed paths are combined, not replaced. Also merged with paths from `Edit(...)` allow permission rules. See [path prefixes](#sandbox-path-prefixes) below. | `["/tmp/build", "~/.kube"]` |

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

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

304| `filesystem.allowManagedReadPathsOnly` | (Managed settings only) Only `filesystem.allowRead` paths from managed settings are respected. `denyRead` still merges from all sources. Default: false | `true` |

305| `network.allowUnixSockets` | (macOS only) Unix socket paths accessible in sandbox. Ignored on Linux and WSL2, where the seccomp filter cannot inspect socket paths; use `allowAllUnixSockets` instead. | `["~/.ssh/agent-socket"]` |

306| `network.allowAllUnixSockets` | Allow all Unix socket connections in sandbox. On Linux and WSL2 this is the only way to permit Unix sockets, since it skips the seccomp filter that otherwise blocks `socket(AF_UNIX, ...)` calls. Default: false | `true` |

307| `network.allowLocalBinding` | Allow binding to localhost ports (macOS only). Default: false | `true` |

308| `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.*"]` |

309| `network.allowedDomains` | Array of domains to allow for outbound network traffic. Supports wildcards (e.g., `*.example.com`). | `["github.com", "*.npmjs.org"]` |

310| `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"]` |

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

103| `network.httpProxyPort` | HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8080` |312| `network.httpProxyPort` | HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8080` |

104| `network.socksProxyPort` | SOCKS5 proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8081` |313| `network.socksProxyPort` | SOCKS5 proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8081` |

315| `enableWeakerNetworkIsolation` | (macOS only) Allow access to the system TLS trust service (`com.apple.trustd.agent`) in the sandbox. Required for Go-based tools like `gh`, `gcloud`, and `terraform` to verify TLS certificates when using `httpProxyPort` with a MITM proxy and custom CA. **Reduces security** by opening a potential data exfiltration path. Default: false | `true` |

316

317#### Sandbox path prefixes

318

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

320

321| Prefix | Meaning | Example |

322| :---------------- | :------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ |

323| `/` | Absolute path from filesystem root | `/tmp/build` stays `/tmp/build` |

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

325| `./` or no prefix | Relative to the project root for project settings, or to `~/.claude` for user settings | `./output` in `.claude/settings.json` resolves to `<project-root>/output` |

326

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

106 328

107**Configuration example:**329**Configuration example:**

108 330

111 "sandbox": {333 "sandbox": {

112 "enabled": true,334 "enabled": true,

113 "autoAllowBashIfSandboxed": true,335 "autoAllowBashIfSandboxed": true,

114 "excludedCommands": ["docker"],336 "excludedCommands": ["docker *"],

337 "filesystem": {

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

339 "denyRead": ["~/.aws/credentials"]

340 },

115 "network": {341 "network": {

342 "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],

343 "deniedDomains": ["uploads.github.com"],

116 "allowUnixSockets": [344 "allowUnixSockets": [

117 "/var/run/docker.sock"345 "/var/run/docker.sock"

118 ],346 ],

119 "allowLocalBinding": true347 "allowLocalBinding": true

120 }348 }

121 },

122 "permissions": {

123 "deny": [

124 "Read(.envrc)",

125 "Read(~/.aws/**)"

126 ]

127 }349 }

128}350}

129```351```

130 352

131**Filesystem access** is controlled via Read/Edit permissions:353**Filesystem and network restrictions** can be configured in two ways that are merged together:

354

355* **`sandbox.filesystem` settings** (shown above): Control paths at the OS-level sandbox boundary. These restrictions apply to all subprocess commands (e.g., `kubectl`, `terraform`, `npm`), not just Claude's file tools.

356* **Permission rules**: Use `Edit` allow/deny rules to control Claude's file tool access, `Read` deny rules to block reads, and `WebFetch` allow/deny rules to control network domains. Paths from these rules are also merged into the sandbox configuration.

357

358### Attribution settings

359

360Claude Code adds attribution to git commits and pull requests. These are configured separately:

361

362* Commits use [git trailers](https://git-scm.com/docs/git-interpret-trailers) (like `Co-Authored-By`) by default, which can be customized or disabled

363* Pull request descriptions are plain text

364

365| Keys | Description |

366| :------- | :----------------------------------------------------------------------------------------- |

367| `commit` | Attribution for git commits, including any trailers. Empty string hides commit attribution |

368| `pr` | Attribution for pull request descriptions. Empty string hides pull request attribution |

369

370**Default commit attribution:**

371

372```text theme={null}

373🤖 Generated with [Claude Code](https://claude.com/claude-code)

374

375 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

376```

377

378**Default pull request attribution:**

379

380```text theme={null}

381🤖 Generated with [Claude Code](https://claude.com/claude-code)

382```

383

384**Example:**

385

386```json theme={null}

387{

388 "attribution": {

389 "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",

390 "pr": ""

391 }

392}

393```

394

395<Note>

396 The `attribution` setting takes precedence over the deprecated `includeCoAuthoredBy` setting. To hide all attribution, set `commit` and `pr` to empty strings.

397</Note>

398

399### File suggestion settings

400

401Configure 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.

402

403```json theme={null}

404{

405 "fileSuggestion": {

406 "type": "command",

407 "command": "~/.claude/file-suggestion.sh"

408 }

409}

410```

411

412The command runs with the same environment variables as [hooks](/en/hooks), including `CLAUDE_PROJECT_DIR`. It receives JSON via stdin with a `query` field:

413

414```json theme={null}

415{"query": "src/comp"}

416```

417

418Output newline-separated file paths to stdout (currently limited to 15):

419

420```text theme={null}

421src/components/Button.tsx

422src/components/Modal.tsx

423src/components/Form.tsx

424```

425

426**Example:**

427

428```bash theme={null}

429#!/bin/bash

430query=$(cat | jq -r '.query')

431your-repo-file-index --query "$query" | head -20

432```

433

434### Hook configuration

435

436These settings control which hooks are allowed to run and what HTTP hooks can access. The `allowManagedHooksOnly` setting can only be configured in [managed settings](#settings-files). The URL and env var allowlists can be set at any settings level and merge across sources.

132 437

133* Read deny rules block file reads in sandbox438**Behavior when `allowManagedHooksOnly` is `true`:**

134* Edit allow rules permit file writes (in addition to the defaults, e.g. the current working directory)

135* Edit deny rules block writes within allowed paths

136 439

137**Network access** is controlled via WebFetch permissions:440* Managed hooks and SDK hooks are loaded

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

442* User hooks, project hooks, and all other plugin hooks are blocked

138 443

139* WebFetch allow rules permit network domains444**Restrict HTTP hook URLs:**

140* WebFetch deny rules block network domains445

446Limit which URLs HTTP hooks can target. Supports `*` as a wildcard for matching. When the array is defined, HTTP hooks targeting non-matching URLs are silently blocked.

447

448```json theme={null}

449{

450 "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]

451}

452```

453

454**Restrict HTTP hook environment variables:**

455

456Limit which environment variable names HTTP hooks can interpolate into header values. Each hook's effective `allowedEnvVars` is the intersection of its own list and this setting.

457

458```json theme={null}

459{

460 "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]

461}

462```

141 463

142### Settings precedence464### Settings precedence

143 465

144Settings are applied in order of precedence (highest to lowest):466Settings apply in order of precedence. From highest to lowest:

145 467

1461. **Enterprise managed policies** (`managed-settings.json`)4681. **Managed settings** ([server-managed](/en/server-managed-settings), [MDM/OS-level policies](#configuration-scopes), or [managed settings](/en/settings#settings-files))

147 * Deployed by IT/DevOps469 * Policies deployed by IT through server delivery, MDM configuration profiles, registry policies, or managed settings files

148 * Cannot be overridden470 * Cannot be overridden by any other level, including command line arguments

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

149 472

1502. **Command line arguments**4732. **Command line arguments**

151 * Temporary overrides for a specific session474 * Temporary overrides for a specific session

1595. **User settings** (`~/.claude/settings.json`)4825. **User settings** (`~/.claude/settings.json`)

160 * Personal global settings483 * Personal global settings

161 484

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

486

487For 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.

488

489<Note>

490 **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.

491</Note>

492

493### Verify active settings

494

495Run `/status` inside Claude Code to see which settings sources are active and where they come from. The output shows each configuration layer (managed, user, project) along with its origin, such as `Enterprise managed settings (remote)`, `Enterprise managed settings (plist)`, `Enterprise managed settings (HKLM)`, `Enterprise managed settings (HKCU)`, or `Enterprise managed settings (file)`. If a settings file contains errors, `/status` reports the issue so you can fix it.

163 496

164### Key points about the configuration system497### Key points about the configuration system

165 498

166* **Memory files (CLAUDE.md)**: Contain instructions and context that Claude loads at startup499* **Memory files (`CLAUDE.md`)**: Contain instructions and context that Claude loads at startup

167* **Settings files (JSON)**: Configure permissions, environment variables, and tool behavior500* **Settings files (JSON)**: Configure permissions, environment variables, and tool behavior

168* **Slash commands**: Custom commands that can be invoked during a session with `/command-name`501* **Skills**: Custom prompts that can be invoked with `/skill-name` or loaded by Claude automatically

169* **MCP servers**: Extend Claude Code with additional tools and integrations502* **MCP servers**: Extend Claude Code with additional tools and integrations

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

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

172 505

173### System prompt availability506### System prompt

174 507

175<Note>508Claude Code's internal system prompt is not published. To add custom instructions, use `CLAUDE.md` files or the `--append-system-prompt` flag.

176 Unlike for claude.ai, we do not publish Claude Code's internal system prompt on this website. Use CLAUDE.md files or `--append-system-prompt` to add custom instructions to Claude Code's behavior.

177</Note>

178 509

179### Excluding sensitive files510### Excluding sensitive files

180 511

181To prevent Claude Code from accessing files containing sensitive information (e.g., API keys, secrets, environment files), use the `permissions.deny` setting in your `.claude/settings.json` file:512To prevent Claude Code from accessing files containing sensitive information like API keys, secrets, and environment files, use the `permissions.deny` setting in your `.claude/settings.json` file:

182 513

183```json theme={null}514```json theme={null}

184{515{

194}525}

195```526```

196 527

197This replaces the deprecated `ignorePatterns` configuration. Files matching these patterns will be completely invisible to Claude Code, preventing any accidental exposure of sensitive data.528This replaces the deprecated `ignorePatterns` configuration. Files matching these patterns are excluded from file discovery and search results, and read operations on these files are denied.

198 529

199## Subagent configuration530## Subagent configuration

200 531

203* **User subagents**: `~/.claude/agents/` - Available across all your projects534* **User subagents**: `~/.claude/agents/` - Available across all your projects

204* **Project subagents**: `.claude/agents/` - Specific to your project and can be shared with your team535* **Project subagents**: `.claude/agents/` - Specific to your project and can be shared with your team

205 536

206Subagent files define specialized AI assistants with custom prompts and tool permissions. Learn more about creating and using subagents in the [subagents documentation](/en/docs/claude-code/sub-agents).537Subagent files define specialized AI assistants with custom prompts and tool permissions. Learn more about creating and using subagents in the [subagents documentation](/en/sub-agents).

207 538

208## Plugin configuration539## Plugin configuration

209 540

210Claude Code supports a plugin system that lets you extend functionality with custom commands, agents, hooks, and MCP servers. Plugins are distributed through marketplaces and can be configured at both user and repository levels.541Claude Code supports a plugin system that lets you extend functionality with skills, agents, hooks, and MCP servers. Plugins are distributed through marketplaces and can be configured at both user and repository levels.

211 542

212### Plugin settings543### Plugin settings

213 544

216```json theme={null}547```json theme={null}

217{548{

218 "enabledPlugins": {549 "enabledPlugins": {

219 "formatter@company-tools": true,550 "formatter@acme-tools": true,

220 "deployer@company-tools": true,551 "deployer@acme-tools": true,

221 "analyzer@security-plugins": false552 "analyzer@security-plugins": false

222 },553 },

223 "extraKnownMarketplaces": {554 "extraKnownMarketplaces": {

224 "company-tools": {555 "acme-tools": {

225 "source": "github",556 "source": "github",

226 "repo": "company/claude-plugins"557 "repo": "acme-corp/claude-plugins"

227 }558 }

228 }559 }

229}560}

238* **User settings** (`~/.claude/settings.json`): Personal plugin preferences569* **User settings** (`~/.claude/settings.json`): Personal plugin preferences

239* **Project settings** (`.claude/settings.json`): Project-specific plugins shared with team570* **Project settings** (`.claude/settings.json`): Project-specific plugins shared with team

240* **Local settings** (`.claude/settings.local.json`): Per-machine overrides (not committed)571* **Local settings** (`.claude/settings.local.json`): Per-machine overrides (not committed)

572* **Managed settings** (`managed-settings.json`): Organization-wide policy overrides that block installation at all scopes and hide the plugin from the marketplace

241 573

242**Example**:574**Example**:

243 575

267```json theme={null}599```json theme={null}

268{600{

269 "extraKnownMarketplaces": {601 "extraKnownMarketplaces": {

270 "company-tools": {602 "acme-tools": {

271 "source": {603 "source": {

272 "source": "github",604 "source": "github",

273 "repo": "company-org/claude-plugins"605 "repo": "acme-corp/claude-plugins"

274 }606 }

275 },607 },

276 "security-plugins": {608 "security-plugins": {

277 "source": {609 "source": {

278 "source": "git",610 "source": "git",

279 "url": "https://git.company.com/security/plugins.git"611 "url": "https://git.example.com/security/plugins.git"

280 }612 }

281 }613 }

282 }614 }

288* `github`: GitHub repository (uses `repo`)620* `github`: GitHub repository (uses `repo`)

289* `git`: Any git URL (uses `url`)621* `git`: Any git URL (uses `url`)

290* `directory`: Local filesystem path (uses `path`, for development only)622* `directory`: Local filesystem path (uses `path`, for development only)

623* `hostPattern`: regex pattern to match marketplace hosts (uses `hostPattern`)

624* `settings`: inline marketplace declared directly in settings.json without a separate hosted repository (uses `name` and `plugins`)

625

626Use `source: 'settings'` to declare a small set of plugins inline without setting up a hosted marketplace repository. Plugins listed here must reference external sources such as GitHub or npm. You still need to enable each plugin separately in `enabledPlugins`.

627

628```json theme={null}

629{

630 "extraKnownMarketplaces": {

631 "team-tools": {

632 "source": {

633 "source": "settings",

634 "name": "team-tools",

635 "plugins": [

636 {

637 "name": "code-formatter",

638 "source": {

639 "source": "github",

640 "repo": "acme-corp/code-formatter"

641 }

642 }

643 ]

644 }

645 }

646 }

647}

648```

649

650#### `strictKnownMarketplaces`

651

652**Managed settings only**: Controls which plugin marketplaces users are allowed to add and install plugins from. This setting can only be configured in [managed settings](/en/settings#settings-files) and provides administrators with strict control over marketplace sources.

653

654**Managed settings file locations**:

655

656* **macOS**: `/Library/Application Support/ClaudeCode/managed-settings.json`

657* **Linux and WSL**: `/etc/claude-code/managed-settings.json`

658* **Windows**: `C:\Program Files\ClaudeCode\managed-settings.json`

659

660**Key characteristics**:

661

662* Only available in managed settings (`managed-settings.json`)

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

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

665* Uses exact matching for source specifications (including `ref`, `path` for git sources), except `hostPattern`, which uses regex matching

666

667**Allowlist behavior**:

668

669* `undefined` (default): No restrictions - users can add any marketplace

670* Empty array `[]`: Complete lockdown - users cannot add any new marketplaces

671* List of sources: Users can only add marketplaces that match exactly

672

673**All supported source types**:

674

675The allowlist supports multiple marketplace source types. Most sources use exact matching, while `hostPattern` uses regex matching against the marketplace host.

676

6771. **GitHub repositories**:

678

679```json theme={null}

680{ "source": "github", "repo": "acme-corp/approved-plugins" }

681{ "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }

682{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }

683```

684

685Fields: `repo` (required), `ref` (optional: branch/tag/SHA), `path` (optional: subdirectory)

686

6872. **Git repositories**:

688

689```json theme={null}

690{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }

691{ "source": "git", "url": "https://bitbucket.org/acme-corp/plugins.git", "ref": "production" }

692{ "source": "git", "url": "ssh://git@git.example.com/plugins.git", "ref": "v3.1", "path": "approved" }

693```

694

695Fields: `url` (required), `ref` (optional: branch/tag/SHA), `path` (optional: subdirectory)

696

6973. **URL-based marketplaces**:

698

699```json theme={null}

700{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }

701{ "source": "url", "url": "https://cdn.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }

702```

703

704Fields: `url` (required), `headers` (optional: HTTP headers for authenticated access)

705

706<Note>

707 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, or git URLs) rather than relative paths. For plugins with relative paths, use a Git-based marketplace instead. See [Troubleshooting](/en/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces) for details.

708</Note>

709

7104. **NPM packages**:

711

712```json theme={null}

713{ "source": "npm", "package": "@acme-corp/claude-plugins" }

714{ "source": "npm", "package": "@acme-corp/approved-marketplace" }

715```

716

717Fields: `package` (required, supports scoped packages)

718

7195. **File paths**:

720

721```json theme={null}

722{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }

723{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }

724```

725

726Fields: `path` (required: absolute path to marketplace.json file)

727

7286. **Directory paths**:

729

730```json theme={null}

731{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }

732{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }

733```

734

735Fields: `path` (required: absolute path to directory containing `.claude-plugin/marketplace.json`)

736

7377. **Host pattern matching**:

738

739```json theme={null}

740{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }

741{ "source": "hostPattern", "hostPattern": "^gitlab\\.internal\\.example\\.com$" }

742```

743

744Fields: `hostPattern` (required: regex pattern to match against the marketplace host)

745

746Use host pattern matching when you want to allow all marketplaces from a specific host without enumerating each repository individually. This is useful for organizations with internal GitHub Enterprise or GitLab servers where developers create their own marketplaces.

747

748Host extraction by source type:

749

750* `github`: always matches against `github.com`

751* `git`: extracts hostname from the URL (supports both HTTPS and SSH formats)

752* `url`: extracts hostname from the URL

753* `npm`, `file`, `directory`: not supported for host pattern matching

754

755**Configuration examples**:

756

757Example: allow specific marketplaces only:

758

759```json theme={null}

760{

761 "strictKnownMarketplaces": [

762 {

763 "source": "github",

764 "repo": "acme-corp/approved-plugins"

765 },

766 {

767 "source": "github",

768 "repo": "acme-corp/security-tools",

769 "ref": "v2.0"

770 },

771 {

772 "source": "url",

773 "url": "https://plugins.example.com/marketplace.json"

774 },

775 {

776 "source": "npm",

777 "package": "@acme-corp/compliance-plugins"

778 }

779 ]

780}

781```

782

783Example - Disable all marketplace additions:

784

785```json theme={null}

786{

787 "strictKnownMarketplaces": []

788}

789```

790

791Example: allow all marketplaces from an internal git server:

792

793```json theme={null}

794{

795 "strictKnownMarketplaces": [

796 {

797 "source": "hostPattern",

798 "hostPattern": "^github\\.example\\.com$"

799 }

800 ]

801}

802```

803

804**Exact matching requirements**:

805

806Marketplace sources must match **exactly** for a user's addition to be allowed. For git-based sources (`github` and `git`), this includes all optional fields:

807

808* The `repo` or `url` must match exactly

809* The `ref` field must match exactly (or both be undefined)

810* The `path` field must match exactly (or both be undefined)

811

812Examples of sources that **do NOT match**:

813

814```json theme={null}

815// These are DIFFERENT sources:

816{ "source": "github", "repo": "acme-corp/plugins" }

817{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }

818

819// These are also DIFFERENT:

820{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }

821{ "source": "github", "repo": "acme-corp/plugins" }

822```

823

824**Comparison with `extraKnownMarketplaces`**:

825

826| Aspect | `strictKnownMarketplaces` | `extraKnownMarketplaces` |

827| --------------------- | ------------------------------------ | ------------------------------------ |

828| **Purpose** | Organizational policy enforcement | Team convenience |

829| **Settings file** | `managed-settings.json` only | Any settings file |

830| **Behavior** | Blocks non-allowlisted additions | Auto-installs missing marketplaces |

831| **When enforced** | Before network/filesystem operations | After user trust prompt |

832| **Can be overridden** | No (highest precedence) | Yes (by higher precedence settings) |

833| **Source format** | Direct source object | Named marketplace with nested source |

834| **Use case** | Compliance, security restrictions | Onboarding, standardization |

835

836**Format difference**:

837

838`strictKnownMarketplaces` uses direct source objects:

839

840```json theme={null}

841{

842 "strictKnownMarketplaces": [

843 { "source": "github", "repo": "acme-corp/plugins" }

844 ]

845}

846```

847

848`extraKnownMarketplaces` requires named marketplaces:

849

850```json theme={null}

851{

852 "extraKnownMarketplaces": {

853 "acme-tools": {

854 "source": { "source": "github", "repo": "acme-corp/plugins" }

855 }

856 }

857}

858```

859

860**Using both together**:

861

862`strictKnownMarketplaces` is a policy gate: it controls what users may add but does not register any marketplaces. To both restrict and pre-register a marketplace for all users, set both in `managed-settings.json`:

863

864```json theme={null}

865{

866 "strictKnownMarketplaces": [

867 { "source": "github", "repo": "acme-corp/plugins" }

868 ],

869 "extraKnownMarketplaces": {

870 "acme-tools": {

871 "source": { "source": "github", "repo": "acme-corp/plugins" }

872 }

873 }

874}

875```

876

877With only `strictKnownMarketplaces` set, users can still add the allowed marketplace manually via `/plugin marketplace add`, but it is not available automatically.

878

879**Important notes**:

880

881* Restrictions are checked BEFORE any network requests or filesystem operations

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

883* The restriction is enforced on marketplace add and on plugin install, update, refresh, and auto-update. A marketplace added before the policy was set cannot be used to install or update plugins once its source no longer matches the allowlist

884* Managed settings have the highest precedence and cannot be overridden

885

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

291 887

292### Managing plugins888### Managing plugins

293 889

296* Browse available plugins from marketplaces892* Browse available plugins from marketplaces

297* Install/uninstall plugins893* Install/uninstall plugins

298* Enable/disable plugins894* Enable/disable plugins

299* View plugin details (commands, agents, hooks provided)895* View plugin details (skills, agents, hooks provided)

300* Add/remove marketplaces896* Add/remove marketplaces

301 897

302Learn more about the plugin system in the [plugins documentation](/en/docs/claude-code/plugins).898Learn more about the plugin system in the [plugins documentation](/en/plugins).

303 899

304## Environment variables900## Environment variables

305 901

306Claude Code supports the following environment variables to control its behavior:902Environment variables let you control Claude Code behavior without editing settings files. Any variable can also be configured in [`settings.json`](#available-settings) under the `env` key to apply it to every session or roll it out to your team.

~~307~~

308<Note>

309 All environment variables can also be configured in [`settings.json`](#available-settings). This is useful as a way to automatically set environment variables for each session, or to roll out a set of environment variables for your whole team or organization.

310</Note>

311 903

312| Variable | Purpose |904See the [environment variables reference](/en/env-vars) for the full list.

313| :----------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

314| `ANTHROPIC_API_KEY` | API key sent as `X-Api-Key` header, typically for the Claude SDK (for interactive usage, run `/login`) |

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

316| `ANTHROPIC_CUSTOM_HEADERS` | Custom headers you want to add to the request (in `Name: Value` format) |

317| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | See [Model configuration](/en/docs/claude-code/model-config#environment-variables) |

318| `ANTHROPIC_DEFAULT_OPUS_MODEL` | See [Model configuration](/en/docs/claude-code/model-config#environment-variables) |

319| `ANTHROPIC_DEFAULT_SONNET_MODEL` | See [Model configuration](/en/docs/claude-code/model-config#environment-variables) |

320| `ANTHROPIC_MODEL` | Name of the model setting to use (see [Model Configuration](/en/docs/claude-code/model-config#environment-variables)) |

321| `ANTHROPIC_SMALL_FAST_MODEL` | \[DEPRECATED] Name of [Haiku-class model for background tasks](/en/docs/claude-code/costs) |

322| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | Override AWS region for the Haiku-class model when using Bedrock |

323| `AWS_BEARER_TOKEN_BEDROCK` | Bedrock API key for authentication (see [Bedrock API keys](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)) |

324| `BASH_DEFAULT_TIMEOUT_MS` | Default timeout for long-running bash commands |

325| `BASH_MAX_OUTPUT_LENGTH` | Maximum number of characters in bash outputs before they are middle-truncated |

326| `BASH_MAX_TIMEOUT_MS` | Maximum timeout the model can set for long-running bash commands |

327| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | Return to the original working directory after each Bash command |

328| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | Interval in milliseconds at which credentials should be refreshed (when using `apiKeyHelper`) |

329| `CLAUDE_CODE_CLIENT_CERT` | Path to client certificate file for mTLS authentication |

330| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | Passphrase for encrypted CLAUDE\_CODE\_CLIENT\_KEY (optional) |

331| `CLAUDE_CODE_CLIENT_KEY` | Path to client private key file for mTLS authentication |

332| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Equivalent of setting `DISABLE_AUTOUPDATER`, `DISABLE_BUG_COMMAND`, `DISABLE_ERROR_REPORTING`, and `DISABLE_TELEMETRY` |

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

334| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | Skip auto-installation of IDE extensions |

335| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Set the maximum number of output tokens for most requests |

336| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Skip AWS authentication for Bedrock (e.g. when using an LLM gateway) |

337| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Skip Google authentication for Vertex (e.g. when using an LLM gateway) |

338| `CLAUDE_CODE_SUBAGENT_MODEL` | See [Model configuration](/en/docs/claude-code/model-config) |

339| `CLAUDE_CODE_USE_BEDROCK` | Use [Bedrock](/en/docs/claude-code/amazon-bedrock) |

340| `CLAUDE_CODE_USE_VERTEX` | Use [Vertex](/en/docs/claude-code/google-vertex-ai) |

341| `DISABLE_AUTOUPDATER` | Set to `1` to disable automatic updates. This takes precedence over the `autoUpdates` configuration setting. |

342| `DISABLE_BUG_COMMAND` | Set to `1` to disable the `/bug` command |

343| `DISABLE_COST_WARNINGS` | Set to `1` to disable cost warning messages |

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

345| `DISABLE_NON_ESSENTIAL_MODEL_CALLS` | Set to `1` to disable model calls for non-critical paths like flavor text |

346| `DISABLE_PROMPT_CACHING` | Set to `1` to disable prompt caching for all models (takes precedence over per-model settings) |

347| `DISABLE_PROMPT_CACHING_HAIKU` | Set to `1` to disable prompt caching for Haiku models |

348| `DISABLE_PROMPT_CACHING_OPUS` | Set to `1` to disable prompt caching for Opus models |

349| `DISABLE_PROMPT_CACHING_SONNET` | Set to `1` to disable prompt caching for Sonnet models |

350| `DISABLE_TELEMETRY` | Set to `1` to opt out of Statsig telemetry (note that Statsig events do not include user data like code, file paths, or bash commands) |

351| `HTTP_PROXY` | Specify HTTP proxy server for network connections |

352| `HTTPS_PROXY` | Specify HTTPS proxy server for network connections |

353| `MAX_MCP_OUTPUT_TOKENS` | Maximum number of tokens allowed in MCP tool responses. Claude Code displays a warning when output exceeds 10,000 tokens (default: 25000) |

354| `MAX_THINKING_TOKENS` | Enable [extended thinking](/en/docs/build-with-claude/extended-thinking) and set the token budget for the thinking process. Extended thinking improves performance on complex reasoning and coding tasks but impacts [prompt caching efficiency](/en/docs/build-with-claude/prompt-caching#caching-with-thinking-blocks). Disabled by default. |

355| `MCP_TIMEOUT` | Timeout in milliseconds for MCP server startup |

356| `MCP_TOOL_TIMEOUT` | Timeout in milliseconds for MCP tool execution |

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

358| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Maximum number of characters for slash command metadata shown to [SlashCommand tool](/en/docs/claude-code/slash-commands#slashcommand-tool) (default: 15000) |

359| `USE_BUILTIN_RIPGREP` | Set to `0` to use system-installed `rg` intead of `rg` included with Claude Code |

360| `VERTEX_REGION_CLAUDE_3_5_HAIKU` | Override region for Claude 3.5 Haiku when using Vertex AI |

361| `VERTEX_REGION_CLAUDE_3_7_SONNET` | Override region for Claude 3.7 Sonnet when using Vertex AI |

362| `VERTEX_REGION_CLAUDE_4_0_OPUS` | Override region for Claude 4.0 Opus when using Vertex AI |

363| `VERTEX_REGION_CLAUDE_4_0_SONNET` | Override region for Claude 4.0 Sonnet when using Vertex AI |

364| `VERTEX_REGION_CLAUDE_4_1_OPUS` | Override region for Claude 4.1 Opus when using Vertex AI |

365 905

366## Tools available to Claude906## Tools available to Claude

367 907

368Claude Code has access to a set of powerful tools that help it understand and modify your codebase:908Claude Code has access to a set of tools for reading, editing, searching, running commands, and orchestrating subagents. Tool names are the exact strings you use in permission rules and hook matchers.

~~369~~

370| Tool | Description | Permission Required |

371| :--------------- | :----------------------------------------------------------------------------------- | :------------------ |

372| **Bash** | Executes shell commands in your environment | Yes |

373| **Edit** | Makes targeted edits to specific files | Yes |

374| **Glob** | Finds files based on pattern matching | No |

375| **Grep** | Searches for patterns in file contents | No |

376| **NotebookEdit** | Modifies Jupyter notebook cells | Yes |

377| **NotebookRead** | Reads and displays Jupyter notebook contents | No |

378| **Read** | Reads the contents of files | No |

379| **SlashCommand** | Runs a [custom slash command](/en/docs/claude-code/slash-commands#slashcommand-tool) | Yes |

380| **Task** | Runs a sub-agent to handle complex, multi-step tasks | No |

381| **TodoWrite** | Creates and manages structured task lists | No |

382| **WebFetch** | Fetches content from a specified URL | Yes |

383| **WebSearch** | Performs web searches with domain filtering | Yes |

384| **Write** | Creates or overwrites files | Yes |

~~385~~

386Permission rules can be configured using `/allowed-tools` or in [permission settings](/en/docs/claude-code/settings#available-settings). Also see [Tool-specific permission rules](/en/docs/claude-code/iam#tool-specific-permission-rules).

~~387~~

388### Extending tools with hooks

~~389~~

390You can run custom commands before or after any tool executes using

391[Claude Code hooks](/en/docs/claude-code/hooks-guide).

392 909

393For example, you could automatically run a Python formatter after Claude910See the [tools reference](/en/tools-reference) for the full list and Bash tool behavior details.

394modifies Python files, or prevent modifications to production configuration

395files by blocking Write operations to certain paths.

396 911

397## See also912## See also

398 913

399* [Identity and Access Management](/en/docs/claude-code/iam#configuring-permissions) - Learn about Claude Code's permission system914* [Permissions](/en/permissions): permission system, rule syntax, tool-specific patterns, and managed policies

400* [IAM and access control](/en/docs/claude-code/iam#enterprise-managed-policy-settings) - Enterprise policy management915* [Authentication](/en/authentication): set up user access to Claude Code

401* [Troubleshooting](/en/docs/claude-code/troubleshooting#auto-updater-issues) - Solutions for common configuration issues916* [Debug your configuration](/en/debug-your-config): diagnose why a setting, hook, or MCP server isn't taking effect

917* [Troubleshoot installation and login](/en/troubleshoot-install): installation, authentication, and platform issues

settings.md Claude Code Docs, 2025-10-31 00:04 UTC → 2026-05-02 04:05 UTC