Claude Code sessions erase after 30 days by default

/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 ascope 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.

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 #

Thesettings.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. Seeserver-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 mirrormanaged-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 aSettings

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

andmanaged-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 alongsidemanaged-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 example10-telemetry.json

and20-security.json

. - macOS:

managed settingsandManaged MCP configurationfor details. Thisrepositoryincludes 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 restrictplugin marketplace additions usingstrictKnownMarketplaces

. For more information, seeManaged marketplace restrictions. - #

Other configuration is stored in~/.claude.json

. This file contains your OAuth session,MCP serverconfigurations 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 schemafor 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 includespermissions

, 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:

ConfigChange

hookmodel

: useto switch mid-session/model

: part of the system prompt, which is rebuilt onoutputStyle

/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, 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"code-reviewer"

agentPushNotifEnabled

Remote Controlis 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. SeeMobile push notifications. Requires Claude Code v2.1.119 or latertrue

allowAllClaudeAiMcps

managed-mcp.json

, which otherwise takes exclusive control and suppresses them. See Managed MCP configurationtrue

allowedChannelPlugins

channelsEnabled: true

. See 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["https://hooks.example.com/*"]

allowedMcpServers

Managed MCP configuration[{ "serverName": "github" }]

allowManagedHooksOnly

enabledPlugins

are loaded. User, project, and all other plugin hooks are blocked. See Hook configurationtrue

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 configurationtrue

allowManagedPermissionRulesOnly

allow

, ask

, or deny

permission rules. Only rules in managed settings apply. See Managed-only settingstrue

alwaysThinkingEnabled

extended thinkingby default for all sessions. Typically configured via the/config

command rather than editing directly. To force thinking off regardless of this setting, set inMAX_THINKING_TOKENS=0

env

, which disables thinking on the Anthropic API except on Fable 5, which cannot have thinking turned off. On third-party providersthis omits thethinking

parameter instead, and adaptive-reasoning models may still thinktrue

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{"commit": "🤖 Generated with Claude Code", "pr": ""}

autoCompactEnabled

true

. Appears in /config

as Auto-compact. To disable via environment variable, setinDISABLE_AUTO_COMPACT

env

false

autoMemoryDirectory

auto memorystorage. 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. Whenfalse

, 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 inCLAUDE_CODE_DISABLE_AUTO_MEMORY

env

false

autoMode

auto modeclassifier blocks and allows. Containsenvironment

, 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. Not read from shared project settings{"soft_deny": ["$defaults", "Never run terraform apply"]}

autoScrollEnabled

fullscreen rendering, 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 offfalse

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 inDISABLE_AUTOUPDATER

env

"stable"

availableModels

subagents, and theadvisor. SeeRestrict model selection. SeeenforceAvailableModels

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)aws sso login --profile myprofile

awsCredentialExport

advanced credential configuration)/bin/generate_aws_grant.sh

blockedMarketplaces

Managed marketplace restrictions[{ "source": "github", "repo": "untrusted/plugins" }]

channelsEnabled

channelsfor the organization. On claude.ai Team and Enterprise plans, channels are blocked when this is unset orfalse

. For Anthropic Consoleaccounts using API key authentication, channels are allowed by default unless your organization deploys managed settings, in which case this key must be set totrue

true

claudeMd

organization-wide CLAUDE.md"Always run make lint before committing."

claudeMdExcludes

CLAUDE.md

