# Claude Code sessions erase after 30 days by default

> Source: <https://code.claude.com/docs/en/settings>
> Published: 2026-06-17 15:05:48+00:00

`/config`

command when using the interactive REPL, which opens a tabbed Settings interface where you can view status information and modify configuration options.
## Configuration scopes

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

### Available scopes

| Scope | Location | Who it affects | Shared with team? |
|---|---|---|---|
Managed | Server-managed settings, plist / registry, or system-level `managed-settings.json` | All users on the machine | Yes (deployed by IT) |
User | `~/.claude/` directory | You, across all projects | No |
Project | `.claude/` in repository | All collaborators on this repository | Yes (committed to git) |
Local | `.claude/settings.local.json` | You, in this repository only | No (gitignored when Claude Code creates it) |

### When to use each scope

**Managed scope** is for:

- Security policies that must be enforced organization-wide
- Compliance requirements that can’t be overridden
- Standardized configurations deployed by IT/DevOps

**User scope** is best for:

- Personal preferences you want everywhere (themes, editor settings)
- Tools and plugins you use across all projects
- API keys and authentication (stored securely)

**Project scope** is best for:

- Team-shared settings (permissions, hooks, MCP servers)
- Plugins the whole team should have
- Standardizing tooling across collaborators

**Local scope** is best for:

- Personal overrides for a specific project
- Testing configurations before sharing with the team
- Machine-specific settings that won’t work for others

### How scopes interact

When the same setting appears in multiple scopes, Claude Code applies them in priority order:**Managed**(highest) - can’t be overridden by anything** Command line arguments**- temporary session overrides** Local**- overrides project and user settings** Project**- overrides user settings** User**(lowest) - applies when nothing else specifies the setting

`spinnerTipsEnabled`

to `true`

and project settings set it to `false`

, the project value applies. Permission rules behave differently because they merge across scopes rather than override. See [Settings precedence](#settings-precedence).

### What uses scopes

Scopes apply to many Claude Code features:| Feature | User location | Project location | Local location |
|---|---|---|---|
Settings | `~/.claude/settings.json` | `.claude/settings.json` | `.claude/settings.local.json` |
Subagents | `~/.claude/agents/` | `.claude/agents/` | None |
MCP servers | `~/.claude.json` | `.mcp.json` | `~/.claude.json` (per-project) |
Plugins | `~/.claude/settings.json` | `.claude/settings.json` | `.claude/settings.local.json` |
CLAUDE.md | `~/.claude/CLAUDE.md` | `CLAUDE.md` or `.claude/CLAUDE.md` | `CLAUDE.local.md` |

`~/.claude`

resolve to `%USERPROFILE%\.claude`

.
## Settings files

The`settings.json`

file is the official mechanism for configuring Claude
Code through hierarchical settings:
-
**User settings** are defined in`~/.claude/settings.json`

and apply to all projects. -
**Project settings** are saved in your project directory:`.claude/settings.json`

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

for settings that are not checked in, useful for personal preferences and experimentation. When Claude Code creates`.claude/settings.local.json`

, it configures git to ignore the file. If you create the file yourself, add it to your gitignore manually.

-
**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:-
**Server-managed settings**: delivered from Anthropic’s servers via the Claude.ai admin console. See[server-managed settings](/docs/en/server-managed-settings). -
**MDM/OS-level policies**: delivered through native device management on macOS and Windows:- 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. - 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) - Windows (user-level):
`HKCU\SOFTWARE\Policies\ClaudeCode`

(lowest policy priority, only used when no admin-level source exists)

- macOS:
-
**File-based**:`managed-settings.json`

and`managed-mcp.json`

deployed to system directories:- macOS:
`/Library/Application Support/ClaudeCode/`

- Linux and WSL:
`/etc/claude-code/`

- Windows:
`C:\Program Files\ClaudeCode\`

`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. 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. Use numeric prefixes to control merge order, for example`10-telemetry.json`

and`20-security.json`

. - macOS:

