Settings schema reference
This page centralizes source-visible settings roots, policy keys, and configuration groups that shape Claude Code tools, prompts, integrations, hooks, sessions, and operations.
Scope and caveats
- This is a known-settings reference, not a complete JSON Schema dump. The complete schema is embedded in the minified bundle and may also be extended by plugins or managed policy.
- Settings names here are included when they are already anchored in implementation pages or are high-signal strings in
cli.renamed.js. - The ordinary effective-object order is plugin defaults → user → project → local → flag/SDK → policy.
--setting-sourcescontrols participation of user/project/local, not that order. Some sensitive keys deliberately use narrower resolvers.
Source anchors
| Semantic alias | String or symbol | Meaning |
|---|---|---|
| ProjectUserSettingsSchema | .claude/settings.json | Project/user settings overlay schema text. |
| TranscriptRetentionSetting | cleanupPeriodDays | Transcript retention setting. |
| ManagedUiPolicySettings | disableAllHooks, statusLine, disableAgentView | Managed settings/policy surfaces for hooks/status/agent view. |
| RemoteControlPolicySetting | disableRemoteControl | Managed policy surface for Remote Control. |
| SkillShellPolicySetting | disableSkillShellExecution | Managed policy surface for shell execution in skills/custom slash commands. |
| ApiKeyHelperSetting | apiKeyHelper | Settings helper script that outputs authentication values. |
| EmbeddedSettingsValidator | parseSettingsFileUncached(), r3().safeParse | Ordinary loaded settings are sanitized, then validated as a whole through the embedded schema ~72,420. |
| ManagedSettingsValidator | mSi() | Managed settings recover per key, with field-specific fail-closed behavior for selected policy controls ~71,679. |
| SettingsMergeOrder | SSi(), settingsMergeCustomizer() | Recursive low-to-high merge; arrays normally union while fallbackModel is replaced ~72,820. |
| EnabledPluginsSetting | enabledPlugins | Settings surface for plugin enablement and version constraints. |
| PluginConfigsSetting | pluginConfigs, MGr() | Plugin user options are read only from user, flag/SDK, and policy settings; project/local values do not participate ~227,482. |
| ExtraMarketplacesSetting | extraKnownMarketplaces | Settings surface for repository/team marketplace registration. |
| StrictMarketplacePolicy | strictKnownMarketplaces | Managed marketplace allowlist. |
| BlockedMarketplacePolicy | blockedMarketplaces | Managed marketplace blocklist. |
| SandboxOverridePolicy | dangerouslyDisableSandbox | Settings/policy schema text controlling sandbox override behavior. |
| StatusLineSettingsMutation | ~/.claude/settings.json | Status-line setup instructions mutate user settings. |
| StatusLineSchema | statusLine, refreshInterval, hideVimModeIndicator, subagentStatusLine | Main-line and agent-row command schemas ~71,080. |
| SettingsInjectionFlag | --settings <file-or-json> | Adds settings JSON file or inline JSON for a session. |
| IdeIntegrationFlag | --ide | Auto-connect IDE integration flag. |
| ChromeIntegrationFlag | --chrome | Chrome integration flag. |
| StartupFileResourceFlag | --file <specs...> | Startup file-resource download integration. |
| AccessibilitySetting | axScreenReader | Selects the screen-reader-friendly classic renderer; env/CLI take precedence. |
| AutoModeShellSetting | autoMode.classifyAllShell | Routes all Bash/PowerShell commands through the auto-mode classifier. |
| WorkflowSettings | enableWorkflows, disableWorkflows, workflowKeywordTriggerEnabled, workflowSizeGuideline | Enables workflows, controls the ultracode trigger, and advises default fan-out size. |
| TeammateModeSetting | teammateMode | Chooses auto, tmux, iterm2, or in-process for experimental Agent Teams; default in-process. |
| SandboxCredentialPolicy | sandbox.credentials | Protects credential files and environment variables inside sandboxed subprocesses. |
| ManagedVersionPolicy | requiredMinimumVersion, requiredMaximumVersion | Refuses startup outside administrator-approved semver bounds. |
| DisableClaudeAiConnectorsSetting | disableClaudeAiConnectors | Disables claude.ai connector loading while leaving other MCP sources separate. |
| TeamOnboardingPolicy | allow_team_onboarding | Organization policy gate for /team-onboarding and its optional hosted-share path. |
Bundle module in cli.renamed.js
| Semantic alias | Loader line(s) | Representative renamed exports | Atlas entry |
|---|---|---|---|
SettingsFileLoader | 62036, 62450 | parseSettingsFile, parseSettingsFileUncached, parseRemoteManagedSettings, loadManagedFileSettingsFromDir, updateSettingsForSource, settingsMergeCustomizer, shouldIncludeParentTier, rawSettingsContainsKey | Bundle module map — permission, trust, hooks, and policy |
Settings roots and loaders
| Surface | Scope | Notes |
|---|---|---|
~/.claude/settings.json | User/global | User-level persisted configuration. |
.claude/settings.json | Project | Repository/project configuration. |
.claude/settings.local.json | Local project | Local overrides that are usually not committed. |
| Managed settings / policy | Organization/admin | Can disable or constrain capabilities regardless of local preferences. |
--settings <file-or-json> | Per invocation | Adds settings JSON file or inline JSON. |
--managed-settings <file-or-json> | Per invocation / SDK parent-policy path | Supplies parent-managed settings; the selected admin tier can filter or suppress that parent slice. |
--setting-sources <sources...> | Per invocation | Admits a comma-separated subset of user, project, and local. Flag/SDK and policy settings remain admitted, and source order stays fixed. |
Effective order and merge exceptions
For the ordinary effective object, later rows have higher precedence:
| Order | Layer | Important boundary |
|---|---|---|
| 0 | Enabled-plugin defaults | Only the plugin-default allowlist is accepted; user and higher sources override it. |
| 1 | User settings | Global editable preferences. |
| 2 | Project settings | Overrides user settings for the repository. Loading does not itself authorize every project-owned executable extension; trust checks remain owner-specific. |
| 3 | Local settings | Private project override. |
| 4 | Flag/SDK settings | --settings file/inline data plus SDK inline settings. |
| 5 | Managed policy | Selected admin policy; lower settings cannot override it. |
Nested objects merge recursively. Arrays normally concatenate and de-duplicate, but a later fallbackModel array replaces the earlier array. When policy defines availableModels, that array entirely replaces the ordinarily merged lower-source array after merge (there is no lower-source union); policy enforceAvailableModels is likewise copied exactly. Lower settings therefore cannot widen model enforcement.
The policy layer is itself selected rather than universally merged. A validated policy helper wins when present; otherwise the first non-empty remote → MDM/HKLM/plist → managed-file tier is the ordinary admin object. parentSettingsBehavior:"first-wins" drops the filtered SDK-parent slice; it is not a generic first-key-wins merge mode. Security-specific consumers can still accumulate restrictions across all admin tiers.
Parsing is also source-sensitive:
- an ordinary settings file with any remaining schema error contributes no settings, although permission/hook/MCP-list sanitizers can first remove bad individual entries with warnings;
- managed settings validate per field, preserving unrelated valid policy and applying explicit fail-closed recovery to fields such as
allowedMcpServers,allowManagedMcpServersOnly,availableModels,enforceAvailableModels, andforceLoginOrgUUID; and - every disk settings file is bounded to 2 MiB.
The complete load, watcher, ConfigChange, and atomic-write path is documented in Load, validate, and merge pipeline.
Known settings and policy groups
| Group | Setting or surface examples | Runtime implication | Primary owner |
|---|---|---|---|
| Retention/session cleanup | cleanupPeriodDays | Bounds how long local transcript/project state is retained. | Session resume and transcripts |
| Hooks and status line | disableAllHooks, hooks, statusLine, subagentStatusLine | Controls lifecycle hooks plus two separate command-derived UI protocols. | Status line runtime and command protocol |
| Remote and agent policy | disableRemoteControl, disableAgentView | Managed policy can disable Remote Control and agent UI paths. | Remote control and teleport |
| Skill/slash safety | disableSkillShellExecution | Replaces or prevents shell execution in skills/custom slash commands. | Slash commands and automation |
| Authentication helpers | apiKeyHelper, proxyAuthHelper, enterpriseGateway | Points to credential/proxy helper mechanisms. | Models, providers, and auth |
| MCP and plugins | mcpServers, disableClaudeAiConnectors, enabledPlugins, pluginConfigs, extraKnownMarketplaces, plugin-provided hooks/output styles/MCP/LSP servers | Adds external capability providers; enablement, user options, installation, and marketplace state remain separate layers. | Plugin lifecycle and configuration |
| Tools and permissions | allowedTools, disallowedTools, permission mode settings, denyRead-style exclusions | Shapes model-visible tools and approval/deny behavior. | Tool inventory and schemas |
| Prompt/context | system prompt, append prompt, output styles, memory/context exclusions | Shapes model-visible context and prompt assembly. | Prompt, context, and memory |
| Integrations | --ide, autoConnectIde, --chrome, claudeInChromeDefaultEnabled, --file | Adds IDE/LSP, browser, and file-resource integration surfaces. | Settings, policy, and integrations |
| Worktree isolation | worktree.baseRef, sparsePaths, symlinkDirectories, bgIsolation | Selects base ancestry, sparse checkout, explicit shared directories, and background edit isolation. | Worktree isolation and handoffs |
| Sandbox/runtime behavior | sandbox mode, ignore-file behavior, tool-specific safety switches | Constrains process/file/network access after permission approval. | Sandbox and isolation |
| Accessibility/UI | axScreenReader, wheelScrollAccelerationEnabled, vimInsertModeRemaps | Selects accessible rendering and terminal input behavior. | Accessibility and screen-reader mode |
| Permission defaults/auto mode | permissions.defaultMode, autoMode.classifyAllShell | manual aliases historical default; auto mode can classify every shell command. | Built-in tools and permissions |
| Workflows | enableWorkflows, disableWorkflows, workflowKeywordTriggerEnabled, global workflowSizeGuideline | Controls feature availability, ultracode keyword opt-in, and advisory workflow size. | Dynamic workflows |
| Agent Teams | teammateMode | Captured once after team enablement; selects the in-process or terminal-pane backend. It does not enable Agent Teams by itself. | Agent Teams |
| Team onboarding | organization policy allow_team_onboarding | Enables the user-only recent-session analysis workflow; hosted sharing remains separately gated. | Team onboarding and share flows |
| Memory | autoMemoryDirectory | Sets the auto-memory directory; project settings are ignored for this key. | Prompt, context, and memory |
| Model/version policy | availableModels, enforceAvailableModels, requiredMinimumVersion, requiredMaximumVersion | Restricts models/default resolution and enforces supported CLI versions. | Models, providers, and auth |
| Sideload/process policy | disableSideloadFlags, processWrapper | Blocks inline plugin/agent/MCP flags or routes background self-spawns through a corporate launcher. | Settings, policy, and integrations |
| Credential isolation | sandbox.credentials.files, sandbox.credentials.envVars, allowPlaintextInject | Denies credential-file reads or masks/removes secret env vars in sandboxed commands. | Sandbox and isolation |
Status-line schemas
The main status line accepts:
| Field | Constraint | Effect |
|---|---|---|
statusLine.type | Literal "command" | Selects the command adapter. |
statusLine.command | String | Receives the main session-state JSON object on stdin. |
statusLine.padding | Optional number | Horizontal TUI padding. |
statusLine.refreshInterval | Optional number, minimum 1 | Adds a periodic refresh every $N$ seconds. |
statusLine.hideVimModeIndicator | Optional boolean | Hides the built-in Vim indicator when the script renders vim.mode. |
subagentStatusLine is a separate object with only type: "command" and command. Its command receives a task-array JSON object and must emit one {id, content} JSON object per stdout line. It does not inherit the main line’s plain-text protocol, padding, interval, or Vim option.
The focused status-line page owns payload fields, refresh/cancellation, shell/environment/cwd behavior, stdout normalization, trust/policy, and rendering.
Settings versus flags versus env vars
| Surface | Good for | Reference |
|---|---|---|
| Settings files | Persisted user/project/local policy and integration configuration. | This page. |
| Root CLI flags | Per-invocation mode, tool, prompt, session, model, and integration overrides. | Command-line reference |
| Environment variables | Credentials, provider selection, debug/telemetry gates, feature kill switches, remote tokens. | Environment variables reference |
| Managed policy | Organization/admin constraints that can disable high-risk features. | Settings, policy, and integrations |
Complete schema extraction boundary
The complete settings validator is present in the bundle, but it is embedded as minified schema construction rather than an exported JSON Schema document. The high-signal ordinary path is parseSettingsFileUncached() → hGe() → r3().safeParse; the managed path wraps the same field shapes through mSi() so policy can recover per key.
| Layer | What is source-confirmed | Documentation status |
|---|---|---|
| Embedded validator | r3().safeParse validates ordinary settings after parsing and targeted sanitization; mSi() owns managed recovery. | Anchored here; not expanded into a full generated JSON Schema. |
| Project/user/local settings | .claude/settings.json, .claude/settings.local.json, ~/.claude/settings.json | Covered as roots and loaders. |
| Managed/policy settings | disableRemoteControl, disableAgentView, disableAllHooks, disableSkillShellExecution, allow_team_onboarding, marketplace allow/block lists | Covered as policy groups; exact organization policy envelopes may vary. |
| Plugin lifecycle/configuration | enabledPlugins, pluginConfigs, extraKnownMarketplaces, strictKnownMarketplaces, blockedMarketplaces | Covered here, in Plugin lifecycle and configuration, and in MCP, plugins, and hooks. |
| Sandbox-sensitive settings | dangerouslyDisableSandbox schema text and sandbox policy pages | Covered as policy boundary, not as a guarantee that a command bypasses sandboxing. |
The remaining “complete schema” gap is mechanical extraction: a future script could reconstruct or evaluate the embedded schema into a stable JSON/Markdown reference. Until then, this page should stay a known-settings reference with exact anchors for high-signal keys, rather than hand-copying every minified schema branch.
Source restrictions for sensitive settings
Not every valid key is honored from every source. autoMemoryDirectory is ignored in checked-in project settings. processWrapper is read from managed, flag/SDK, or user settings (and can be overridden by CLAUDE_CODE_PROCESS_WRAPPER), while project/local values are ignored. sandbox.credentials.allowPlaintextInject and sandbox.network.tlsTerminate are likewise restricted to user, managed/policy, or --settings sources. autoMode classifier rules reject project/local sources because repositories control those files. pluginConfigs follows user → flag/SDK → policy and ignores both project and local settings so repository configuration cannot supply plugin options/secrets. Sensitive plugin values are stored outside settings JSON and merged last.
enabledPlugins is different: it uses the ordinary scoped cascade, so project/local values can enable or disable a plugin unless a higher source wins. extraKnownMarketplaces can also be declared by editable scopes, but project/local declarations do not enter the usable marketplace set before workspace trust. See Plugin lifecycle and configuration for the complete distinction.
statusLine normally uses the merged effective setting after workspace trust. Safe mode, managed allowManagedHooksOnly, or a non-policy merged disableAllHooks state reduces it to the managed-policy value; managed disableAllHooks: true suppresses execution. This is a source-selection boundary, not a per-refresh permission prompt.
De-duplication rule
When adding new settings detail, prefer this ownership split:
- Put the key name, scope, and owning behavior here.
- Put call paths and runtime effects in the owning implementation page.
- Put env-var-only toggles in Environment variables reference, not here.
- Put plugin enablement, plugin-owned defaults,
userConfig, and sensitive option storage in Plugin lifecycle and configuration, not in the general key list.
Related docs
- Status line runtime and command protocol
- Settings, policy, and integrations
- Plugin lifecycle and configuration
- Browser automation and Claude in Chrome
- IDE integration and LSP diagnostics
- Worktree isolation and handoffs
- Accessibility and screen-reader mode
- Safe mode and recovery
- Tool inventory and schemas
- Hooks and events reference
- MCP, plugins, and hooks
- Environment variables reference
- Team onboarding and share flows
- Agent Teams
Created and maintained by Yingting Huang.