files to skip when 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 worktreesat startup. To disable transcript writes entirely, set theenvironment variable, or in non-interactive mode (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"powershell"

deniedMcpServers

Managed MCP configuration[{ "serverName": "filesystem" }]

disableAgentView

true

to turn off background agents and agent view:claude agents

, --bg

, /background

, and the on-demand supervisor. Typically set in managed settings. Equivalent to settingCLAUDE_CODE_DISABLE_AGENT_VIEW

to 1

true

disableAllHooks

hooksand any customstatus linetrue

disableAutoMode

"disable"

to prevent auto modefrom being activated. Removesauto

from the Shift+Tab

cycle and rejects --permission-mode auto

at startup. Most useful in managed settingswhere users cannot override it"disable"

disableBundledSkills

true

to disable the skillsand 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 linkslet 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: blocksclaude remote-control

, the --remote-control

flag, auto-start, and the in-session toggle. Typically placed in managed settingsfor per-device MDM enforcement, but works from any scope. Requires Claude Code v2.1.128 or latertrue

disableSkillShellExecution

!...``

and ````!`

blocks in skillsand 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 settingswhere users cannot override ittrue

disableWorkflows

dynamic workflowsand 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 levelacross 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. SeeCLAUDE_CODE_EFFORT_LEVEL

Adjust effort levelfor supported models"xhigh"

enableAllProjectMcpServers

.mcp.json

filestrue

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 selectionfor details and themerge behaviorwhenavailableModels

is set at multiple levels. Requires Claude Code v2.1.175 or latertrue

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--fallback-model

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

feedbackSurveyRate

session quality surveyappears when eligible. Set to0

to suppress entirely, or set inCLAUDE_CODE_DISABLE_FEEDBACK_SURVEY

env

. Useful when using Bedrock, Vertex, or Foundry where the default sample rate does not apply0.05

fileCheckpointingEnabled

can restore them. Default:/rewind

true

. Appears in /config

as Rewind code (checkpoints). To disable via environment variable, setinCLAUDE_CODE_DISABLE_FILE_CHECKPOINTING

env

false

fileSuggestion

@

file autocomplete. See 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 badgesfor 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 Anthropicclaudeai

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 enforcementtrue

gcpAuthRefresh

advanced credential configurationgcloud auth application-default login

hooks

hooks documentationfor formathookshttpHookAllowedEnvVars

allowedEnvVars

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

includeCoAuthoredBy

Deprecated: Useattribution

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 setfalse

inputNeededNotifEnabled

Remote Controlis 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. SeeMobile push notifications. Requires Claude Code v2.1.119 or latertrue

language

"japanese"

, "spanish"

, "french"

). Claude will respond in this language by default. Also sets the language for voice dictationand 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 listingClaude 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 laterskillListingBudgetFraction

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 settingsto pin an organization-wide minimum. For a hard floor that blocks startup entirely, seerequiredMinimumVersion

"2.1.100"

model

--model

and override this for one sessionANTHROPIC_MODEL

"claude-sonnet-4-6"

modelOverrides

Override model IDs per version{"claude-opus-4-6": "arn:aws:bedrock:..."}

otelHeadersHelper

. SeeCLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS

Dynamic headers/bin/generate_otel_headers.sh

outputStyle

output styles documentation"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. 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. SeeGet 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 suggestionsfalse

showClearContextOnPlanAccept

false

. Set to true

to restore the optiontrue

showThinkingSummaries

extended thinkingsummaries in interactive sessions. When unset orfalse

(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 thinkinginstead. This setting has no effect in non-interactive mode (-p

), the Agent SDK, or IDE extensions such as VS Codetrue

showTurnDuration

true

. Appears in /config

as Show turn durationfalse

skillListingBudgetFraction

skill listingClaude 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 later0.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. Requires Claude Code v2.1.129 or later{"legacy-context": "name-only", "deploy": "off"}

skipWebFetchPreflight

WebFetch domain safety checkthat sends each requested hostname toapi.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 blocklisttrue

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

Desktopenvironment dropdown. Each entry requiresid

, 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[{ "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 teamteammates 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"in-process"

terminalProgressBarEnabled

true

. Appears in /config

as Terminal progress barfalse

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. Appears in/config

as Theme"dark"

tui

"fullscreen"

for the flicker-free alt-screen rendererwith virtualized scrollback. Use"default"

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

. You can also set the environment variable. Background sessions opened fromCLAUDE_CODE_NO_FLICKER

agent viewalways use the fullscreen renderer regardless of this setting"fullscreen"

ultracode

ultracodefor the session. Session-only and not read fromsettings.json

. Set through /effort ultracode

, --settings

, or an Agent SDK control requesttrue

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 sessiontrue

viewMode

"default"

, "verbose"

, or "focus"

. Overrides the sticky /focus

selection when set. The --verbose

flag overrides this for one session"verbose"

voice

Voice dictationsettings: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

objecttrue

wheelScrollAccelerationEnabled

fullscreen rendering, 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 laterfalse

workflowKeywordTriggerEnabled

ultracode

in a prompt triggers a dynamic workflow. Set tofalse

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 wasworkflow

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 Windowstrue

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.

.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 syntaxandBash permission limitations[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]

additionalDirectories

working directoriesfor file access. Most.claude/

configuration is not discoveredfrom these directories[ "../docs/" ]

defaultMode

permission modewhen 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 settingsto 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 prompttrue

Permission rule syntax

Permission rules follow the formatTool

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

Sandbox settings

Configure advanced sandboxing behavior. Sandboxing isolates bash commands from your filesystem and network. SeeSandboxingfor 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 infilesystem.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, 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

settingskubectl

,terraform

,npm

), not just Claude’s file tools.Permission rules: UseEdit

allow/deny rules to control Claude’s file tool access,Read

deny rules to block reads, andWebFetch

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(likeCo-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, including

CLAUDE_PROJECT_DIR

. It receives JSON via stdin with a query

field: Example:

Footer link badges

ThefooterLinksRegexes

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 linewhen 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. TheallowManagedHooksOnly

setting can only be configured in managed settings. 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 fullplugin@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

ThepolicyHelper

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. 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,MDM/OS-level policies, ormanaged settings)- 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 settingtoparentSettingsBehavior

"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, or a

JetBrains IDE. 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

fallbackModel

value replaces lower-precedence entries entirely. See

availableModels

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 settingsare 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 startupCLAUDE.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 automaticallyMCP 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, andavailableModels

, 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, useCLAUDE.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 thepermissions.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 projectsProject subagents:.claude/agents/

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

subagents documentation.

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

defaultEnabled

Scopes:

User settings(~/.claude/settings.json

): Personal plugin preferencesProject settings(.claude/settings.json

): Project-specific plugins shared with teamLocal settings(.claude/settings.local.json

): Per-machine overrides, gitignored when Claude Code creates itManaged 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 (usesrepo

)git

: Any git URL (usesurl

)directory

: Local filesystem path (usespath

, for development only)hostPattern

: regex pattern to match marketplace hosts (useshostPattern

)settings

: inline marketplace declared directly in settings.json without a separate hosted repository (usesname

andplugins

)

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 repositoriesfor 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 down 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. 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 settingsand 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), excepthostPattern

andpathPattern

, 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 Troubleshootingfor 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 againstgithub.com

git

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

: extracts hostname from the URLnpm

,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

orurl

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

Environment variables #

Environment variables let you control Claude Code behavior without editing settings files. Any variable can also be configured inunder the

settings.json

env

key to apply it to every session or roll it out to your team. See the environment variables referencefor 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 thetools referencefor the full list and Bash tool behavior details.

See also #

Permissions: permission system, rule syntax, tool-specific patterns, and managed policiesAuthentication: set up user access to Claude CodeDebug your configuration: diagnose why a setting, hook, or MCP server isn’t taking effectTroubleshoot installation and login: installation, authentication, and platform issues

source & further reading

code.claude.com — original article