[managed settings](/docs/en/permissions#managed-only-settings)and[Managed MCP configuration](/docs/en/managed-mcp)for details. 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.Managed deployments can also restrict**plugin marketplace additions** using`strictKnownMarketplaces`

. For more information, see[Managed marketplace restrictions](/docs/en/plugin-marketplaces#managed-marketplace-restrictions). -
-
**Other configuration** is stored in`~/.claude.json`

. This file contains your OAuth session,[MCP server](/docs/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`

.

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

Example settings.json

`$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.
The 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.
### When edits take effect

Claude Code watches your settings files and reloads them when they change, so edits to most keys apply to the running session without a restart. This includes`permissions`

, `hooks`

, and credential helpers like `apiKeyHelper`

. The reload covers user, project, local, and managed settings, and the [fires for each detected change. A few keys are read once at session start and apply on the next restart instead:](/docs/en/hooks#configchange)

`ConfigChange`

hook`model`

: useto switch mid-session`/model`

: part of the system prompt, which is rebuilt on`outputStyle`

`/clear`

or restart

### Invalid entries in managed settings

Managed settings parse tolerantly. When a managed configuration contains an entry that fails schema validation, Claude Code strips that entry, records a warning, and enforces every remaining valid policy. A single typo cannot disable the rest of your organization’s policy. This behavior is consistent across all three delivery mechanisms:[server-managed settings](/docs/en/server-managed-settings), plist and registry policies deployed through MDM, and

`managed-settings.json`

files. Requires Claude Code v2.1.169 or later.
Security-enforcement fields are handled per field instead of being stripped wholesale when they are present but invalid:
| Field | Behavior when present but invalid |
|---|---|
`allowedMcpServers` | Enforced as an empty allowlist, so no MCP servers are admitted until the value is fixed. An individual invalid entry is stripped and the valid subset is enforced. |
`allowManagedMcpServersOnly` | Treated as `true` . |
`availableModels` | Enforced as an empty allowlist, so only the Default model is available until the value is fixed. An individual non-string entry is stripped and the valid subset is enforced. Applies in v2.1.175 and later. |
`enforceAvailableModels` | Treated as `true` . Applies in v2.1.175 and later. |
`forceLoginOrgUUID` | No organization is permitted to log in until the value is fixed. |
`deniedMcpServers` | An individual invalid entry is stripped and the valid subset is enforced. A wholly invalid value is dropped with a warning, since denying every server would block servers the policy never named. |

`requiredMinimumVersion`

and `requiredMaximumVersion`

fail open by design: an invalid value is stripped rather than enforced, so a bad policy push cannot prevent Claude Code from starting.
Validation errors surface in three places:
- Interactive sessions show a dialog at startup listing the invalid entries.
- Headless runs with
`-p`

print a summary to stderr. lists each invalid entry with its source and field.`claude doctor`

`claude doctor`

on a test machine before deploying them fleet-wide.
This tolerance applies only to managed settings. User, project, and local settings files remain strict: a file that fails validation is rejected as a whole and reported.
### Available settings

`settings.json`

supports a number of options:
| Key | Description | Example |
|---|---|---|
`advisorModel` | Model for the server-side
`"opus"` , `"sonnet"` , or `"fable"` (v2.1.170+), or a full model ID. Written automatically when you run `/advisor` . Unset to disable the advisor. Requires Claude Code v2.1.98 or later |

`"opus"`

`agent`

`claude agents`

. Applies that subagent’s system prompt, tool restrictions, and model. See [Invoke subagents explicitly](/docs/en/sub-agents#invoke-subagents-explicitly)`"code-reviewer"`

`agentPushNotifEnabled`

[Remote Control](/docs/en/remote-control)is connected, allow Claude to send proactive push notifications to your phone, for example when a long task finishes. Default:`false`

. Appears in `/config`

as **Push when Claude decides**. See[Mobile push notifications](/docs/en/remote-control#mobile-push-notifications). Requires Claude Code v2.1.119 or later`true`

`allowAllClaudeAiMcps`

`managed-mcp.json`

, which otherwise takes exclusive control and suppresses them. See [Managed MCP configuration](/docs/en/managed-mcp)`true`

`allowedChannelPlugins`

`channelsEnabled: true`

. See [Restrict which channel plugins can run](/docs/en/channels#restrict-which-channel-plugins-can-run)`[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]`

`allowedHttpHookUrls`

`*`

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

`allowedMcpServers`

[Managed MCP configuration](/docs/en/managed-mcp)`[{ "serverName": "github" }]`

`allowManagedHooksOnly`

`enabledPlugins`

are loaded. User, project, and all other plugin hooks are blocked. See [Hook configuration](#hook-configuration)`true`

`allowManagedMcpServersOnly`

`allowedMcpServers`

from managed settings are respected. `deniedMcpServers`

still merges from all sources. Users can still add MCP servers, but only the admin-defined allowlist applies. See [Managed MCP configuration](/docs/en/managed-mcp)`true`

`allowManagedPermissionRulesOnly`

`allow`

, `ask`

, or `deny`

permission rules. Only rules in managed settings apply. See [Managed-only settings](/docs/en/permissions#managed-only-settings)`true`

`alwaysThinkingEnabled`

[extended thinking](/docs/en/model-config#extended-thinking)by default for all sessions. Typically configured via the`/config`

command rather than editing directly. To force thinking off regardless of this setting, set [in](/docs/en/env-vars)`MAX_THINKING_TOKENS=0`

`env`

, which disables thinking on the Anthropic API except on Fable 5, which cannot have thinking turned off. On [third-party providers](/docs/en/third-party-integrations)this omits the`thinking`

parameter instead, and adaptive-reasoning models may still think`true`

`apiKeyHelper`

`/bin/sh`

, to generate an auth value. This value will be sent as `X-Api-Key`

and `Authorization: Bearer`

headers for model requests. Set the refresh interval with `CLAUDE_CODE_API_KEY_HELPER_TTL_MS`

`/bin/generate_temp_api_key.sh`

`attribution`

[Attribution settings](#attribution-settings)`{"commit": "🤖 Generated with Claude Code", "pr": ""}`

`autoCompactEnabled`

`true`

. Appears in `/config`

as **Auto-compact**. To disable via environment variable, set[in](/docs/en/env-vars)`DISABLE_AUTO_COMPACT`

`env`

`false`

`autoMemoryDirectory`

[auto memory](/docs/en/memory#storage-location)storage. Accepts an absolute path or a`~/`

-prefixed path. From project or local settings, this is honored only after you accept the workspace trust dialog, since a cloned repository can supply this file`"~/my-memory-dir"`

`autoMemoryEnabled`

[auto memory](/docs/en/memory#enable-or-disable-auto-memory). When`false`

, Claude does not read from or write to the auto memory directory. Default: `true`

. You can also toggle this with `/memory`

during a session. To disable via environment variable, set [in](/docs/en/env-vars)`CLAUDE_CODE_DISABLE_AUTO_MEMORY`

`env`

`false`

`autoMode`

[auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode)classifier blocks and allows. Contains`environment`

, `allow`

, `soft_deny`

, and `hard_deny`

arrays of prose rules. Include the literal string `"$defaults"`

in an array to inherit the built-in rules at that position. See [Configure auto mode](/docs/en/auto-mode-config). Not read from shared project settings`{"soft_deny": ["$defaults", "Never run terraform apply"]}`

`autoScrollEnabled`

[fullscreen rendering](/docs/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`

`autoUpdatesChannel`

`"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. To disable auto-updates entirely, set [in](/docs/en/setup#disable-auto-updates)`DISABLE_AUTOUPDATER`

`env`

`"stable"`

`availableModels`

[subagents](/docs/en/sub-agents), and the[advisor](/docs/en/advisor). See[Restrict model selection](/docs/en/model-config#restrict-model-selection). See`enforceAvailableModels`

to also constrain Default`["sonnet", "haiku"]`

`awaySummaryEnabled`

`false`

or turn off Session recap in `/config`

to disable. Same as `CLAUDE_CODE_ENABLE_AWAY_SUMMARY`

`true`

`awsAuthRefresh`

`.aws`

directory (see [advanced credential configuration](/docs/en/amazon-bedrock#advanced-credential-configuration))`aws sso login --profile myprofile`

`awsCredentialExport`

[advanced credential configuration](/docs/en/amazon-bedrock#advanced-credential-configuration))`/bin/generate_aws_grant.sh`

`blockedMarketplaces`

[Managed marketplace restrictions](/docs/en/plugin-marketplaces#managed-marketplace-restrictions)`[{ "source": "github", "repo": "untrusted/plugins" }]`

`channelsEnabled`

[channels](/docs/en/channels)for the organization. On claude.ai Team and Enterprise plans, channels are blocked when this is unset or`false`

. For [Anthropic Console](/docs/en/authentication#claude-console-authentication)accounts using API key authentication, channels are allowed by default unless your organization deploys managed settings, in which case this key must be set to`true`

`true`

`claudeMd`

[organization-wide CLAUDE.md](/docs/en/memory#deploy-organization-wide-claude-md)`"Always run make lint before committing."`

`claudeMdExcludes`

`CLAUDE.md`

files to skip when loading [memory](/docs/en/memory). Patterns match against absolute file paths. Only applies to user, project, and local memory; managed policy files cannot be excluded`["**/vendor/**/CLAUDE.md"]`

`cleanupPeriodDays`

`0`

is rejected with a validation error. Also controls the age cutoff for automatic removal of [orphaned subagent worktrees](/docs/en/worktrees#clean-up-worktrees)at startup. To disable transcript writes entirely, set the[environment variable, or in non-interactive mode (](/docs/en/env-vars)`CLAUDE_CODE_SKIP_PROMPT_HISTORY`

`-p`

) use the `--no-session-persistence`

flag or the `persistSession: false`

SDK option.`20`

`companyAnnouncements`

`["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]`

`defaultShell`

`!`

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](/docs/en/tools-reference#powershell-tool)`"powershell"`

`deniedMcpServers`

[Managed MCP configuration](/docs/en/managed-mcp)`[{ "serverName": "filesystem" }]`

`disableAgentView`

`true`

to turn off [background agents and agent view](/docs/en/agent-view):`claude agents`

, `--bg`

, `/background`

, and the on-demand supervisor. Typically set in [managed settings](/docs/en/permissions#managed-settings). Equivalent to setting`CLAUDE_CODE_DISABLE_AGENT_VIEW`

to `1`

`true`

`disableAllHooks`

[hooks](/docs/en/hooks)and any custom[status line](/docs/en/statusline)`true`

`disableAutoMode`

`"disable"`

to prevent [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode)from being activated. Removes`auto`

from the `Shift+Tab`

cycle and rejects `--permission-mode auto`

at startup. Most useful in [managed settings](/docs/en/permissions#managed-settings)where users cannot override it`"disable"`

`disableBundledSkills`

`true`

to disable the [skills](/docs/en/skills)and workflows that ship with Claude Code: bundled skills and workflows are removed entirely, while built-in slash commands like`/init`

stay typable but are hidden from the model. Skills from plugins, `.claude/skills/`

, and `.claude/commands/`

are unaffected. Equivalent to setting `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS`

to `1`

`true`

`disableDeepLinkRegistration`

`"disable"`

to prevent Claude Code from registering the `claude-cli://`

protocol handler with the operating system on startup. [Deep links](/docs/en/deep-links)let external tools open a Claude Code session with a pre-filled prompt. Useful in environments where protocol handler registration is restricted or managed separately`"disable"`

`disabledMcpjsonServers`

`.mcp.json`

files to reject`["filesystem"]`

`disableRemoteControl`

[Remote Control](/docs/en/remote-control): blocks`claude remote-control`

, the `--remote-control`

flag, auto-start, and the in-session toggle. Typically placed in [managed settings](/docs/en/permissions#managed-settings)for per-device MDM enforcement, but works from any scope. Requires Claude Code v2.1.128 or later`true`

`disableSkillShellExecution`

`!`...``

and ````!`

blocks in [skills](/docs/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](/docs/en/permissions#managed-settings)where users cannot override it`true`

`disableWorkflows`

[dynamic workflows](/docs/en/workflows#turn-workflows-off)and the bundled workflow commands. Default:`false`

. Equivalent to setting `CLAUDE_CODE_DISABLE_WORKFLOWS`

to `1`

`true`

`editorMode`

`"normal"`

or `"vim"`

. Default: `"normal"`

. Appears in `/config`

as **Editor mode**`"vim"`

`effortLevel`

[effort level](/docs/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. `--effort`

and [override this for one session. See](/docs/en/env-vars)`CLAUDE_CODE_EFFORT_LEVEL`

[Adjust effort level](/docs/en/model-config#adjust-effort-level)for supported models`"xhigh"`

`enableAllProjectMcpServers`

`.mcp.json`

files`true`

`enabledMcpjsonServers`

`.mcp.json`

files to approve`["memory", "github"]`

`enforceAvailableModels`

`true`

and `availableModels`

is a non-empty list in managed or policy settings, the Default model is also constrained to the allowlist. See [Restrict model selection](/docs/en/model-config#restrict-model-selection)for details and the[merge behavior](/docs/en/model-config#merge-behavior)when`availableModels`

is set at multiple levels. Requires Claude Code v2.1.175 or later`true`

`env`

`NO_COLOR`

and `FORCE_COLOR`

set here are passed to subprocesses but do not change Claude Code’s own interface colors. Set those in your shell before launching `claude`

to change interface colors`{"FOO": "bar"}`

`fallbackModel`

`"default"`

expands to the default model. Chains are capped at three models; extra entries are ignored. Unlike most array settings, this key does not merge across settings files: the highest-precedence file that defines it supplies the entire chain. The [flag overrides this for one session. See](/docs/en/cli-reference#cli-flags)`--fallback-model`

[Fallback model chains](/docs/en/model-config#fallback-model-chains)`["claude-sonnet-4-6", "claude-haiku-4-5"]`

`fastModePerSessionOptIn`

`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](/docs/en/fast-mode#require-per-session-opt-in)`true`

`feedbackSurveyRate`

[session quality survey](/docs/en/data-usage#session-quality-surveys)appears when eligible. Set to`0`

to suppress entirely, or set [in](/docs/en/env-vars)`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`

`env`

. Useful when using Bedrock, Vertex, or Foundry where the default sample rate does not apply`0.05`

`fileCheckpointingEnabled`

[can restore them. Default:](/docs/en/checkpointing)`/rewind`

`true`

. Appears in `/config`

as **Rewind code (checkpoints)**. To disable via environment variable, set[in](/docs/en/env-vars)`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`

`env`

`false`

`fileSuggestion`

`@`

file autocomplete. See [File suggestion settings](#file-suggestion-settings)`{"type": "command", "command": "~/.claude/file-suggestion.sh"}`

`footerLinksRegexes`

`pattern`

, a `url`

template with `{name}`

placeholders filled from named capture groups, and an optional `label`

. Read from user, `--settings`

flag, and managed settings only. See [Footer link badges](#footer-link-badges)for URL constraints, scheme allowlist, and limits. Requires Claude Code v2.1.176 or later`[{"type": "regex", "pattern": "\\b(?<key>PROJ-\\d+)\\b", "url": "https://issues.example.com/browse/{key}", "label": "{key}"}]`

`forceLoginMethod`

`claudeai`

to restrict login to Claude.ai accounts, `console`

to restrict login to Claude Console accounts. When set in managed settings, sessions authenticated by `ANTHROPIC_API_KEY`

, `ANTHROPIC_AUTH_TOKEN`

, or `apiKeyHelper`

are blocked at startup, since neither value can be satisfied without first-party OAuth. Third-party provider sessions such as Bedrock, Vertex, and Foundry are not blocked: they authenticate against your cloud provider rather than Anthropic`claudeai`

`forceLoginOrgUUID`

`ANTHROPIC_API_KEY`

, `ANTHROPIC_AUTH_TOKEN`

, or `apiKeyHelper`

are blocked at startup since organization membership cannot be verified for them. Third-party provider sessions such as Bedrock, Vertex, and Foundry are not blocked: use your cloud IAM to restrict which cloud accounts can be used. 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"]`

`forceRemoteSettingsRefresh`

[fail-closed enforcement](/docs/en/server-managed-settings#enforce-fail-closed-startup)`true`

`gcpAuthRefresh`

[advanced credential configuration](/docs/en/google-vertex-ai#advanced-credential-configuration)`gcloud auth application-default login`

`hooks`

[hooks documentation](/docs/en/hooks)for format[hooks](/docs/en/hooks)`httpHookAllowedEnvVars`

`allowedEnvVars`

is the intersection with this list. Undefined = no restriction. Arrays merge across settings sources. See [Hook configuration](#hook-configuration)`["MY_TOKEN", "HOOK_SECRET"]`

`includeCoAuthoredBy`

**Deprecated**: Use`attribution`

instead. Whether to include the `co-authored-by Claude`

byline in git commits and pull requests (default: `true`

)`false`

`includeGitInstructions`

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

`inputNeededNotifEnabled`

[Remote Control](/docs/en/remote-control)is connected, send a push notification to your phone when a permission prompt or question is waiting for your input. Default:`false`

. Appears in `/config`

as **Push when actions required**. See[Mobile push notifications](/docs/en/remote-control#mobile-push-notifications). Requires Claude Code v2.1.119 or later`true`

`language`

`"japanese"`

, `"spanish"`

, `"french"`

). Claude will respond in this language by default. Also sets the language for [voice dictation](/docs/en/voice-dictation#change-the-dictation-language)and auto-generated session titles. As of v2.1.176, when not set, session titles match the language of your conversation`"japanese"`

`maxSkillDescriptionChars`

`description`

and `when_to_use`

text in the [skill listing](/docs/en/skills#skill-descriptions-are-cut-short)Claude sees each turn (default:`1536`

). Text longer than this is truncated. Raise to keep long descriptions intact at the cost of more context per turn; lower to fit more skills under [. Requires Claude Code v2.1.105 or later](#available-settings)`skillListingBudgetFraction`

`2048`

`minimumVersion`

`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](/docs/en/permissions#managed-settings)to pin an organization-wide minimum. For a hard floor that blocks startup entirely, see`requiredMinimumVersion`

`"2.1.100"`

`model`

`--model`

and [override this for one session](/docs/en/model-config#environment-variables)`ANTHROPIC_MODEL`

`"claude-sonnet-4-6"`

`modelOverrides`

[Override model IDs per version](/docs/en/model-config#override-model-ids-per-version)`{"claude-opus-4-6": "arn:aws:bedrock:..."}`

`otelHeadersHelper`

[. See](/docs/en/env-vars)`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`

[Dynamic headers](/docs/en/monitoring-usage#dynamic-headers)`/bin/generate_otel_headers.sh`

`outputStyle`

[output styles documentation](/docs/en/output-styles)`"Explanatory"`

`parentSettingsBehavior`

`"first-wins"`

: the parent-supplied settings are dropped and only the admin tier applies. `"merge"`

: the parent-supplied settings apply under the admin tier, filtered so they can tighten policy but not loosen it. Has no effect when no admin tier is deployed. Default: `"first-wins"`

. Requires Claude Code v2.1.133 or later`"merge"`

`permissions`

`plansDirectory`

`~/.claude/plans`

`"./plans"`

`pluginSuggestionMarketplaces`

`relevance`

declaration in its marketplace entry. A name only takes effect when the marketplace is registered on the machine and its registered source is also declared in managed settings, either as the `extraKnownMarketplaces`

entry for that name or as an entry of `strictKnownMarketplaces`

. A marketplace registered from a different source under an allowlisted name is ignored. The official marketplace is exempt from the source requirement: allowlisting its name alone suffices, since that name can only register from the official Anthropic source.`["acme-corp-plugins"]`

`pluginTrustMessage`

`"All plugins from our marketplace are approved by IT"`

`policyHelper`

`managed-settings.json`

file. See [Compute managed settings with a policy helper](#compute-managed-settings-with-a-policy-helper). Requires Claude Code v2.1.136 or later`{"path": "/usr/local/bin/claude-policy"}`

`preferredNotifChannel`

`"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](/docs/en/terminal-config#get-a-terminal-bell-or-notification)`"terminal_bell"`

`prefersReducedMotion`

`true`

`prUrlTemplate`

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

`requiredMaximumVersion`

`claude install <version>`

may also work. Background auto-updates and `claude update`

skip versions above the ceiling, so an in-range installation stays in range. `claude update`

, `claude install`

, and `claude doctor`

keep working above the ceiling so users can recover. Versions that predate this setting ignore it`"2.1.150"`

`requiredMinimumVersion`

`claude update`

, `claude install`

, and `claude doctor`

keep working below the floor so users can recover. Differs from `minimumVersion`

, which prevents downgrades but never blocks startup. Versions that predate this setting ignore it`"2.1.150"`

`respectGitignore`

`@`

file picker respects `.gitignore`

patterns. When `true`

(default), files matching `.gitignore`

patterns are excluded from suggestions`false`

`showClearContextOnPlanAccept`

`false`

. Set to `true`

to restore the option`true`

`showThinkingSummaries`

[extended thinking](/docs/en/model-config#extended-thinking)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](/docs/en/model-config#extended-thinking)instead. This setting has no effect in non-interactive mode (`-p`

), the Agent SDK, or IDE extensions such as VS Code`true`

`showTurnDuration`

`true`

. Appears in `/config`

as **Show turn duration**`false`

`skillListingBudgetFraction`

[skill listing](/docs/en/skills#skill-descriptions-are-cut-short)Claude sees each turn (default:`0.01`

= 1%). When the listing exceeds the budget, descriptions for the least-used skills are collapsed to bare names so Claude can still invoke them but won’t see why. Raise to keep more descriptions visible at the cost of more context per turn. `/doctor`

shows the current truncation count and which skills are affected. Requires Claude Code v2.1.105 or later`0.02`

`skillOverrides`

`"on"`

, `"name-only"`

, `"user-invocable-only"`

, or `"off"`

. Lets you hide or collapse a skill without editing its SKILL.md. Does not apply to plugin skills, which are managed through `/plugin`

. The `/skills`

menu writes these to `.claude/settings.local.json`

. See [Override skill visibility from settings](/docs/en/skills#override-skill-visibility-from-settings). Requires Claude Code v2.1.129 or later`{"legacy-context": "name-only", "deploy": "off"}`

`skipWebFetchPreflight`

[WebFetch domain safety check](/docs/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`

`spinnerTipsEnabled`

`false`

to disable tips (default: `true`

)`false`

`spinnerTipsOverride`

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

`spinnerVerbs`

`mode`

to `"replace"`

to use only your verbs, or `"append"`

to add them to the defaults`{"mode": "append", "verbs": ["Pondering", "Crafting"]}`

`sshConfigs`

[Desktop](/docs/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"}]`

`statusLine`

`statusLine`

documentation`{"type": "command", "command": "~/.claude/statusline.sh"}`

`strictKnownMarketplaces`

[Managed marketplace restrictions](/docs/en/plugin-marketplaces#managed-marketplace-restrictions)`[{ "source": "github", "repo": "acme-corp/plugins" }]`

`strictPluginOnlyCustomization`

`true`

locks all four surfaces; an array locks only the named ones. See `strictPluginOnlyCustomization`

`["skills", "hooks"]`

`syntaxHighlightingDisabled`

`true`

`teammateMode`

[agent team](/docs/en/agent-teams)teammates display:`auto`

(split panes when running inside tmux or iTerm2, in-process otherwise), `in-process`

, or `tmux`

(split panes using tmux or iTerm2, detected from your terminal). `--teammate-mode`

overrides this for one session. See [choose a display mode](/docs/en/agent-teams#choose-a-display-mode)`"in-process"`

`terminalProgressBarEnabled`

`true`

. Appears in `/config`

as **Terminal progress bar**`false`

`theme`

`"auto"`

, `"dark"`

, `"light"`

, `"dark-daltonized"`

, `"light-daltonized"`

, `"dark-ansi"`

, `"light-ansi"`

, or a custom theme reference such as `"custom:<slug>"`

or `"custom:<plugin-name>:<slug>"`

. Default: `"dark"`

. See [Create a custom theme](/docs/en/terminal-config#create-a-custom-theme). Appears in`/config`

as **Theme**`"dark"`

`tui`

`"fullscreen"`

for the flicker-free [alt-screen renderer](/docs/en/fullscreen)with virtualized scrollback. Use`"default"`

for the classic main-screen renderer. Set via `/tui`

. You can also set the [environment variable. Background sessions opened from](/docs/en/env-vars)`CLAUDE_CODE_NO_FLICKER`

[agent view](/docs/en/agent-view)always use the fullscreen renderer regardless of this setting`"fullscreen"`

`ultracode`

[ultracode](/docs/en/workflows#let-claude-decide-with-ultracode)for the session. Session-only and not read from`settings.json`

. Set through `/effort ultracode`

, `--settings`

, or an Agent SDK control request`true`

`useAutoModeDuringPlan`

`true`

. Not read from shared project settings. Appears in `/config`

as “Use auto mode during plan”`false`

`verbose`

`false`

. Appears in `/config`

as **Verbose output**. The`--verbose`

flag overrides this for one session`true`

`viewMode`

`"default"`

, `"verbose"`

, or `"focus"`

. Overrides the sticky `/focus`

selection when set. The `--verbose`

flag overrides this for one session`"verbose"`

`voice`

[Voice dictation](/docs/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" }`

`voiceEnabled`

`voice.enabled`

. Prefer the `voice`

object`true`

`wheelScrollAccelerationEnabled`

[fullscreen rendering](/docs/en/fullscreen#mouse-wheel-scrolling), accelerate mouse-wheel scroll speed during fast scrolls. Default:`true`

. Set to `false`

for a constant scroll rate per wheel notch. Requires Claude Code v2.1.174 or later`false`

`workflowKeywordTriggerEnabled`

`ultracode`

in a prompt triggers a [dynamic workflow](/docs/en/workflows#ask-for-a-workflow-in-your-prompt). Set to`false`

to type the word without triggering one. The `ultracode`

effort setting, `/workflows`

, and saved workflow commands are unaffected. Default: `true`

. Appears in `/config`

as **Ultracode keyword trigger**. Added in v2.1.157; before v2.1.160 the trigger keyword was`workflow`

`false`

`wslInheritsWindowsSettings`

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

### Global config settings

These settings are stored in`~/.claude.json`

rather than `settings.json`

. Adding them to `settings.json`

will trigger a schema validation error.
Versions before v2.1.119 also store a number of

`/config`

preference keys here instead of in `settings.json`

, including `theme`

, `verbose`

, `editorMode`

, `autoCompactEnabled`

, and `preferredNotifChannel`

.| Key | Description | Example |
|---|---|---|
`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. The
`CLAUDE_CODE_AUTO_CONNECT_IDE` | `true` |
`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` | `false` |
`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` |
`teammateDefaultModel` | Default model for
`"sonnet"` , or `null` to inherit the lead’s current `/model` selection. Appears in `/config` as Default teammate model |

`"sonnet"`

### Worktree settings

Configure how`--worktree`

creates and manages git worktrees.
| Key | Description | Example |
|---|---|---|
`worktree.baseRef` | Which ref new worktrees branch from. `"fresh"` (default) branches from `origin/<default-branch>` for a clean tree matching the remote. `"head"` branches from your current local `HEAD` , so unpushed commits and feature-branch state are present in the worktree. Applies to `--worktree` , the `EnterWorktree` tool, and subagent isolation | `"head"` |
`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"]` |
`worktree.sparsePaths` | Directories to check out in each worktree via git sparse-checkout. Only the listed directories plus root-level files are written to disk, which is faster in large monorepos | `["packages/my-app", "shared/utils"]` |
`worktree.bgIsolation` | Isolation mode for
`"worktree"` (default) blocks `Edit` /`Write` in the main checkout until `EnterWorktree` is called. `"none"` lets background jobs edit the working copy directly. Requires Claude Code v2.1.143 or later |

`"none"`

`.env`

into new worktrees, use a [in your project root instead of a setting.](/docs/en/worktrees#copy-gitignored-files-into-worktrees)

`.worktreeinclude`

file### Permission settings

| Keys | Description | Example |
|---|---|---|
`allow` | Array of permission rules to allow tool use. Tool-name globs are supported only in the tool position after a literal `mcp__<server>__` prefix, such as `mcp__github__get_*` ; the server segment must be glob-free. See
| `[ "Bash(git diff *)" ]` |
`ask` | Array of permission rules to ask for confirmation upon tool use. See
|

`[ "Bash(git push *)" ]`

`deny`

`"*"`

denies every tool and `"mcp__*"`

denies all MCP tools. See [Permission rule syntax](#permission-rule-syntax)and[Bash permission limitations](/docs/en/permissions#tool-specific-permission-rules)`[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]`

`additionalDirectories`

[working directories](/docs/en/permissions#working-directories)for file access. Most`.claude/`

configuration is [not discovered](/docs/en/permissions#additional-directories-grant-file-access-not-configuration)from these directories`[ "../docs/" ]`

`defaultMode`

[permission mode](/docs/en/permission-modes)when opening Claude Code. Valid values:`default`

, `acceptEdits`

, `plan`

, `auto`

, `dontAsk`

, `bypassPermissions`

. As of Claude Code v2.1.142, `auto`

is ignored when set in project or local settings (`.claude/settings.json`

, `.claude/settings.local.json`

) so a repository cannot grant itself auto mode. Set it in `~/.claude/settings.json`

instead. The `--permission-mode`

CLI flag overrides this setting for a single session`"acceptEdits"`

`disableBypassPermissionsMode`

`"disable"`

to prevent `bypassPermissions`

mode from being activated. This disables the `--dangerously-skip-permissions`

command-line flag. Typically placed in [managed settings](/docs/en/permissions#managed-settings)to enforce organizational policy, but works from any scope`"disable"`

`skipDangerousModePermissionPrompt`

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

### Permission rule syntax

Permission rules follow the format`Tool`

or `Tool(specifier)`

. Rules are evaluated in order: deny rules first, then ask, then allow. The first match determines the outcome regardless of rule specificity. See the [permission rule evaluation order](/docs/en/permissions#manage-permissions)for details. Quick examples:

| Rule | Effect |
|---|---|
`Bash` | Matches all Bash commands |
`Bash(npm run *)` | Matches commands starting with `npm run` |
`Read(./.env)` | Matches reading the `.env` file |
`WebFetch(domain:example.com)` | Matches fetch requests to example.com |

[Permission rule syntax](/docs/en/permissions#permission-rule-syntax).

### Sandbox settings

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

| Keys | Description | Example |
|---|---|---|
`enabled` | Enable bash sandboxing (macOS, Linux, and WSL2). Default: false | `true` |
`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` |
`autoAllowBashIfSandboxed` | Auto-approve bash commands when sandboxed. Default: true | `true` |
`excludedCommands` | Commands that should run outside of the sandbox | `["docker *"]` |
`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` |
`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
| `["/tmp/build", "~/.kube"]` |
`filesystem.denyWrite` | Paths where sandboxed commands cannot write. Arrays are merged across all settings scopes. Also merged with paths from `Edit(...)` deny permission rules. | `["/etc", "/usr/local/bin"]` |
`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"]` |
`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. | `["."]` |
`filesystem.allowManagedReadPathsOnly` | (Managed settings only) Only `filesystem.allowRead` paths from managed settings are respected. `denyRead` still merges from all sources. Default: false | `true` |
`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"]` |
`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` |
`network.allowLocalBinding` | Allow binding to localhost ports (macOS only). Default: false | `true` |
`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.*"]` |
`network.allowedDomains` | Array of domains to allow for outbound network traffic. Supports wildcards (e.g., `*.example.com` ). | `["github.com", "*.npmjs.org"]` |
`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"]` |
`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` |
`network.httpProxyPort` | HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8080` |
`network.socksProxyPort` | SOCKS5 proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8081` |
`enableWeakerNestedSandbox` | Enable weaker sandbox for unprivileged Docker environments (Linux and WSL2 only). Reduces security. Default: false | `true` |
`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` |
`bwrapPath` | (Managed settings only, Linux/WSL2) Absolute path to the bubblewrap (`bwrap` ) binary. Overrides automatic detection via `PATH` . Only honored from
`bwrap` is installed at a non-standard location in managed environments. | `/opt/admin/bwrap` |
`socatPath` | (Managed settings only, Linux/WSL2) Absolute path to the `socat` binary used for the sandbox network proxy. Overrides automatic detection via `PATH` . Only honored from managed settings. | `/opt/admin/socat` |

#### Sandbox path prefixes

Paths in`filesystem.allowWrite`

, `filesystem.denyWrite`

, `filesystem.denyRead`

, and `filesystem.allowRead`

support these prefixes:
| Prefix | Meaning | Example |
|---|---|---|
`/` | Absolute path from filesystem root | `/tmp/build` stays `/tmp/build` |
`~/` | Relative to home directory | `~/.kube` becomes `$HOME/.kube` |
`./` 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` |

`//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](/docs/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.
**Configuration example:**

**Filesystem and network restrictions** can be configured in two ways that are merged together:

(shown above): Control paths at the OS-level sandbox boundary. These restrictions apply to all subprocess commands (e.g.,`sandbox.filesystem`

settings`kubectl`

,`terraform`

,`npm`

), not just Claude’s file tools.**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.

### Attribution settings

Claude Code adds attribution to git commits and pull requests. These are configured separately:- Commits use
[git trailers](https://git-scm.com/docs/git-interpret-trailers)(like`Co-Authored-By`

) by default, which can be customized or disabled - Pull request descriptions are plain text

| Keys | Description |
|---|---|
`commit` | Attribution for git commits, including any trailers. Empty string hides commit attribution |
`pr` | Attribution for pull request descriptions. Empty string hides pull request attribution |

**Default commit attribution:**

**Default pull request attribution:**

**Example:**

The

`attribution`

setting takes precedence over the deprecated `includeCoAuthoredBy`

setting. To hide all attribution, set `commit`

and `pr`

to empty strings.### File suggestion settings

Configure 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.
[hooks](/docs/en/hooks), including

`CLAUDE_PROJECT_DIR`

. It receives JSON via stdin with a `query`

field:
**Example:**

### Footer link badges

The`footerLinksRegexes`

setting renders extra clickable badges in the footer below the input box. Use it to turn IDs printed by project CLIs, such as review tools and issue trackers, into session links.
Each entry’s `pattern`

regex is matched against turn output: tool results, including file contents and fetched pages, and Claude’s own responses. `{name}`

placeholders in `url`

and `label`

are filled from named capture groups in the pattern.
The following example renders a badge whenever an issue key like `PROJ-1234`

appears in turn output. The `(?<key>...)`

named group captures the key, and `{key}`

substitutes it into the URL and label:
~/.claude/settings.json

`PROJ-1234`

appears in a tool result or in Claude’s reply, a `PROJ-1234`

chip appears in the footer linking to `https://issues.example.com/browse/PROJ-1234`

.
The following constraints apply to each entry:
| Constraint | Behavior |
|---|---|
| URL origin | Captured values are URL-encoded and the constructed URL must share the template’s literal origin. A capture can fill a path segment or query value but cannot change where the link points |
| URL length | Constructed URLs longer than 2048 characters are dropped |
| URL scheme | Must be `https` , `http` , or a recognized editor or workspace deep-link scheme: `vscode` , `vscode-insiders` , `cursor` , `windsurf` , `zed` , `jetbrains` , `idea` , `slack` , `linear` , `notion` , `figma` |
| Label | Defaults to the matched text and is truncated to 28 display columns |
| Badge count | At most 5 badges render. The oldest is displaced by newer matches and `/clear` removes them |
| Settings scope | Read from user settings, the `--settings` flag, and managed settings only. Ignored in project `.claude/settings.json` and local `.claude/settings.local.json` |

`pattern`

regex against the turn output on the main thread, so a slow regex blocks the UI until it finishes. Nested quantifiers such as `(a+)+$`

can take exponentially long against certain inputs and freeze the session, so keep each `pattern`

linear and avoid nesting `+`

or `*`

.
Footer badges render alongside a [custom status line](/docs/en/statusline)when one is configured; neither replaces the other. Use a status line for a script-driven row that computes its own content from session data, and footer badges to turn IDs from the conversation into links without a script.

### Hook configuration

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

**Behavior when**

`allowManagedHooksOnly`

is `true`

:- Managed hooks and SDK hooks are loaded
- 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 - User hooks, project hooks, and all other plugin hooks are blocked

**Restrict HTTP hook URLs:** Limit 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. Hostname matching is case-insensitive and ignores a trailing FQDN dot, matching DNS semantics.
**Restrict HTTP hook environment variables:** Limit 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.
### Compute managed settings with a policy helper

The`policyHelper`

setting points at an executable that computes managed settings at startup, so admins can derive policy from device posture, identity, or a remote service instead of a static file. Configure it from MDM or a system `managed-settings.json`

file. Claude Code ignores `policyHelper`

when it appears in any other scope, including user settings, project settings, the HKCU registry hive, and [server-managed settings](/docs/en/server-managed-settings). The setting accepts these keys:

| Key | Type | Description |
|---|---|---|
`path` | string | Absolute path to the helper executable |
`timeoutMs` | number | How long to wait for the helper before treating the run as failed |
`refreshIntervalMs` | number | How often to re-run the helper in the background. Set to `0` to disable refresh, or to at least `60000` |

`managedSettings`

key rather than at the top level, since a bare settings object parses with `managedSettings`

undefined and applies nothing:
`managedSettings`

, that object replaces the file-based managed settings for the run. When the helper exits non-zero at startup, Claude Code prints the error and refuses to start, so a helper that needs outage resilience should serve from its own cache and exit `0`

.
### Settings precedence

Settings apply in order of precedence. From highest to lowest:-
**Managed settings**([server-managed](/docs/en/server-managed-settings),[MDM/OS-level policies](#configuration-scopes), or[managed settings](/docs/en/settings#settings-files))- Policies deployed by IT through server delivery, MDM configuration profiles, registry policies, or managed settings files
- Cannot be overridden by any other level, including command line arguments
- 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. - Embedding hosts such as Claude Desktop can supply policy via the SDK
`managedSettings`

option. By default this is ignored when any managed-settings tier is present. Administrators can opt in by settingto`parentSettingsBehavior`

`"merge"`

. The embedder’s values are filtered so they can tighten managed policy but not loosen it.

-
**Command line arguments**- Temporary overrides for a specific session. JSON passed via
`--settings <file-or-json>`

merges with file-based settings using the same rules as the other layers: a key set here overrides the same key in local, project, or user settings, and omitting a key leaves the lower-layer value in place

- Temporary overrides for a specific session. JSON passed via
-
**Local project settings**(`.claude/settings.local.json`

)- Personal project-specific settings

-
**Shared project settings**(`.claude/settings.json`

)- Team-shared project settings in source control

-
**User settings**(`~/.claude/settings.json`

)- Personal global settings

[VS Code extension](/docs/en/vs-code), or a

[JetBrains IDE](/docs/en/jetbrains). For example, if your user settings set

`permissions.defaultMode`

to `acceptEdits`

and a project’s shared settings set it to `default`

, the project value applies. The example below covers how array-valued settings such as permission rules combine instead.
**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. Two exceptions: [is an ordered chain where position carries meaning, so the highest-precedence file that defines it supplies the entire value. As of v2.1.175, a managed or policy](#available-settings)

`fallbackModel`

[value replaces lower-precedence entries entirely. See](#available-settings)

`availableModels`

[Merge behavior](/docs/en/model-config#merge-behavior).

### Verify active settings

Run`/status`

inside Claude Code to see which settings sources are active. Inside the menu, the **Status** tab includes a

`Setting sources`

line that lists each layer Claude Code loaded for the current session, such as `User settings`

or `Project local settings`

. When [managed settings](/docs/en/admin-setup#decide-how-settings-reach-devices)are in effect, the entry shows the delivery channel in parentheses, for example

`Enterprise managed settings (remote)`

, `(plist)`

, `(HKLM)`

, `(HKCU)`

, or `(file)`

. A layer appears in the list only when that source is loaded with at least one key, so an empty list means no settings sources were found.
The `Setting sources`

line confirms which sources are being read. It does not show which layer supplied each individual key. The **Config** tab in the same dialog is an editor for a fixed set of toggles such as theme and verbose output, not a view of your

`settings.json`

contents.
If a settings file contains errors, such as invalid JSON or a value that fails validation, Claude Code shows a setup issues notice at startup and `/status`

lists the affected files. Run `/doctor`

to see the details for each error.
### Key points about the configuration system

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

)**Settings files (JSON)**: Configure permissions, environment variables, and tool behavior** Skills**: Custom prompts that can be invoked with`/skill-name`

or loaded by Claude automatically**MCP servers**: Extend Claude Code with additional tools and integrations** Precedence**: Higher-level configurations (Managed) override lower-level ones (User/Project)** Inheritance**: Settings merge across scopes; scalar values from higher-priority scopes override, and arrays concatenate. Exceptions:`fallbackModel`

, where the highest-precedence scope supplies the whole chain, and`availableModels`

, where a managed or policy value replaces lower-precedence entries

### System prompt

Claude Code’s internal system prompt is not published. To add custom instructions, use`CLAUDE.md`

files or the `--append-system-prompt`

flag.
### Excluding sensitive files

To 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:
`ignorePatterns`

configuration. Files matching these patterns are excluded from file discovery and search results, and read operations on these files are denied.
## Subagent configuration

Claude Code supports custom AI subagents that can be configured at both user and project levels. These subagents are stored as Markdown files with YAML frontmatter:**User subagents**:`~/.claude/agents/`

- Available across all your projects**Project subagents**:`.claude/agents/`

- Specific to your project and can be shared with your team

[subagents documentation](/docs/en/sub-agents).

## Plugin configuration

Claude 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.### Plugin settings

Plugin-related settings in`settings.json`

:
`enabledPlugins`

Controls which plugins are enabled. Format: `"plugin-name@marketplace-name": true/false`

. A plugin with no entry at any scope falls back to its [value.](/docs/en/plugins-reference#default-enablement)

`defaultEnabled`

**Scopes**:

**User settings**(`~/.claude/settings.json`

): Personal plugin preferences**Project settings**(`.claude/settings.json`

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

): Per-machine overrides, gitignored when Claude Code creates it**Managed settings**(`managed-settings.json`

): Organization-wide policy overrides that block installation at all scopes and hide the plugin from the marketplace

Project settings take precedence over user settings, so setting a plugin to

`false`

in `~/.claude/settings.json`

does not disable a plugin that the project’s `.claude/settings.json`

enables. To opt out of a project-enabled plugin on your machine, set it to `false`

in `.claude/settings.local.json`

instead.Plugins force-enabled by managed settings cannot be disabled this way, since managed settings override local settings.**Example**:

`extraKnownMarketplaces`

Defines additional marketplaces that should be made available for the repository. Typically used in repository-level settings to ensure team members have access to required plugin sources.
**When a repository includes**:

`extraKnownMarketplaces`

- Team members are prompted to install the marketplace when they trust the folder
- Team members are then prompted to install plugins from that marketplace
- Users can skip unwanted marketplaces or plugins (stored in user settings)
- Installation respects trust boundaries and requires explicit consent

**Example**:

**Marketplace source types**:

`github`

: GitHub repository (uses`repo`

)`git`

: Any git URL (uses`url`

)`directory`

: Local filesystem path (uses`path`

, for development only)`hostPattern`

: regex pattern to match marketplace hosts (uses`hostPattern`

)`settings`

: inline marketplace declared directly in settings.json without a separate hosted repository (uses`name`

and`plugins`

)

`git`

source type works with any git hosting service, including self-hosted GitLab and Bitbucket. Claude Code clones the repository with the same authentication that `git clone`

would use on that machine: configured credential helpers, SSH keys, or a host-specific token environment variable. See [Private repositories](/docs/en/plugin-marketplaces#private-repositories)for setup details. For

`github`

and `git`

sources, set `"skipLfs": true`

inside the `source`

object (alongside `repo`

or `url`

) to skip Git LFS downloads when Claude Code clones or updates the marketplace repository. LFS pointer files remain as pointers instead of downloading their content. Use this when the repository contains large LFS objects unrelated to plugin content. Requires Claude Code v2.1.153 or later.
Each marketplace entry also accepts an optional `autoUpdate`

Boolean. Set `"autoUpdate": true`

alongside `source`

to make Claude Code refresh that marketplace and update its installed plugins at startup. When omitted, official Anthropic marketplaces default to `true`

and all other marketplaces default to `false`

. See [Configure auto-updates](/docs/en/discover-plugins#configure-auto-updates). Use

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

.
`strictKnownMarketplaces`

**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](/docs/en/settings#settings-files)and provides administrators with strict control over marketplace sources.

**Managed settings file locations**:

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

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

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

**Key characteristics**:

- Only available in managed settings (
`managed-settings.json`

) - Cannot be overridden by user or project settings (highest precedence)
- Enforced BEFORE network/filesystem operations (blocked sources never execute)
- Uses exact matching for source specifications (including
`ref`

,`path`

for git sources), except`hostPattern`

and`pathPattern`

, which use regex matching

**Allowlist behavior**:

`undefined`

(default): No restrictions - users can add any marketplace- Empty array
`[]`

: Complete lockdown - users cannot add any new marketplaces - List of sources: Users can only add marketplaces that match exactly

**All supported source types**: The allowlist supports multiple marketplace source types. Most sources use exact matching, while

`hostPattern`

and `pathPattern`

use regex matching against the marketplace host and filesystem path respectively.
**GitHub repositories**:

`repo`

(required), `ref`

(optional: branch/tag/SHA), `path`

(optional: subdirectory)
**Git repositories**:

`url`

(required), `ref`

(optional: branch/tag/SHA), `path`

(optional: subdirectory)
**URL-based marketplaces**:

`url`

(required), `headers`

(optional: HTTP headers for authenticated access)
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](/docs/en/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces)for details.**NPM packages**:

`package`

(required, supports scoped packages)
**File paths**:

`path`

(required: absolute path to marketplace.json file)
**Directory paths**:

`path`

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

)
**Host pattern matching**:

`hostPattern`

(required: regex pattern to match against the marketplace host)
Use 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.
Host extraction by source type:
`github`

: always matches against`github.com`

`git`

: extracts hostname from the URL (supports both HTTPS and SSH formats)`url`

: extracts hostname from the URL`npm`

,`file`

,`directory`

: not supported for host pattern matching

**Path pattern matching**:

`pathPattern`

(required: regex pattern matched against the `path`

field of `file`

and `directory`

sources)
Use path pattern matching to allow filesystem-based marketplaces alongside `hostPattern`

restrictions for network sources. Set `".*"`

to allow all local paths, or a narrower pattern to restrict to specific directories.
**Configuration examples**: Example: allow specific marketplaces only:

**Exact matching requirements**: Marketplace sources must match

**exactly** for a user’s addition to be allowed. For git-based sources (

`github`

and `git`

), this includes all optional fields:
- The
`repo`

or`url`

must match exactly - The
`ref`

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

field must match exactly (or both be undefined)

**do NOT match**:

**Comparison with**:

`extraKnownMarketplaces`

| Aspect | `strictKnownMarketplaces` | `extraKnownMarketplaces` |
|---|---|---|
Purpose | Organizational policy enforcement | Team convenience |
Settings file | `managed-settings.json` only | Any settings file |
Behavior | Blocks non-allowlisted additions | Auto-installs missing marketplaces |
When enforced | Before network/filesystem operations | After user trust prompt |
Can be overridden | No (highest precedence) | Yes (by higher precedence settings) |
Source format | Direct source object | Named marketplace with nested source |
Use case | Compliance, security restrictions | Onboarding, standardization |

**Format difference**:

`strictKnownMarketplaces`

uses direct source objects:
`extraKnownMarketplaces`

requires named marketplaces:
**Using both together**:

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

:
`strictKnownMarketplaces`

set, users can still add the allowed marketplace manually via `/plugin marketplace add`

, but it is not available automatically.
**Important notes**:

- Restrictions are checked BEFORE any network requests or filesystem operations
- When blocked, users see clear error messages indicating the source is blocked by managed policy
- 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
- Managed settings have the highest precedence and cannot be overridden

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

`strictPluginOnlyCustomization`

**Managed settings only**: blocks skills, agents, hooks, and MCP servers from user and project sources, so they can only come from plugins or managed settings. Combine it with

`strictKnownMarketplaces`

to control the full customization supply chain: the marketplace allowlist controls which plugins users can install, and this setting blocks everything that doesn’t come from a plugin or from managed settings.
`strictPluginOnlyCustomization`

requires Claude Code v2.1.82 or later. Earlier versions ignore the key and keep loading user and project customizations, so the lockdown isn’t enforced until clients update.`true`

to lock all four surfaces, or an array naming the surfaces to lock:
| Surface | Blocked when locked | Still loads |
|---|---|---|
`skills` | `~/.claude/skills/` , `.claude/skills/` | Plugin skills, bundled skills, skills in the managed policy directory |
`agents` | `~/.claude/agents/` , `.claude/agents/` | Plugin agents, built-in agents, agents in the managed policy directory |
`hooks` | Hooks in user, project, and local `settings.json` | Plugin hooks, hooks in managed settings |
`mcp` | Servers in `~/.claude.json` and `.mcp.json` | Plugin MCP servers,
`managed-mcp.json` |

### Managing plugins

Use the`/plugin`

command to manage plugins interactively:
- Browse available plugins from marketplaces
- Install/uninstall plugins
- Enable/disable plugins
- View plugin details (skills, agents, hooks provided)
- Add/remove marketplaces

[plugins documentation](/docs/en/plugins).

## Environment variables

Environment variables let you control Claude Code behavior without editing settings files. Any variable can also be configured in[under the](#available-settings)

`settings.json`

`env`

key to apply it to every session or roll it out to your team.
See the [environment variables reference](/docs/en/env-vars)for the full list.

## Tools available to Claude

Claude 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. See the[tools reference](/docs/en/tools-reference)for the full list and Bash tool behavior details.

## See also

[Permissions](/docs/en/permissions): permission system, rule syntax, tool-specific patterns, and managed policies[Authentication](/docs/en/authentication): set up user access to Claude Code[Debug your configuration](/docs/en/debug-your-config): diagnose why a setting, hook, or MCP server isn’t taking effect[Troubleshoot installation and login](/docs/en/troubleshoot-install): installation, authentication, and platform issues