{"slug": "claude-code-sessions-erase-after-30-days-by-default", "title": "Claude Code sessions erase after 30 days by default", "summary": "Anthropic's Claude Code erases sessions after 30 days by default, with configuration scopes including Managed, User, Project, and Local settings that determine how configurations apply and who they are shared with.", "body_md": "`/config`\n\ncommand when using the interactive REPL, which opens a tabbed Settings interface where you can view status information and modify configuration options.\n## Configuration scopes\n\nClaude 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.\n\n### Available scopes\n\n| Scope | Location | Who it affects | Shared with team? |\n|---|---|---|---|\nManaged | Server-managed settings, plist / registry, or system-level `managed-settings.json` | All users on the machine | Yes (deployed by IT) |\nUser | `~/.claude/` directory | You, across all projects | No |\nProject | `.claude/` in repository | All collaborators on this repository | Yes (committed to git) |\nLocal | `.claude/settings.local.json` | You, in this repository only | No (gitignored when Claude Code creates it) |\n\n### When to use each scope\n\n**Managed scope** is for:\n\n- Security policies that must be enforced organization-wide\n- Compliance requirements that can’t be overridden\n- Standardized configurations deployed by IT/DevOps\n\n**User scope** is best for:\n\n- Personal preferences you want everywhere (themes, editor settings)\n- Tools and plugins you use across all projects\n- API keys and authentication (stored securely)\n\n**Project scope** is best for:\n\n- Team-shared settings (permissions, hooks, MCP servers)\n- Plugins the whole team should have\n- Standardizing tooling across collaborators\n\n**Local scope** is best for:\n\n- Personal overrides for a specific project\n- Testing configurations before sharing with the team\n- Machine-specific settings that won’t work for others\n\n### How scopes interact\n\nWhen 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\n\n`spinnerTipsEnabled`\n\nto `true`\n\nand project settings set it to `false`\n\n, the project value applies. Permission rules behave differently because they merge across scopes rather than override. See [Settings precedence](#settings-precedence).\n\n### What uses scopes\n\nScopes apply to many Claude Code features:| Feature | User location | Project location | Local location |\n|---|---|---|---|\nSettings | `~/.claude/settings.json` | `.claude/settings.json` | `.claude/settings.local.json` |\nSubagents | `~/.claude/agents/` | `.claude/agents/` | None |\nMCP servers | `~/.claude.json` | `.mcp.json` | `~/.claude.json` (per-project) |\nPlugins | `~/.claude/settings.json` | `.claude/settings.json` | `.claude/settings.local.json` |\nCLAUDE.md | `~/.claude/CLAUDE.md` | `CLAUDE.md` or `.claude/CLAUDE.md` | `CLAUDE.local.md` |\n\n`~/.claude`\n\nresolve to `%USERPROFILE%\\.claude`\n\n.\n## Settings files\n\nThe`settings.json`\n\nfile is the official mechanism for configuring Claude\nCode through hierarchical settings:\n-\n**User settings** are defined in`~/.claude/settings.json`\n\nand apply to all projects. -\n**Project settings** are saved in your project directory:`.claude/settings.json`\n\nfor settings that are checked into source control and shared with your team`.claude/settings.local.json`\n\nfor settings that are not checked in, useful for personal preferences and experimentation. When Claude Code creates`.claude/settings.local.json`\n\n, it configures git to ignore the file. If you create the file yourself, add it to your gitignore manually.\n\n-\n**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:-\n**Server-managed settings**: delivered from Anthropic’s servers via the Claude.ai admin console. See[server-managed settings](/docs/en/server-managed-settings). -\n**MDM/OS-level policies**: delivered through native device management on macOS and Windows:- macOS:\n`com.anthropic.claudecode`\n\nmanaged preferences domain. The plist’s top-level keys mirror`managed-settings.json`\n\n, with nested settings as dictionaries and arrays as plist arrays. Deploy via configuration profiles in Jamf, Iru (Kandji), or similar MDM tools. - Windows:\n`HKLM\\SOFTWARE\\Policies\\ClaudeCode`\n\nregistry key with a`Settings`\n\nvalue (REG_SZ or REG_EXPAND_SZ) containing JSON (deployed via Group Policy or Intune) - Windows (user-level):\n`HKCU\\SOFTWARE\\Policies\\ClaudeCode`\n\n(lowest policy priority, only used when no admin-level source exists)\n\n- macOS:\n-\n**File-based**:`managed-settings.json`\n\nand`managed-mcp.json`\n\ndeployed to system directories:- macOS:\n`/Library/Application Support/ClaudeCode/`\n\n- Linux and WSL:\n`/etc/claude-code/`\n\n- Windows:\n`C:\\Program Files\\ClaudeCode\\`\n\n`managed-settings.d/`\n\nin the same system directory alongside`managed-settings.json`\n\n. This lets separate teams deploy independent policy fragments without coordinating edits to a single file. Following the systemd convention,`managed-settings.json`\n\nis merged first as the base, then all`*.json`\n\nfiles 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`.`\n\nare ignored. Use numeric prefixes to control merge order, for example`10-telemetry.json`\n\nand`20-security.json`\n\n. - macOS:\n\n[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`\n\n. For more information, see[Managed marketplace restrictions](/docs/en/plugin-marketplaces#managed-marketplace-restrictions). -\n-\n**Other configuration** is stored in`~/.claude.json`\n\n. 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`\n\n.\n\nClaude Code automatically creates timestamped backups of configuration files and retains the five most recent backups to prevent data loss.\n\nExample settings.json\n\n`$schema`\n\nline 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\n\n`settings.json`\n\nenables autocomplete and inline validation in VS Code, Cursor, and any other editor that supports JSON schema validation.\nThe 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.\n### When edits take effect\n\nClaude 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`\n\n, `hooks`\n\n, and credential helpers like `apiKeyHelper`\n\n. 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)\n\n`ConfigChange`\n\nhook`model`\n\n: useto switch mid-session`/model`\n\n: part of the system prompt, which is rebuilt on`outputStyle`\n\n`/clear`\n\nor restart\n\n### Invalid entries in managed settings\n\nManaged 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\n\n`managed-settings.json`\n\nfiles. Requires Claude Code v2.1.169 or later.\nSecurity-enforcement fields are handled per field instead of being stripped wholesale when they are present but invalid:\n| Field | Behavior when present but invalid |\n|---|---|\n`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. |\n`allowManagedMcpServersOnly` | Treated as `true` . |\n`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. |\n`enforceAvailableModels` | Treated as `true` . Applies in v2.1.175 and later. |\n`forceLoginOrgUUID` | No organization is permitted to log in until the value is fixed. |\n`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. |\n\n`requiredMinimumVersion`\n\nand `requiredMaximumVersion`\n\nfail open by design: an invalid value is stripped rather than enforced, so a bad policy push cannot prevent Claude Code from starting.\nValidation errors surface in three places:\n- Interactive sessions show a dialog at startup listing the invalid entries.\n- Headless runs with\n`-p`\n\nprint a summary to stderr. lists each invalid entry with its source and field.`claude doctor`\n\n`claude doctor`\n\non a test machine before deploying them fleet-wide.\nThis 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.\n### Available settings\n\n`settings.json`\n\nsupports a number of options:\n| Key | Description | Example |\n|---|---|---|\n`advisorModel` | Model for the server-side\n`\"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 |\n\n`\"opus\"`\n\n`agent`\n\n`claude agents`\n\n. Applies that subagent’s system prompt, tool restrictions, and model. See [Invoke subagents explicitly](/docs/en/sub-agents#invoke-subagents-explicitly)`\"code-reviewer\"`\n\n`agentPushNotifEnabled`\n\n[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`\n\n. Appears in `/config`\n\nas **Push when Claude decides**. See[Mobile push notifications](/docs/en/remote-control#mobile-push-notifications). Requires Claude Code v2.1.119 or later`true`\n\n`allowAllClaudeAiMcps`\n\n`managed-mcp.json`\n\n, which otherwise takes exclusive control and suppresses them. See [Managed MCP configuration](/docs/en/managed-mcp)`true`\n\n`allowedChannelPlugins`\n\n`channelsEnabled: true`\n\n. See [Restrict which channel plugins can run](/docs/en/channels#restrict-which-channel-plugins-can-run)`[{ \"marketplace\": \"claude-plugins-official\", \"plugin\": \"telegram\" }]`\n\n`allowedHttpHookUrls`\n\n`*`\n\nas 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/*\"]`\n\n`allowedMcpServers`\n\n[Managed MCP configuration](/docs/en/managed-mcp)`[{ \"serverName\": \"github\" }]`\n\n`allowManagedHooksOnly`\n\n`enabledPlugins`\n\nare loaded. User, project, and all other plugin hooks are blocked. See [Hook configuration](#hook-configuration)`true`\n\n`allowManagedMcpServersOnly`\n\n`allowedMcpServers`\n\nfrom managed settings are respected. `deniedMcpServers`\n\nstill 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`\n\n`allowManagedPermissionRulesOnly`\n\n`allow`\n\n, `ask`\n\n, or `deny`\n\npermission rules. Only rules in managed settings apply. See [Managed-only settings](/docs/en/permissions#managed-only-settings)`true`\n\n`alwaysThinkingEnabled`\n\n[extended thinking](/docs/en/model-config#extended-thinking)by default for all sessions. Typically configured via the`/config`\n\ncommand rather than editing directly. To force thinking off regardless of this setting, set [in](/docs/en/env-vars)`MAX_THINKING_TOKENS=0`\n\n`env`\n\n, 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`\n\nparameter instead, and adaptive-reasoning models may still think`true`\n\n`apiKeyHelper`\n\n`/bin/sh`\n\n, to generate an auth value. This value will be sent as `X-Api-Key`\n\nand `Authorization: Bearer`\n\nheaders for model requests. Set the refresh interval with `CLAUDE_CODE_API_KEY_HELPER_TTL_MS`\n\n`/bin/generate_temp_api_key.sh`\n\n`attribution`\n\n[Attribution settings](#attribution-settings)`{\"commit\": \"🤖 Generated with Claude Code\", \"pr\": \"\"}`\n\n`autoCompactEnabled`\n\n`true`\n\n. Appears in `/config`\n\nas **Auto-compact**. To disable via environment variable, set[in](/docs/en/env-vars)`DISABLE_AUTO_COMPACT`\n\n`env`\n\n`false`\n\n`autoMemoryDirectory`\n\n[auto memory](/docs/en/memory#storage-location)storage. Accepts an absolute path or a`~/`\n\n-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\"`\n\n`autoMemoryEnabled`\n\n[auto memory](/docs/en/memory#enable-or-disable-auto-memory). When`false`\n\n, Claude does not read from or write to the auto memory directory. Default: `true`\n\n. You can also toggle this with `/memory`\n\nduring a session. To disable via environment variable, set [in](/docs/en/env-vars)`CLAUDE_CODE_DISABLE_AUTO_MEMORY`\n\n`env`\n\n`false`\n\n`autoMode`\n\n[auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode)classifier blocks and allows. Contains`environment`\n\n, `allow`\n\n, `soft_deny`\n\n, and `hard_deny`\n\narrays of prose rules. Include the literal string `\"$defaults\"`\n\nin 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\"]}`\n\n`autoScrollEnabled`\n\n[fullscreen rendering](/docs/en/fullscreen), follow new output to the bottom of the conversation. Default:`true`\n\n. Appears in `/config`\n\nas **Auto-scroll**. Permission prompts still scroll into view when this is off`false`\n\n`autoUpdatesChannel`\n\n`\"stable\"`\n\nfor a version that is typically about one week old and skips versions with major regressions, or `\"latest\"`\n\n(default) for the most recent release. To disable auto-updates entirely, set [in](/docs/en/setup#disable-auto-updates)`DISABLE_AUTOUPDATER`\n\n`env`\n\n`\"stable\"`\n\n`availableModels`\n\n[subagents](/docs/en/sub-agents), and the[advisor](/docs/en/advisor). See[Restrict model selection](/docs/en/model-config#restrict-model-selection). See`enforceAvailableModels`\n\nto also constrain Default`[\"sonnet\", \"haiku\"]`\n\n`awaySummaryEnabled`\n\n`false`\n\nor turn off Session recap in `/config`\n\nto disable. Same as `CLAUDE_CODE_ENABLE_AWAY_SUMMARY`\n\n`true`\n\n`awsAuthRefresh`\n\n`.aws`\n\ndirectory (see [advanced credential configuration](/docs/en/amazon-bedrock#advanced-credential-configuration))`aws sso login --profile myprofile`\n\n`awsCredentialExport`\n\n[advanced credential configuration](/docs/en/amazon-bedrock#advanced-credential-configuration))`/bin/generate_aws_grant.sh`\n\n`blockedMarketplaces`\n\n[Managed marketplace restrictions](/docs/en/plugin-marketplaces#managed-marketplace-restrictions)`[{ \"source\": \"github\", \"repo\": \"untrusted/plugins\" }]`\n\n`channelsEnabled`\n\n[channels](/docs/en/channels)for the organization. On claude.ai Team and Enterprise plans, channels are blocked when this is unset or`false`\n\n. 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`\n\n`true`\n\n`claudeMd`\n\n[organization-wide CLAUDE.md](/docs/en/memory#deploy-organization-wide-claude-md)`\"Always run make lint before committing.\"`\n\n`claudeMdExcludes`\n\n`CLAUDE.md`\n\nfiles 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\"]`\n\n`cleanupPeriodDays`\n\n`0`\n\nis 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`\n\n`-p`\n\n) use the `--no-session-persistence`\n\nflag or the `persistSession: false`\n\nSDK option.`20`\n\n`companyAnnouncements`\n\n`[\"Welcome to Acme Corp! Review our code guidelines at docs.acme.com\"]`\n\n`defaultShell`\n\n`!`\n\ncommands. Accepts `\"bash\"`\n\n(default) or `\"powershell\"`\n\n. Setting `\"powershell\"`\n\nroutes interactive `!`\n\ncommands through PowerShell on Windows. Requires `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`\n\n. See [PowerShell tool](/docs/en/tools-reference#powershell-tool)`\"powershell\"`\n\n`deniedMcpServers`\n\n[Managed MCP configuration](/docs/en/managed-mcp)`[{ \"serverName\": \"filesystem\" }]`\n\n`disableAgentView`\n\n`true`\n\nto turn off [background agents and agent view](/docs/en/agent-view):`claude agents`\n\n, `--bg`\n\n, `/background`\n\n, and the on-demand supervisor. Typically set in [managed settings](/docs/en/permissions#managed-settings). Equivalent to setting`CLAUDE_CODE_DISABLE_AGENT_VIEW`\n\nto `1`\n\n`true`\n\n`disableAllHooks`\n\n[hooks](/docs/en/hooks)and any custom[status line](/docs/en/statusline)`true`\n\n`disableAutoMode`\n\n`\"disable\"`\n\nto prevent [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode)from being activated. Removes`auto`\n\nfrom the `Shift+Tab`\n\ncycle and rejects `--permission-mode auto`\n\nat startup. Most useful in [managed settings](/docs/en/permissions#managed-settings)where users cannot override it`\"disable\"`\n\n`disableBundledSkills`\n\n`true`\n\nto 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`\n\nstay typable but are hidden from the model. Skills from plugins, `.claude/skills/`\n\n, and `.claude/commands/`\n\nare unaffected. Equivalent to setting `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS`\n\nto `1`\n\n`true`\n\n`disableDeepLinkRegistration`\n\n`\"disable\"`\n\nto prevent Claude Code from registering the `claude-cli://`\n\nprotocol 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\"`\n\n`disabledMcpjsonServers`\n\n`.mcp.json`\n\nfiles to reject`[\"filesystem\"]`\n\n`disableRemoteControl`\n\n[Remote Control](/docs/en/remote-control): blocks`claude remote-control`\n\n, the `--remote-control`\n\nflag, 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`\n\n`disableSkillShellExecution`\n\n`!`...``\n\nand ````!`\n\nblocks 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]`\n\ninstead 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`\n\n`disableWorkflows`\n\n[dynamic workflows](/docs/en/workflows#turn-workflows-off)and the bundled workflow commands. Default:`false`\n\n. Equivalent to setting `CLAUDE_CODE_DISABLE_WORKFLOWS`\n\nto `1`\n\n`true`\n\n`editorMode`\n\n`\"normal\"`\n\nor `\"vim\"`\n\n. Default: `\"normal\"`\n\n. Appears in `/config`\n\nas **Editor mode**`\"vim\"`\n\n`effortLevel`\n\n[effort level](/docs/en/model-config#adjust-effort-level)across sessions. Accepts`\"low\"`\n\n, `\"medium\"`\n\n, `\"high\"`\n\n, or `\"xhigh\"`\n\n. Written automatically when you run `/effort`\n\nwith one of those values. `--effort`\n\nand [override this for one session. See](/docs/en/env-vars)`CLAUDE_CODE_EFFORT_LEVEL`\n\n[Adjust effort level](/docs/en/model-config#adjust-effort-level)for supported models`\"xhigh\"`\n\n`enableAllProjectMcpServers`\n\n`.mcp.json`\n\nfiles`true`\n\n`enabledMcpjsonServers`\n\n`.mcp.json`\n\nfiles to approve`[\"memory\", \"github\"]`\n\n`enforceAvailableModels`\n\n`true`\n\nand `availableModels`\n\nis 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`\n\nis set at multiple levels. Requires Claude Code v2.1.175 or later`true`\n\n`env`\n\n`NO_COLOR`\n\nand `FORCE_COLOR`\n\nset here are passed to subprocesses but do not change Claude Code’s own interface colors. Set those in your shell before launching `claude`\n\nto change interface colors`{\"FOO\": \"bar\"}`\n\n`fallbackModel`\n\n`\"default\"`\n\nexpands 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`\n\n[Fallback model chains](/docs/en/model-config#fallback-model-chains)`[\"claude-sonnet-4-6\", \"claude-haiku-4-5\"]`\n\n`fastModePerSessionOptIn`\n\n`true`\n\n, fast mode does not persist across sessions. Each session starts with fast mode off, requiring users to enable it with `/fast`\n\n. 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`\n\n`feedbackSurveyRate`\n\n[session quality survey](/docs/en/data-usage#session-quality-surveys)appears when eligible. Set to`0`\n\nto suppress entirely, or set [in](/docs/en/env-vars)`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`\n\n`env`\n\n. Useful when using Bedrock, Vertex, or Foundry where the default sample rate does not apply`0.05`\n\n`fileCheckpointingEnabled`\n\n[can restore them. Default:](/docs/en/checkpointing)`/rewind`\n\n`true`\n\n. Appears in `/config`\n\nas **Rewind code (checkpoints)**. To disable via environment variable, set[in](/docs/en/env-vars)`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`\n\n`env`\n\n`false`\n\n`fileSuggestion`\n\n`@`\n\nfile autocomplete. See [File suggestion settings](#file-suggestion-settings)`{\"type\": \"command\", \"command\": \"~/.claude/file-suggestion.sh\"}`\n\n`footerLinksRegexes`\n\n`pattern`\n\n, a `url`\n\ntemplate with `{name}`\n\nplaceholders filled from named capture groups, and an optional `label`\n\n. Read from user, `--settings`\n\nflag, 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}\"}]`\n\n`forceLoginMethod`\n\n`claudeai`\n\nto restrict login to Claude.ai accounts, `console`\n\nto restrict login to Claude Console accounts. When set in managed settings, sessions authenticated by `ANTHROPIC_API_KEY`\n\n, `ANTHROPIC_AUTH_TOKEN`\n\n, or `apiKeyHelper`\n\nare 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`\n\n`forceLoginOrgUUID`\n\n`ANTHROPIC_API_KEY`\n\n, `ANTHROPIC_AUTH_TOKEN`\n\n, or `apiKeyHelper`\n\nare 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\"`\n\nor `[\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\", \"yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy\"]`\n\n`forceRemoteSettingsRefresh`\n\n[fail-closed enforcement](/docs/en/server-managed-settings#enforce-fail-closed-startup)`true`\n\n`gcpAuthRefresh`\n\n[advanced credential configuration](/docs/en/google-vertex-ai#advanced-credential-configuration)`gcloud auth application-default login`\n\n`hooks`\n\n[hooks documentation](/docs/en/hooks)for format[hooks](/docs/en/hooks)`httpHookAllowedEnvVars`\n\n`allowedEnvVars`\n\nis the intersection with this list. Undefined = no restriction. Arrays merge across settings sources. See [Hook configuration](#hook-configuration)`[\"MY_TOKEN\", \"HOOK_SECRET\"]`\n\n`includeCoAuthoredBy`\n\n**Deprecated**: Use`attribution`\n\ninstead. Whether to include the `co-authored-by Claude`\n\nbyline in git commits and pull requests (default: `true`\n\n)`false`\n\n`includeGitInstructions`\n\n`true`\n\n). Set to `false`\n\nto remove both, for example when using your own git workflow skills. The `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS`\n\nenvironment variable takes precedence over this setting when set`false`\n\n`inputNeededNotifEnabled`\n\n[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`\n\n. Appears in `/config`\n\nas **Push when actions required**. See[Mobile push notifications](/docs/en/remote-control#mobile-push-notifications). Requires Claude Code v2.1.119 or later`true`\n\n`language`\n\n`\"japanese\"`\n\n, `\"spanish\"`\n\n, `\"french\"`\n\n). 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\"`\n\n`maxSkillDescriptionChars`\n\n`description`\n\nand `when_to_use`\n\ntext in the [skill listing](/docs/en/skills#skill-descriptions-are-cut-short)Claude sees each turn (default:`1536`\n\n). 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`\n\n`2048`\n\n`minimumVersion`\n\n`claude update`\n\nfrom installing a version below this one. Switching from the `\"latest\"`\n\nchannel to `\"stable\"`\n\nvia `/config`\n\nprompts 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`\n\n`\"2.1.100\"`\n\n`model`\n\n`--model`\n\nand [override this for one session](/docs/en/model-config#environment-variables)`ANTHROPIC_MODEL`\n\n`\"claude-sonnet-4-6\"`\n\n`modelOverrides`\n\n[Override model IDs per version](/docs/en/model-config#override-model-ids-per-version)`{\"claude-opus-4-6\": \"arn:aws:bedrock:...\"}`\n\n`otelHeadersHelper`\n\n[. See](/docs/en/env-vars)`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`\n\n[Dynamic headers](/docs/en/monitoring-usage#dynamic-headers)`/bin/generate_otel_headers.sh`\n\n`outputStyle`\n\n[output styles documentation](/docs/en/output-styles)`\"Explanatory\"`\n\n`parentSettingsBehavior`\n\n`\"first-wins\"`\n\n: the parent-supplied settings are dropped and only the admin tier applies. `\"merge\"`\n\n: 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\"`\n\n. Requires Claude Code v2.1.133 or later`\"merge\"`\n\n`permissions`\n\n`plansDirectory`\n\n`~/.claude/plans`\n\n`\"./plans\"`\n\n`pluginSuggestionMarketplaces`\n\n`relevance`\n\ndeclaration 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`\n\nentry for that name or as an entry of `strictKnownMarketplaces`\n\n. 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\"]`\n\n`pluginTrustMessage`\n\n`\"All plugins from our marketplace are approved by IT\"`\n\n`policyHelper`\n\n`managed-settings.json`\n\nfile. 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\"}`\n\n`preferredNotifChannel`\n\n`\"auto\"`\n\n, `\"terminal_bell\"`\n\n, `\"iterm2\"`\n\n, `\"iterm2_with_bell\"`\n\n, `\"kitty\"`\n\n, `\"ghostty\"`\n\n, or `\"notifications_disabled\"`\n\n. Default: `\"auto\"`\n\n, which sends a desktop notification in iTerm2, Ghostty, and Kitty and does nothing in other terminals. Set `\"terminal_bell\"`\n\nto ring the bell character in any terminal. Appears in `/config`\n\nas **Notifications**. See[Get a terminal bell or notification](/docs/en/terminal-config#get-a-terminal-bell-or-notification)`\"terminal_bell\"`\n\n`prefersReducedMotion`\n\n`true`\n\n`prUrlTemplate`\n\n`{host}`\n\n, `{owner}`\n\n, `{repo}`\n\n, `{number}`\n\n, and `{url}`\n\nfrom the `gh`\n\n-reported PR URL. Use to point PR links at an internal code-review tool instead of `github.com`\n\n. Does not affect `#123`\n\nautolinks in Claude’s prose`\"https://reviews.example.com/{owner}/{repo}/pull/{number}\"`\n\n`requiredMaximumVersion`\n\n`claude install <version>`\n\nmay also work. Background auto-updates and `claude update`\n\nskip versions above the ceiling, so an in-range installation stays in range. `claude update`\n\n, `claude install`\n\n, and `claude doctor`\n\nkeep working above the ceiling so users can recover. Versions that predate this setting ignore it`\"2.1.150\"`\n\n`requiredMinimumVersion`\n\n`claude update`\n\n, `claude install`\n\n, and `claude doctor`\n\nkeep working below the floor so users can recover. Differs from `minimumVersion`\n\n, which prevents downgrades but never blocks startup. Versions that predate this setting ignore it`\"2.1.150\"`\n\n`respectGitignore`\n\n`@`\n\nfile picker respects `.gitignore`\n\npatterns. When `true`\n\n(default), files matching `.gitignore`\n\npatterns are excluded from suggestions`false`\n\n`showClearContextOnPlanAccept`\n\n`false`\n\n. Set to `true`\n\nto restore the option`true`\n\n`showThinkingSummaries`\n\n[extended thinking](/docs/en/model-config#extended-thinking)summaries in interactive sessions. When unset or`false`\n\n(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`\n\n), the Agent SDK, or IDE extensions such as VS Code`true`\n\n`showTurnDuration`\n\n`true`\n\n. Appears in `/config`\n\nas **Show turn duration**`false`\n\n`skillListingBudgetFraction`\n\n[skill listing](/docs/en/skills#skill-descriptions-are-cut-short)Claude sees each turn (default:`0.01`\n\n= 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`\n\nshows the current truncation count and which skills are affected. Requires Claude Code v2.1.105 or later`0.02`\n\n`skillOverrides`\n\n`\"on\"`\n\n, `\"name-only\"`\n\n, `\"user-invocable-only\"`\n\n, or `\"off\"`\n\n. Lets you hide or collapse a skill without editing its SKILL.md. Does not apply to plugin skills, which are managed through `/plugin`\n\n. The `/skills`\n\nmenu writes these to `.claude/settings.local.json`\n\n. 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\"}`\n\n`skipWebFetchPreflight`\n\n[WebFetch domain safety check](/docs/en/data-usage#webfetch-domain-safety-check)that sends each requested hostname to`api.anthropic.com`\n\nbefore fetching. Set to `true`\n\nin 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`\n\n`spinnerTipsEnabled`\n\n`false`\n\nto disable tips (default: `true`\n\n)`false`\n\n`spinnerTipsOverride`\n\n`tips`\n\n: array of tip strings. `excludeDefault`\n\n: if `true`\n\n, only show custom tips; if `false`\n\nor absent, custom tips are merged with built-in tips`{ \"excludeDefault\": true, \"tips\": [\"Use our internal tool X\"] }`\n\n`spinnerVerbs`\n\n`mode`\n\nto `\"replace\"`\n\nto use only your verbs, or `\"append\"`\n\nto add them to the defaults`{\"mode\": \"append\", \"verbs\": [\"Pondering\", \"Crafting\"]}`\n\n`sshConfigs`\n\n[Desktop](/docs/en/desktop#pre-configure-ssh-connections-for-your-team)environment dropdown. Each entry requires`id`\n\n, `name`\n\n, and `sshHost`\n\n; `sshPort`\n\n, `sshIdentityFile`\n\n, and `startDirectory`\n\nare 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\"}]`\n\n`statusLine`\n\n`statusLine`\n\ndocumentation`{\"type\": \"command\", \"command\": \"~/.claude/statusline.sh\"}`\n\n`strictKnownMarketplaces`\n\n[Managed marketplace restrictions](/docs/en/plugin-marketplaces#managed-marketplace-restrictions)`[{ \"source\": \"github\", \"repo\": \"acme-corp/plugins\" }]`\n\n`strictPluginOnlyCustomization`\n\n`true`\n\nlocks all four surfaces; an array locks only the named ones. See `strictPluginOnlyCustomization`\n\n`[\"skills\", \"hooks\"]`\n\n`syntaxHighlightingDisabled`\n\n`true`\n\n`teammateMode`\n\n[agent team](/docs/en/agent-teams)teammates display:`auto`\n\n(split panes when running inside tmux or iTerm2, in-process otherwise), `in-process`\n\n, or `tmux`\n\n(split panes using tmux or iTerm2, detected from your terminal). `--teammate-mode`\n\noverrides this for one session. See [choose a display mode](/docs/en/agent-teams#choose-a-display-mode)`\"in-process\"`\n\n`terminalProgressBarEnabled`\n\n`true`\n\n. Appears in `/config`\n\nas **Terminal progress bar**`false`\n\n`theme`\n\n`\"auto\"`\n\n, `\"dark\"`\n\n, `\"light\"`\n\n, `\"dark-daltonized\"`\n\n, `\"light-daltonized\"`\n\n, `\"dark-ansi\"`\n\n, `\"light-ansi\"`\n\n, or a custom theme reference such as `\"custom:<slug>\"`\n\nor `\"custom:<plugin-name>:<slug>\"`\n\n. Default: `\"dark\"`\n\n. See [Create a custom theme](/docs/en/terminal-config#create-a-custom-theme). Appears in`/config`\n\nas **Theme**`\"dark\"`\n\n`tui`\n\n`\"fullscreen\"`\n\nfor the flicker-free [alt-screen renderer](/docs/en/fullscreen)with virtualized scrollback. Use`\"default\"`\n\nfor the classic main-screen renderer. Set via `/tui`\n\n. You can also set the [environment variable. Background sessions opened from](/docs/en/env-vars)`CLAUDE_CODE_NO_FLICKER`\n\n[agent view](/docs/en/agent-view)always use the fullscreen renderer regardless of this setting`\"fullscreen\"`\n\n`ultracode`\n\n[ultracode](/docs/en/workflows#let-claude-decide-with-ultracode)for the session. Session-only and not read from`settings.json`\n\n. Set through `/effort ultracode`\n\n, `--settings`\n\n, or an Agent SDK control request`true`\n\n`useAutoModeDuringPlan`\n\n`true`\n\n. Not read from shared project settings. Appears in `/config`\n\nas “Use auto mode during plan”`false`\n\n`verbose`\n\n`false`\n\n. Appears in `/config`\n\nas **Verbose output**. The`--verbose`\n\nflag overrides this for one session`true`\n\n`viewMode`\n\n`\"default\"`\n\n, `\"verbose\"`\n\n, or `\"focus\"`\n\n. Overrides the sticky `/focus`\n\nselection when set. The `--verbose`\n\nflag overrides this for one session`\"verbose\"`\n\n`voice`\n\n[Voice dictation](/docs/en/voice-dictation)settings:`enabled`\n\nturns dictation on, `mode`\n\nselects `\"hold\"`\n\nor `\"tap\"`\n\n, and `autoSubmit`\n\nsends the prompt on key release in hold mode. Written automatically when you run `/voice`\n\n. Requires a Claude.ai account`{ \"enabled\": true, \"mode\": \"tap\" }`\n\n`voiceEnabled`\n\n`voice.enabled`\n\n. Prefer the `voice`\n\nobject`true`\n\n`wheelScrollAccelerationEnabled`\n\n[fullscreen rendering](/docs/en/fullscreen#mouse-wheel-scrolling), accelerate mouse-wheel scroll speed during fast scrolls. Default:`true`\n\n. Set to `false`\n\nfor a constant scroll rate per wheel notch. Requires Claude Code v2.1.174 or later`false`\n\n`workflowKeywordTriggerEnabled`\n\n`ultracode`\n\nin a prompt triggers a [dynamic workflow](/docs/en/workflows#ask-for-a-workflow-in-your-prompt). Set to`false`\n\nto type the word without triggering one. The `ultracode`\n\neffort setting, `/workflows`\n\n, and saved workflow commands are unaffected. Default: `true`\n\n. Appears in `/config`\n\nas **Ultracode keyword trigger**. Added in v2.1.157; before v2.1.160 the trigger keyword was`workflow`\n\n`false`\n\n`wslInheritsWindowsSettings`\n\n`true`\n\n, Claude Code on WSL reads managed settings from the Windows policy chain in addition to `/etc/claude-code`\n\n, with Windows sources taking priority. Only honored when set in the HKLM registry key or `C:\\Program Files\\ClaudeCode\\managed-settings.json`\n\n, 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`\n\n### Global config settings\n\nThese settings are stored in`~/.claude.json`\n\nrather than `settings.json`\n\n. Adding them to `settings.json`\n\nwill trigger a schema validation error.\nVersions before v2.1.119 also store a number of\n\n`/config`\n\npreference keys here instead of in `settings.json`\n\n, including `theme`\n\n, `verbose`\n\n, `editorMode`\n\n, `autoCompactEnabled`\n\n, and `preferredNotifChannel`\n\n.| Key | Description | Example |\n|---|---|---|\n`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\n`CLAUDE_CODE_AUTO_CONNECT_IDE` | `true` |\n`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\n`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | `false` |\n`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` |\n`teammateDefaultModel` | Default model for\n`\"sonnet\"` , or `null` to inherit the lead’s current `/model` selection. Appears in `/config` as Default teammate model |\n\n`\"sonnet\"`\n\n### Worktree settings\n\nConfigure how`--worktree`\n\ncreates and manages git worktrees.\n| Key | Description | Example |\n|---|---|---|\n`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\"` |\n`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\"]` |\n`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\"]` |\n`worktree.bgIsolation` | Isolation mode for\n`\"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 |\n\n`\"none\"`\n\n`.env`\n\ninto new worktrees, use a [in your project root instead of a setting.](/docs/en/worktrees#copy-gitignored-files-into-worktrees)\n\n`.worktreeinclude`\n\nfile### Permission settings\n\n| Keys | Description | Example |\n|---|---|---|\n`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\n| `[ \"Bash(git diff *)\" ]` |\n`ask` | Array of permission rules to ask for confirmation upon tool use. See\n|\n\n`[ \"Bash(git push *)\" ]`\n\n`deny`\n\n`\"*\"`\n\ndenies every tool and `\"mcp__*\"`\n\ndenies 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/**)\" ]`\n\n`additionalDirectories`\n\n[working directories](/docs/en/permissions#working-directories)for file access. Most`.claude/`\n\nconfiguration is [not discovered](/docs/en/permissions#additional-directories-grant-file-access-not-configuration)from these directories`[ \"../docs/\" ]`\n\n`defaultMode`\n\n[permission mode](/docs/en/permission-modes)when opening Claude Code. Valid values:`default`\n\n, `acceptEdits`\n\n, `plan`\n\n, `auto`\n\n, `dontAsk`\n\n, `bypassPermissions`\n\n. As of Claude Code v2.1.142, `auto`\n\nis ignored when set in project or local settings (`.claude/settings.json`\n\n, `.claude/settings.local.json`\n\n) so a repository cannot grant itself auto mode. Set it in `~/.claude/settings.json`\n\ninstead. The `--permission-mode`\n\nCLI flag overrides this setting for a single session`\"acceptEdits\"`\n\n`disableBypassPermissionsMode`\n\n`\"disable\"`\n\nto prevent `bypassPermissions`\n\nmode from being activated. This disables the `--dangerously-skip-permissions`\n\ncommand-line flag. Typically placed in [managed settings](/docs/en/permissions#managed-settings)to enforce organizational policy, but works from any scope`\"disable\"`\n\n`skipDangerousModePermissionPrompt`\n\n`--dangerously-skip-permissions`\n\nor `defaultMode: \"bypassPermissions\"`\n\n. Ignored when set in project settings (`.claude/settings.json`\n\n) to prevent untrusted repositories from auto-bypassing the prompt`true`\n\n### Permission rule syntax\n\nPermission rules follow the format`Tool`\n\nor `Tool(specifier)`\n\n. 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:\n\n| Rule | Effect |\n|---|---|\n`Bash` | Matches all Bash commands |\n`Bash(npm run *)` | Matches commands starting with `npm run` |\n`Read(./.env)` | Matches reading the `.env` file |\n`WebFetch(domain:example.com)` | Matches fetch requests to example.com |\n\n[Permission rule syntax](/docs/en/permissions#permission-rule-syntax).\n\n### Sandbox settings\n\nConfigure advanced sandboxing behavior. Sandboxing isolates bash commands from your filesystem and network. See[Sandboxing](/docs/en/sandboxing)for details.\n\n| Keys | Description | Example |\n|---|---|---|\n`enabled` | Enable bash sandboxing (macOS, Linux, and WSL2). Default: false | `true` |\n`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` |\n`autoAllowBashIfSandboxed` | Auto-approve bash commands when sandboxed. Default: true | `true` |\n`excludedCommands` | Commands that should run outside of the sandbox | `[\"docker *\"]` |\n`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` |\n`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\n| `[\"/tmp/build\", \"~/.kube\"]` |\n`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\"]` |\n`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\"]` |\n`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. | `[\".\"]` |\n`filesystem.allowManagedReadPathsOnly` | (Managed settings only) Only `filesystem.allowRead` paths from managed settings are respected. `denyRead` still merges from all sources. Default: false | `true` |\n`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\"]` |\n`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` |\n`network.allowLocalBinding` | Allow binding to localhost ports (macOS only). Default: false | `true` |\n`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.*\"]` |\n`network.allowedDomains` | Array of domains to allow for outbound network traffic. Supports wildcards (e.g., `*.example.com` ). | `[\"github.com\", \"*.npmjs.org\"]` |\n`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\"]` |\n`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` |\n`network.httpProxyPort` | HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8080` |\n`network.socksProxyPort` | SOCKS5 proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8081` |\n`enableWeakerNestedSandbox` | Enable weaker sandbox for unprivileged Docker environments (Linux and WSL2 only). Reduces security. Default: false | `true` |\n`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` |\n`bwrapPath` | (Managed settings only, Linux/WSL2) Absolute path to the bubblewrap (`bwrap` ) binary. Overrides automatic detection via `PATH` . Only honored from\n`bwrap` is installed at a non-standard location in managed environments. | `/opt/admin/bwrap` |\n`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` |\n\n#### Sandbox path prefixes\n\nPaths in`filesystem.allowWrite`\n\n, `filesystem.denyWrite`\n\n, `filesystem.denyRead`\n\n, and `filesystem.allowRead`\n\nsupport these prefixes:\n| Prefix | Meaning | Example |\n|---|---|---|\n`/` | Absolute path from filesystem root | `/tmp/build` stays `/tmp/build` |\n`~/` | Relative to home directory | `~/.kube` becomes `$HOME/.kube` |\n`./` 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` |\n\n`//path`\n\nprefix for absolute paths still works. If you previously used single-slash `/path`\n\nexpecting project-relative resolution, switch to `./path`\n\n. This syntax differs from [Read and Edit permission rules](/docs/en/permissions#read-and-edit), which use\n\n`//path`\n\nfor absolute and `/path`\n\nfor project-relative. Sandbox filesystem paths use standard conventions: `/tmp/build`\n\nis an absolute path.\n**Configuration example:**\n\n**Filesystem and network restrictions** can be configured in two ways that are merged together:\n\n(shown above): Control paths at the OS-level sandbox boundary. These restrictions apply to all subprocess commands (e.g.,`sandbox.filesystem`\n\nsettings`kubectl`\n\n,`terraform`\n\n,`npm`\n\n), not just Claude’s file tools.**Permission rules**: Use`Edit`\n\nallow/deny rules to control Claude’s file tool access,`Read`\n\ndeny rules to block reads, and`WebFetch`\n\nallow/deny rules to control network domains. Paths from these rules are also merged into the sandbox configuration.\n\n### Attribution settings\n\nClaude Code adds attribution to git commits and pull requests. These are configured separately:- Commits use\n[git trailers](https://git-scm.com/docs/git-interpret-trailers)(like`Co-Authored-By`\n\n) by default, which can be customized or disabled - Pull request descriptions are plain text\n\n| Keys | Description |\n|---|---|\n`commit` | Attribution for git commits, including any trailers. Empty string hides commit attribution |\n`pr` | Attribution for pull request descriptions. Empty string hides pull request attribution |\n\n**Default commit attribution:**\n\n**Default pull request attribution:**\n\n**Example:**\n\nThe\n\n`attribution`\n\nsetting takes precedence over the deprecated `includeCoAuthoredBy`\n\nsetting. To hide all attribution, set `commit`\n\nand `pr`\n\nto empty strings.### File suggestion settings\n\nConfigure a custom command for`@`\n\nfile 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.\n[hooks](/docs/en/hooks), including\n\n`CLAUDE_PROJECT_DIR`\n\n. It receives JSON via stdin with a `query`\n\nfield:\n**Example:**\n\n### Footer link badges\n\nThe`footerLinksRegexes`\n\nsetting 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.\nEach entry’s `pattern`\n\nregex is matched against turn output: tool results, including file contents and fetched pages, and Claude’s own responses. `{name}`\n\nplaceholders in `url`\n\nand `label`\n\nare filled from named capture groups in the pattern.\nThe following example renders a badge whenever an issue key like `PROJ-1234`\n\nappears in turn output. The `(?<key>...)`\n\nnamed group captures the key, and `{key}`\n\nsubstitutes it into the URL and label:\n~/.claude/settings.json\n\n`PROJ-1234`\n\nappears in a tool result or in Claude’s reply, a `PROJ-1234`\n\nchip appears in the footer linking to `https://issues.example.com/browse/PROJ-1234`\n\n.\nThe following constraints apply to each entry:\n| Constraint | Behavior |\n|---|---|\n| 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 |\n| URL length | Constructed URLs longer than 2048 characters are dropped |\n| 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` |\n| Label | Defaults to the matched text and is truncated to 28 display columns |\n| Badge count | At most 5 badges render. The oldest is displaced by newer matches and `/clear` removes them |\n| 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` |\n\n`pattern`\n\nregex against the turn output on the main thread, so a slow regex blocks the UI until it finishes. Nested quantifiers such as `(a+)+$`\n\ncan take exponentially long against certain inputs and freeze the session, so keep each `pattern`\n\nlinear and avoid nesting `+`\n\nor `*`\n\n.\nFooter 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.\n\n### Hook configuration\n\nThese settings control which hooks are allowed to run and what HTTP hooks can access. The`allowManagedHooksOnly`\n\nsetting 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.\n\n**Behavior when**\n\n`allowManagedHooksOnly`\n\nis `true`\n\n:- Managed hooks and SDK hooks are loaded\n- Hooks from plugins force-enabled in managed settings\n`enabledPlugins`\n\nare loaded. This lets administrators distribute vetted hooks through an organization marketplace while blocking everything else. Trust is granted by full`plugin@marketplace`\n\nID, so a plugin with the same name from a different marketplace stays blocked - User hooks, project hooks, and all other plugin hooks are blocked\n\n**Restrict HTTP hook URLs:** Limit which URLs HTTP hooks can target. Supports\n\n`*`\n\nas 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.\n**Restrict HTTP hook environment variables:** Limit which environment variable names HTTP hooks can interpolate into header values. Each hook’s effective\n\n`allowedEnvVars`\n\nis the intersection of its own list and this setting.\n### Compute managed settings with a policy helper\n\nThe`policyHelper`\n\nsetting 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`\n\nfile. Claude Code ignores `policyHelper`\n\nwhen 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:\n\n| Key | Type | Description |\n|---|---|---|\n`path` | string | Absolute path to the helper executable |\n`timeoutMs` | number | How long to wait for the helper before treating the run as failed |\n`refreshIntervalMs` | number | How often to re-run the helper in the background. Set to `0` to disable refresh, or to at least `60000` |\n\n`managedSettings`\n\nkey rather than at the top level, since a bare settings object parses with `managedSettings`\n\nundefined and applies nothing:\n`managedSettings`\n\n, 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`\n\n.\n### Settings precedence\n\nSettings apply in order of precedence. From highest to lowest:-\n**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\n- Cannot be overridden by any other level, including command line arguments\n- Within the managed tier, precedence is: server-managed > MDM/OS-level policies > file-based (\n`managed-settings.d/*.json`\n\n+`managed-settings.json`\n\n) > 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\n`managedSettings`\n\noption. By default this is ignored when any managed-settings tier is present. Administrators can opt in by settingto`parentSettingsBehavior`\n\n`\"merge\"`\n\n. The embedder’s values are filtered so they can tighten managed policy but not loosen it.\n\n-\n**Command line arguments**- Temporary overrides for a specific session. JSON passed via\n`--settings <file-or-json>`\n\nmerges 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\n\n- Temporary overrides for a specific session. JSON passed via\n-\n**Local project settings**(`.claude/settings.local.json`\n\n)- Personal project-specific settings\n\n-\n**Shared project settings**(`.claude/settings.json`\n\n)- Team-shared project settings in source control\n\n-\n**User settings**(`~/.claude/settings.json`\n\n)- Personal global settings\n\n[VS Code extension](/docs/en/vs-code), or a\n\n[JetBrains IDE](/docs/en/jetbrains). For example, if your user settings set\n\n`permissions.defaultMode`\n\nto `acceptEdits`\n\nand a project’s shared settings set it to `default`\n\n, the project value applies. The example below covers how array-valued settings such as permission rules combine instead.\n**Array settings merge across scopes.** When the same array-valued setting (such as\n\n`sandbox.filesystem.allowWrite`\n\nor `permissions.allow`\n\n) 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\n\n`allowWrite`\n\nto `[\"/opt/company-tools\"]`\n\nand a user adds `[\"~/.kube\"]`\n\n, 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)\n\n`fallbackModel`\n\n[value replaces lower-precedence entries entirely. See](#available-settings)\n\n`availableModels`\n\n[Merge behavior](/docs/en/model-config#merge-behavior).\n\n### Verify active settings\n\nRun`/status`\n\ninside Claude Code to see which settings sources are active. Inside the menu, the **Status** tab includes a\n\n`Setting sources`\n\nline that lists each layer Claude Code loaded for the current session, such as `User settings`\n\nor `Project local settings`\n\n. 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\n\n`Enterprise managed settings (remote)`\n\n, `(plist)`\n\n, `(HKLM)`\n\n, `(HKCU)`\n\n, or `(file)`\n\n. 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.\nThe `Setting sources`\n\nline 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\n\n`settings.json`\n\ncontents.\nIf 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`\n\nlists the affected files. Run `/doctor`\n\nto see the details for each error.\n### Key points about the configuration system\n\n**Memory files (**: Contain instructions and context that Claude loads at startup`CLAUDE.md`\n\n)**Settings files (JSON)**: Configure permissions, environment variables, and tool behavior** Skills**: Custom prompts that can be invoked with`/skill-name`\n\nor 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`\n\n, where the highest-precedence scope supplies the whole chain, and`availableModels`\n\n, where a managed or policy value replaces lower-precedence entries\n\n### System prompt\n\nClaude Code’s internal system prompt is not published. To add custom instructions, use`CLAUDE.md`\n\nfiles or the `--append-system-prompt`\n\nflag.\n### Excluding sensitive files\n\nTo prevent Claude Code from accessing files containing sensitive information like API keys, secrets, and environment files, use the`permissions.deny`\n\nsetting in your `.claude/settings.json`\n\nfile:\n`ignorePatterns`\n\nconfiguration. Files matching these patterns are excluded from file discovery and search results, and read operations on these files are denied.\n## Subagent configuration\n\nClaude 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/`\n\n- Available across all your projects**Project subagents**:`.claude/agents/`\n\n- Specific to your project and can be shared with your team\n\n[subagents documentation](/docs/en/sub-agents).\n\n## Plugin configuration\n\nClaude 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\n\nPlugin-related settings in`settings.json`\n\n:\n`enabledPlugins`\n\nControls which plugins are enabled. Format: `\"plugin-name@marketplace-name\": true/false`\n\n. A plugin with no entry at any scope falls back to its [value.](/docs/en/plugins-reference#default-enablement)\n\n`defaultEnabled`\n\n**Scopes**:\n\n**User settings**(`~/.claude/settings.json`\n\n): Personal plugin preferences**Project settings**(`.claude/settings.json`\n\n): Project-specific plugins shared with team**Local settings**(`.claude/settings.local.json`\n\n): Per-machine overrides, gitignored when Claude Code creates it**Managed settings**(`managed-settings.json`\n\n): Organization-wide policy overrides that block installation at all scopes and hide the plugin from the marketplace\n\nProject settings take precedence over user settings, so setting a plugin to\n\n`false`\n\nin `~/.claude/settings.json`\n\ndoes not disable a plugin that the project’s `.claude/settings.json`\n\nenables. To opt out of a project-enabled plugin on your machine, set it to `false`\n\nin `.claude/settings.local.json`\n\ninstead.Plugins force-enabled by managed settings cannot be disabled this way, since managed settings override local settings.**Example**:\n\n`extraKnownMarketplaces`\n\nDefines 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.\n**When a repository includes**:\n\n`extraKnownMarketplaces`\n\n- Team members are prompted to install the marketplace when they trust the folder\n- Team members are then prompted to install plugins from that marketplace\n- Users can skip unwanted marketplaces or plugins (stored in user settings)\n- Installation respects trust boundaries and requires explicit consent\n\n**Example**:\n\n**Marketplace source types**:\n\n`github`\n\n: GitHub repository (uses`repo`\n\n)`git`\n\n: Any git URL (uses`url`\n\n)`directory`\n\n: Local filesystem path (uses`path`\n\n, for development only)`hostPattern`\n\n: regex pattern to match marketplace hosts (uses`hostPattern`\n\n)`settings`\n\n: inline marketplace declared directly in settings.json without a separate hosted repository (uses`name`\n\nand`plugins`\n\n)\n\n`git`\n\nsource 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`\n\nwould 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\n\n`github`\n\nand `git`\n\nsources, set `\"skipLfs\": true`\n\ninside the `source`\n\nobject (alongside `repo`\n\nor `url`\n\n) 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.\nEach marketplace entry also accepts an optional `autoUpdate`\n\nBoolean. Set `\"autoUpdate\": true`\n\nalongside `source`\n\nto make Claude Code refresh that marketplace and update its installed plugins at startup. When omitted, official Anthropic marketplaces default to `true`\n\nand all other marketplaces default to `false`\n\n. See [Configure auto-updates](/docs/en/discover-plugins#configure-auto-updates). Use\n\n`source: 'settings'`\n\nto 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`\n\n.\n`strictKnownMarketplaces`\n\n**Managed settings only**: Controls which plugin marketplaces users are allowed to add and install plugins from. This setting can only be configured in\n\n[managed settings](/docs/en/settings#settings-files)and provides administrators with strict control over marketplace sources.\n\n**Managed settings file locations**:\n\n**macOS**:`/Library/Application Support/ClaudeCode/managed-settings.json`\n\n**Linux and WSL**:`/etc/claude-code/managed-settings.json`\n\n**Windows**:`C:\\Program Files\\ClaudeCode\\managed-settings.json`\n\n**Key characteristics**:\n\n- Only available in managed settings (\n`managed-settings.json`\n\n) - Cannot be overridden by user or project settings (highest precedence)\n- Enforced BEFORE network/filesystem operations (blocked sources never execute)\n- Uses exact matching for source specifications (including\n`ref`\n\n,`path`\n\nfor git sources), except`hostPattern`\n\nand`pathPattern`\n\n, which use regex matching\n\n**Allowlist behavior**:\n\n`undefined`\n\n(default): No restrictions - users can add any marketplace- Empty array\n`[]`\n\n: Complete lockdown - users cannot add any new marketplaces - List of sources: Users can only add marketplaces that match exactly\n\n**All supported source types**: The allowlist supports multiple marketplace source types. Most sources use exact matching, while\n\n`hostPattern`\n\nand `pathPattern`\n\nuse regex matching against the marketplace host and filesystem path respectively.\n**GitHub repositories**:\n\n`repo`\n\n(required), `ref`\n\n(optional: branch/tag/SHA), `path`\n\n(optional: subdirectory)\n**Git repositories**:\n\n`url`\n\n(required), `ref`\n\n(optional: branch/tag/SHA), `path`\n\n(optional: subdirectory)\n**URL-based marketplaces**:\n\n`url`\n\n(required), `headers`\n\n(optional: HTTP headers for authenticated access)\nURL-based marketplaces only download the\n\n`marketplace.json`\n\nfile. 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**:\n\n`package`\n\n(required, supports scoped packages)\n**File paths**:\n\n`path`\n\n(required: absolute path to marketplace.json file)\n**Directory paths**:\n\n`path`\n\n(required: absolute path to directory containing `.claude-plugin/marketplace.json`\n\n)\n**Host pattern matching**:\n\n`hostPattern`\n\n(required: regex pattern to match against the marketplace host)\nUse 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.\nHost extraction by source type:\n`github`\n\n: always matches against`github.com`\n\n`git`\n\n: extracts hostname from the URL (supports both HTTPS and SSH formats)`url`\n\n: extracts hostname from the URL`npm`\n\n,`file`\n\n,`directory`\n\n: not supported for host pattern matching\n\n**Path pattern matching**:\n\n`pathPattern`\n\n(required: regex pattern matched against the `path`\n\nfield of `file`\n\nand `directory`\n\nsources)\nUse path pattern matching to allow filesystem-based marketplaces alongside `hostPattern`\n\nrestrictions for network sources. Set `\".*\"`\n\nto allow all local paths, or a narrower pattern to restrict to specific directories.\n**Configuration examples**: Example: allow specific marketplaces only:\n\n**Exact matching requirements**: Marketplace sources must match\n\n**exactly** for a user’s addition to be allowed. For git-based sources (\n\n`github`\n\nand `git`\n\n), this includes all optional fields:\n- The\n`repo`\n\nor`url`\n\nmust match exactly - The\n`ref`\n\nfield must match exactly (or both be undefined) - The\n`path`\n\nfield must match exactly (or both be undefined)\n\n**do NOT match**:\n\n**Comparison with**:\n\n`extraKnownMarketplaces`\n\n| Aspect | `strictKnownMarketplaces` | `extraKnownMarketplaces` |\n|---|---|---|\nPurpose | Organizational policy enforcement | Team convenience |\nSettings file | `managed-settings.json` only | Any settings file |\nBehavior | Blocks non-allowlisted additions | Auto-installs missing marketplaces |\nWhen enforced | Before network/filesystem operations | After user trust prompt |\nCan be overridden | No (highest precedence) | Yes (by higher precedence settings) |\nSource format | Direct source object | Named marketplace with nested source |\nUse case | Compliance, security restrictions | Onboarding, standardization |\n\n**Format difference**:\n\n`strictKnownMarketplaces`\n\nuses direct source objects:\n`extraKnownMarketplaces`\n\nrequires named marketplaces:\n**Using both together**:\n\n`strictKnownMarketplaces`\n\nis 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`\n\n:\n`strictKnownMarketplaces`\n\nset, users can still add the allowed marketplace manually via `/plugin marketplace add`\n\n, but it is not available automatically.\n**Important notes**:\n\n- Restrictions are checked BEFORE any network requests or filesystem operations\n- When blocked, users see clear error messages indicating the source is blocked by managed policy\n- 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\n- Managed settings have the highest precedence and cannot be overridden\n\n[Managed marketplace restrictions](/docs/en/plugin-marketplaces#managed-marketplace-restrictions)for user-facing documentation.\n\n`strictPluginOnlyCustomization`\n\n**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\n\n`strictKnownMarketplaces`\n\nto 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.\n`strictPluginOnlyCustomization`\n\nrequires 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`\n\nto lock all four surfaces, or an array naming the surfaces to lock:\n| Surface | Blocked when locked | Still loads |\n|---|---|---|\n`skills` | `~/.claude/skills/` , `.claude/skills/` | Plugin skills, bundled skills, skills in the managed policy directory |\n`agents` | `~/.claude/agents/` , `.claude/agents/` | Plugin agents, built-in agents, agents in the managed policy directory |\n`hooks` | Hooks in user, project, and local `settings.json` | Plugin hooks, hooks in managed settings |\n`mcp` | Servers in `~/.claude.json` and `.mcp.json` | Plugin MCP servers,\n`managed-mcp.json` |\n\n### Managing plugins\n\nUse the`/plugin`\n\ncommand to manage plugins interactively:\n- Browse available plugins from marketplaces\n- Install/uninstall plugins\n- Enable/disable plugins\n- View plugin details (skills, agents, hooks provided)\n- Add/remove marketplaces\n\n[plugins documentation](/docs/en/plugins).\n\n## Environment variables\n\nEnvironment variables let you control Claude Code behavior without editing settings files. Any variable can also be configured in[under the](#available-settings)\n\n`settings.json`\n\n`env`\n\nkey to apply it to every session or roll it out to your team.\nSee the [environment variables reference](/docs/en/env-vars)for the full list.\n\n## Tools available to Claude\n\nClaude 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.\n\n## See also\n\n[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", "url": "https://wpnews.pro/news/claude-code-sessions-erase-after-30-days-by-default", "canonical_source": "https://code.claude.com/docs/en/settings", "published_at": "2026-06-17 15:05:48+00:00", "updated_at": "2026-06-17 15:23:01.262502+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-products"], "entities": ["Anthropic", "Claude Code"], "alternates": {"html": "https://wpnews.pro/news/claude-code-sessions-erase-after-30-days-by-default", "markdown": "https://wpnews.pro/news/claude-code-sessions-erase-after-30-days-by-default.md", "text": "https://wpnews.pro/news/claude-code-sessions-erase-after-30-days-by-default.txt", "jsonld": "https://wpnews.pro/news/claude-code-sessions-erase-after-30-days-by-default.jsonld"}}