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.js. - Runtime precedence can be affected by
--setting-sources, managed policy, and per-invocation flags; docs should avoid assuming one universal merge order for every mode.
Source anchors
| Semantic alias | Source | Approximate location | String or symbol | Meaning |
|---|---|---|---|---|
| ProjectUserSettingsSchema | cli.js | line ~185, byte 0x11b83b | .claude/settings.json | Project/user settings overlay schema text. |
| TranscriptRetentionSetting | cli.js | line ~185, byte 0x11904c | cleanupPeriodDays | Transcript retention setting. |
| ManagedUiPolicySettings | cli.js | line ~185, byte 0x11a6b4 | disableAllHooks, statusLine, disableAgentView | Managed settings/policy surfaces for hooks/status/agent view. |
| RemoteControlPolicySetting | cli.js | line ~185, byte 0x11a7e1 | disableRemoteControl | Managed policy surface for Remote Control. |
| SkillShellPolicySetting | cli.js | line ~185, byte 0x11a8f2 | disableSkillShellExecution | Managed policy surface for shell execution in skills/custom slash commands. |
| ApiKeyHelperSetting | cli.js | line ~185, byte 0x118a65 | apiKeyHelper | Settings helper script that outputs authentication values. |
| EmbeddedSettingsValidator | cli.js | line ~187, byte 0x121a0d | PP().safeParse | Loaded settings are validated through the embedded schema. |
| EnabledPluginsSetting | cli.js | line ~185, byte 0x11b66d | enabledPlugins | Settings surface for plugin enablement and version constraints. |
| ExtraMarketplacesSetting | cli.js | line ~185, byte 0x11b871 | extraKnownMarketplaces | Settings surface for repository/team marketplace registration. |
| StrictMarketplacePolicy | cli.js | line ~185, byte 0x113422 | strictKnownMarketplaces | Managed marketplace allowlist. |
| BlockedMarketplacePolicy | cli.js | line ~185, byte 0x113479 | blockedMarketplaces | Managed marketplace blocklist. |
| SandboxOverridePolicy | cli.js | line ~185, byte 0x10a6cf | dangerouslyDisableSandbox | Settings/policy schema text controlling sandbox override behavior. |
| StatusLineSettingsMutation | cli.js | line ~1593, byte 0x4eddc6 | ~/.claude/settings.json | Status-line setup instructions mutate user settings. |
| SettingsInjectionFlag | cli.js | line ~19525, byte 0xdc1cba | --settings <file-or-json> | Adds settings JSON file or inline JSON for a session. |
| IdeIntegrationFlag | cli.js | line ~19525, byte 0xdc1e09 | --ide | Auto-connect IDE integration flag. |
| ChromeIntegrationFlag | cli.js | line ~19525, byte 0xdc2268 | --chrome | Chrome integration flag. |
| StartupFileResourceFlag | cli.js | line ~19525, byte 0xdc22de | --file <specs...> | Startup file-resource download integration. |
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 / policy test path | Loads managed-policy-style settings from a file or inline JSON. |
--setting-sources <sources...> | Per invocation | Selects setting source order/participation for a run. |
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 | Enables/disables hooks and status-line execution. | Hooks and events reference |
| 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, plugin marketplaces, plugin-provided hooks/output styles/MCP servers | Adds external capability providers. | MCP, plugins, and hooks |
| 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, --chrome, --file plus integration settings | Adds editor/browser/file-resource integration surfaces. | Settings, policy, and integrations |
| Sandbox/runtime behavior | sandbox mode, ignore-file behavior, tool-specific safety switches | Constrains process/file/network access after permission approval. | Sandbox and isolation |
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 validation anchor is PP().safeParse around line ~187: loaded JSON is parsed, preflight errors are collected, and only the parsed .data is returned as settings.
| Layer | What is source-confirmed | Documentation status |
|---|---|---|
| Embedded validator | PP().safeParse validates loaded settings after JSON/object parsing. | 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, marketplace allow/block lists | Covered as policy groups; exact organization policy envelopes may vary. |
| Plugin marketplaces | enabledPlugins, extraKnownMarketplaces, strictKnownMarketplaces, blockedMarketplaces | Covered here 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.
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.
- Keep plugin-specific schema extensions in plugin/MCP docs until confirmed as general settings.
Related docs
Created and maintained by Yingting Huang.