--- url: /api/schemas/settings.md description: >- Schema reference for settings.json including permissions, attribution, and sandbox configuration. --- # Settings The `settings.json` file configures Claude Code behavior. It can be located at `~/.claude/settings.json` (global), `.claude/settings.json` (project), or `.claude/settings.local.json` (local, gitignored). ## Fields ### Permissions | Field | Type | Required | Description | | ------------------------------ | -------- | -------- | ------------------------------------------------------------- | | `allow` | string\[] | no | Permission patterns to auto-allow (e.g., `"Bash(npm run *)"`) | | `deny` | string\[] | no | Permission patterns to always deny | | `ask` | string\[] | no | Permission patterns to always prompt | | `defaultMode` | string | no | `acceptEdits`, `bypassPermissions`, `default`, or `plan` | | `disableBypassPermissionsMode` | string | no | Set to `"disable"` to prevent bypass | | `additionalDirectories` | string\[] | no | Extra directories to allow access to | | `blockReadsOutsideWorkingDirectories` | boolean | no | Block file reads outside the working directories | ### Attribution | Field | Type | Required | Description | | -------- | ------ | -------- | ----------------------- | | `commit` | string | no | Commit message template | | `pr` | string | no | PR description template | | `sessionUrl` | boolean | no | Include the cloud or Remote Control session URL in attribution | ### Sandbox | Field | Type | Required | Description | | --------------------------- | -------- | -------- | ------------------------------------------------------------ | | `enabled` | boolean | no | Enable sandboxing | | `failIfUnavailable` | boolean | no | Fail rather than run unsandboxed when the sandbox is missing | | `autoAllowBashIfSandboxed` | boolean | no | Auto-allow bash in sandbox | | `excludedCommands` | string\[] | no | Commands excluded from sandbox | | `allowUnsandboxedCommands` | boolean | no | Allow the `dangerouslyDisableSandbox` escape hatch | | `enableWeakerNestedSandbox` | boolean | no | Allow weaker nested sandbox | | `filesystem` | object | no | Filesystem read/write allow and deny lists | | `credentials` | object | no | Credential file and env var protection | | `network` | object | no | Network restrictions (see below) | | `allowAppleEvents` | boolean | no | Permit Apple Events on macOS | | `bwrapPath` | string | no | Managed bubblewrap executable path | | `socatPath` | string | no | Managed socat executable path | | `enableWeakerNetworkIsolation` | boolean | no | Permit macOS TLS trust service access | | `ignoreViolations` | object | no | Map command substrings to arrays of violation substrings to suppress | | `ripgrep` | object | no | Custom command and optional args for ripgrep | ### Sandbox network | Field | Type | Required | Description | | ------------------------- | -------- | -------- | --------------------------------------- | | `allowedDomains` | string\[] | no | Domains the sandbox may reach | | `deniedDomains` | string\[] | no | Domains the sandbox may not reach | | `allowManagedDomainsOnly` | boolean | no | Restrict to managed domains | | `allowUnixSockets` | string\[] | no | Unix sockets the sandbox may connect to | | `allowAllUnixSockets` | boolean | no | Allow all Unix sockets | | `allowLocalBinding` | boolean | no | Allow binding to local ports | | `allowMachLookup` | string\[] | no | Mach services the sandbox may look up | | `httpProxyPort` | number | no | HTTP proxy port | | `socksProxyPort` | number | no | SOCKS proxy port | | `strictAllowlist` | boolean | no | Deny hosts outside the sandbox allowlist | ## Example ```json { "permissions": { "allow": ["Bash(npm run *)", "Bash(git *)", "Read", "Edit"], "deny": ["Bash(rm -rf *)"] }, "sandbox": { "enabled": true, "network": { "allowedDomains": ["registry.npmjs.org"] } } } ``` The schema validates setting values across scopes. It does not enforce whether a setting is permitted in a particular file or change runtime policy. Scope restrictions are listed in the [upstream settings reference](https://code.claude.com/docs/en/settings-reference#scopes). ## Full field reference Every top-level key `SettingsSchema` models, generated from the schema itself. Descriptions are abridged from the [official settings reference](https://code.claude.com/docs/en/settings-reference). | Field | Type | Required | Description | | --------------------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------- | | `availableModelsMatch` | string | no | Managed model allowlist matching: `prefix` or `exact` | | `deniedModels` | string\[] | no | Managed model aliases or IDs to block | | `bashEditDiffEnabled` | boolean | no | Record file changes during Bash commands; project settings cannot enable recording | | `maxProseWidth` | number | no | Whole terminal columns, minimum 40 | | `syncClaudeAiPlugins` | boolean | no | Set false to stop syncing and loading account plugins; project settings cannot disable sync | | `prependPlugins` | string\[] | no | Plugin IDs whose mods run first, from user or managed settings | | `appendPlugins` | string\[] | no | Plugin IDs whose mods run last, from user or managed settings | | `allowClaudeInChromeWithManagedMcp` | boolean | no | Device-managed exception allowing Chrome with managed MCP configuration | | `allowedProviders` | string\[] | no | Managed provider allowlist: `anthropic`, `bedrock`, `vertex`, `foundry`, `anthropicAws`, `mantle`, `customEndpoint`, `gateway` | | `gatewayInternalNetworks` | string\[] | no | At most four nonoverlapping public IPv4 CIDRs, /8–/32, from device-managed settings | | `$schema` | string | No | — | | `advisorModel` | string | No | Model for the server-side advisor tool. Accepts a model alias such as `"opus"`, `"sonnet"`, or `"fab | | `agent` | string | No | Run the main thread as a named subagent, and set the default agent for sessions dispatched from`cla | | `agentPushNotifEnabled` | boolean | No | **Default**: `false`. When Remote Control is connected, allow Claude to send proactive push notifica | | `allowAllClaudeAiMcps` | boolean | No | (Managed settings only) Load claude.ai connectors alongside a deployed `managed-mcp.json`, which oth | | `allowManagedHooksOnly` | boolean | No | (Managed settings only) Only managed hooks, SDK hooks, and hooks from plugins force-enabled in manag | | `allowManagedMcpServersOnly` | boolean | No | Treated as `true` | | `allowManagedPermissionRulesOnly` | boolean | No | (Managed settings only) Prevent user and project settings from defining `allow`, `ask`, or `deny` pe | | `allowedChannelPlugins` | array | No | (Managed settings only) Allowlist of channel plugins that may push messages. Replaces the default An | | `allowedHttpHookUrls` | array | No | Allowlist of URL patterns that HTTP hooks may target. Supports `*` as a wildcard. When set, hooks wi | | `allowedMcpServers` | array | No | Enforced as an empty allowlist, so no MCP servers are admitted until the value is fixed. An individu | | `alwaysThinkingEnabled` | boolean | No | Enable extended thinking by default for all sessions. Typically configured via the `/config` command | | `apiKeyHelper` | string | No | Custom command, run through the system shell (`/bin/sh` on macOS and Linux, `cmd` on Windows), to ge | | `askUserQuestionTimeout` | string | No | **Default**: `"never"`. Idle time before an unanswered `AskUserQuestion` dialog auto-continues with | | `attribution` | object | No | Customize attribution for git commits and pull requests. See Attribution settings | | `autoCompactEnabled` | boolean | No | **Default**: `true`. Automatically compact the conversation when context approaches the limit. Appea | | `autoMemoryDirectory` | string | No | Custom directory for auto memory storage. Accepts an absolute path or a `~/`-prefixed path. From pro | | `autoMemoryEnabled` | boolean | No | **Default**: `true`. Enable auto memory. When `false`, Claude does not read from or write to the aut | | `autoMode` | object | No | Customize what the auto mode classifier blocks and allows. Contains `environment`, `allow`, `soft_de | | `autoScrollEnabled` | boolean | No | **Default**:`true`. In fullscreen rendering, follow new output to the bottom of the conversation. A | | `autoUpdatesChannel` | string | No | **Default**:`"latest"`. Release channel to follow for updates. Use `"stable"`for a version that is | |`availableModels` | array | No | Enforced as an empty allowlist, so only the Default model is available until the value is fixed. An | |`awaySummaryEnabled` | boolean | No | Show a one-line session recap when you return to the terminal after a few minutes away. Set to`fals | | `awsAuthRefresh` | string | No | Custom script that modifies the `.aws` directory (see advanced credential configuration) | | `awsCredentialExport` | string | No | Custom script that outputs JSON with AWS credentials (see advanced credential configuration) | | `axScreenReader` | boolean | No | Render screen-reader friendly output: flat text without decorative borders or animations. Screen-rea | | `blockedMarketplaces` | array | No | (Managed settings only) Blocklist of marketplace sources. Enforced on marketplace add and on plugin | | `browserExternalPageTools` | string | No | (Managed settings only) Set to `"disabled"` to prevent Claude from using tools to read or act on ext | | `channelsEnabled` | boolean | No | (Managed settings only) Allow channels for the organization. On claude.ai Team and Enterprise plans, | | `claudeMd` | string | No | (Managed settings only) CLAUDE.md-style instructions injected as organization-managed memory. Only h | | `claudeMdExcludes` | array | No | Glob patterns or absolute paths of `CLAUDE.md` files to skip when loading memory. Patterns match aga | | `cleanupPeriodDays` | number | No | **Default**: `30` days, minimum `1`. Claude Code deletes session files and other application data ol | | `companyAnnouncements` | array | No | Announcement to display to users at startup. If multiple announcements are provided, they will be cy | | `defaultShell` | string | No | **Default**: `"bash"`, or `"powershell"` on Windows when Bash isn't available. Default shell for inp | | `deniedMcpServers` | array | No | An individual invalid entry is stripped and the valid subset is enforced. A wholly invalid value is | | `disableAgentView` | boolean | No | Set to `true` to turn off background agents and agent view: `claude agents`, `--bg`, `/background`, | | `disableAllHooks` | boolean | No | Disable all hooks and any custom status line | | `disableArtifact` | boolean | No | Set to `true` to disable the Artifact tool, which publishes session output as a private web page on | | `disableAutoMode` | string | No | Set to `"disable"` to prevent auto mode from being activated. Removes `auto` from the `Shift+Tab` cy | | `disableBundledSkills` | boolean | No | Set to `true` to disable the skills and workflows included with Claude Code: bundled skills and work | | `disableClaudeAiConnectors` | boolean | No | Disable claude.ai MCP connectors so they are not auto-fetched or connected. Set in any settings scop | | `disableDeepLinkRegistration` | string | No | Set to `"disable"` to prevent Claude Code from registering the `claude-cli://` protocol handler with | | `disableRemoteControl` | boolean | No | Disable Remote Control: blocks `claude remote-control`, the `--remote-control` flag, auto-start, and | | `disableSideloadFlags` | boolean | No | (Managed settings only) Reject the `--plugin-dir`, `--plugin-url`, `--agents`, and `--mcp-config` CL | | `disableSkillShellExecution` | boolean | No | Disable inline shell execution for `` !`...` `` and ` ```! ` blocks in skills and custom commands fr | | `disableWorkflows` | boolean | No | **Default**: `false`. Disable dynamic workflows and the bundled workflow commands. Equivalent to set | | `disabledMcpjsonServers` | array | No | List of specific MCP servers from `.mcp.json` files to reject | | `editorMode` | string | No | **Default**: `"normal"`. Key binding mode for the input prompt: `"normal"` or `"vim"`. Appears in `/ | | `effortLevel` | string | No | Persist the effort level across sessions. Accepts`"low"`, `"medium"`, `"high"`, or `"xhigh"`. Writt | | `enableAllProjectMcpServers` | boolean | No | Automatically approve all MCP servers defined in project`.mcp.json`files. As of v2.1.196,`claude | | `enableArtifact` | boolean | No | Enable or disable the Artifact tool for this user. When unset, the default follows the feature's ava | | `enabledMcpjsonServers` | array | No | List of specific MCP servers from `.mcp.json` files to approve. As of v2.1.196, `claude mcp list` an | | `enabledPlugins` | object | No | — | | `enforceAvailableModels` | boolean | No | Treated as `true`. Applies in v2.1.175 and later | | `env` | object | No | Environment variables applied to every session and to subprocesses Claude Code spawns from it. As of | | `extraKnownMarketplaces` | object | No | — | | `fallbackModel` | array | No | Fallback model(s) to try in order when the primary model is overloaded or unavailable. Claude Code s | | `fastModePerSessionOptIn` | boolean | No | When `true`, fast mode does not persist across sessions. Each session starts with fast mode off, req | | `feedbackSurveyRate` | number | No | Probability (0–1) that the session quality survey appears when eligible. Set to `0` to suppress enti | | `fileCheckpointingEnabled` | boolean | No | **Default**: `true`. Snapshot files before each edit so `/rewind` can restore them. Appears in `/con | | `fileSuggestion` | object | No | Configure a custom script for`@`file autocomplete. See File suggestion settings | |`footerLinksRegexes` | array | No | Render extra clickable badges in the footer when a regex matches turn output. Each entry has a`patt | | `forceLoginGatewayUrl` | string | No | Pre-fills and locks the gateway URL on the `/login` Cloud gateway screen. Either this key or `forceL | | `forceLoginMethod` | string | No | Use`claudeai`to restrict login to Claude.ai accounts,`console`to restrict login to Claude Consol | |`forceLoginOrgUUID` | string \| string[] | No | No organization is permitted to log in until the value is fixed | |`forceRemoteSettingsRefresh` | boolean | No | (Managed settings only) Block CLI startup until remote managed settings are freshly fetched from the | |`gcpAuthRefresh` | string | No | Custom script that refreshes GCP Application Default Credentials when they expire or cannot be loade | |`hooks` | object | No | Configure custom commands to run at lifecycle events. See hooks documentation for format | |`httpHookAllowedEnvVars` | array | No | Allowlist of environment variable names HTTP hooks may interpolate into headers. When set, each hook | |`includeGitInstructions` | boolean | No | **Default**:`true`. Include built-in commit and PR workflow instructions and the git status snapsho | | `inputNeededNotifEnabled` | boolean | No | **Default**:`false`. When Remote Control is connected, send a push notification to your phone when | | `language` | string | No | Configure Claude's preferred response language (e.g.,`"japanese"`, `"spanish"`, `"french"`). Claude | | `minimumVersion` | string | No | Floor that prevents background auto-updates and`claude update`from installing a version below this | |`model` | string | No | Override the default model to use for Claude Code.`--model`and`ANTHROPIC\_MODEL`override this for | |`modelOverrides` | object | No | Map Anthropic model IDs to provider-specific model IDs such as Amazon Bedrock inference profile ARNs | |`otelHeadersHelper` | string | No | Script to generate dynamic OpenTelemetry headers. Runs at startup and periodically. Set the refresh | |`outputStyle` | string | No | Configure an output style to adjust the system prompt. See output styles documentation | |`parentSettingsBehavior` | string | No | (Managed settings only) **Default**:`"first-wins"`. Controls whether managed settings supplied prog | | `permissions` | object | No | See table below for structure of permissions | |`plansDirectory` | string | No | **Default**:`~/.claude/plans`. Customize where plan files are stored. Path is relative to project r | | `pluginSuggestionMarketplaces` | array | No | (Managed settings only) Marketplace names whose plugins can appear as contextual install suggestions | |`pluginTrustMessage` | string | No | (Managed settings only) Custom message appended to the plugin trust warning shown before installatio | |`policyHelper` | object | No | Admin-deployed executable that computes managed settings dynamically at startup. Only honored from M | |`prUrlTemplate` | string | No | URL template for the PR badge shown in the footer and in tool-result summaries. Substitutes`{host}`| |`preferredNotifChannel` | string | No | **Default**:`"auto"`. Method for task-complete and permission-prompt notifications: `"auto"`, `"ter | | `prefersReducedMotion` | boolean | No | Reduce or disable UI animations (spinners, shimmer, flash effects) for accessibility | | `remoteControlAtStartup` | boolean | No | Connect Remote Control automatically when each interactive session starts, instead of waiting for `/ | | `requiredMaximumVersion` | string | No | Managed settings only. Maximum Claude Code version allowed to start. If the running version is newer | |`requiredMinimumVersion` | string | No | Managed settings only. Minimum Claude Code version required to start. If the running version is olde | |`respectGitignore` | boolean | No | **Default**:`true`. Control whether the `@`file picker respects`.gitignore`patterns. When`true`| |`respondToBashCommands` | boolean | No | **Default**:`true`. Whether Claude responds after an input-box `!`shell command runs. Set to`fals | | `sandbox` | object | No | — | | `showClearContextOnPlanAccept` | boolean | No | **Default**: `false`. Show the "clear context" option on the plan accept screen. Set to `true` to re | | `showThinkingSummaries` | boolean | No | **Default**: `false`. Show extended thinking summaries in interactive sessions. When unset or `false | | `showTurnDuration` | boolean | No | **Default**:`true`. Show turn duration messages after responses, e.g. "Cooked for 1m 6s". Appears i | | `skillListingBudgetFraction` | number | No | **Default**:`0.01`. Fraction of the model's context window reserved for the skill listing Claude se | | `skillListingMaxDescChars` | number | No | **Default**:`1536`. Per-skill character cap on the combined `description`and`when\_to\_use`text in | |`skillOverrides` | object | No | Per-skill visibility overrides keyed by skill name. Value is`"on"`, `"name-only"`, `"user-invocable | | `skipWebFetchPreflight` | boolean | No | Skip the WebFetch domain safety check that sends each requested hostname to `api.anthropic.com` befo | | `spinnerTipsEnabled` | boolean | No | **Default**: `true`. Show tips in the spinner while Claude is working. Set to `false` to disable tip | | `spinnerTipsOverride` | object | No | Override spinner tips with custom strings. `tips`: array of tip strings. `excludeDefault`: if `true` | | `spinnerVerbs` | object | No | Customize the action verbs shown while a turn is in progress. Set `mode` to `"replace"` to use only | | `sshConfigs` | array | No | SSH connections to show in the Desktop environment dropdown. Each entry requires `id`, `name`, and `| |`statusLine` | object | No | Configure a custom status line to display context. The object's optional`padding`, `refreshInterval | | `strictKnownMarketplaces` | array | No | (Managed settings only) Allowlist of plugin marketplace sources. Undefined = no restrictions, empty | | `strictPluginOnlyCustomization` | array | No | (Managed settings only) Block skills, agents, hooks, and MCP servers from user and project sources, | | `syntaxHighlightingDisabled` | boolean | No | Disable syntax highlighting in diffs, code blocks, and file previews | | `teammateMode` | string | No | **Default**: `in-process`. How agent team teammates display: `in-process`, `auto` (split panes when | | `terminalProgressBarEnabled` | boolean | No | **Default**: `true`. Show the terminal progress bar in supported terminals: ConEmu, Ghostty 1.2.0+, | | `theme` | string | No | **Default**: `"dark"`. Color theme for the interface: `"auto"`, `"dark"`, `"light"`, `"dark-daltoniz | | `tui` | string | No | Terminal UI renderer. Use`"fullscreen"`for the flicker-free alt-screen renderer with virtualized s | |`ultracode` | boolean | No | Turn on ultracode for the current session. This key isn't read from`settings.json`. Set it through | | `useAutoModeDuringPlan` | boolean | No | **Default**:`true`. Whether plan mode uses auto mode semantics when auto mode is available. Not rea | | `verbose` | boolean | No | **Default**:`false`. Show full tool output instead of truncated summaries. Appears in `/config`as | |`viewMode` | string | No | Default transcript view mode on startup:`"default"`, `"verbose"`, or `"focus"`. Overrides the stick | | `voice` | object | No | Voice dictation settings:`enabled`turns dictation on,`mode`selects`"hold"`or`"tap"`, and `aut | | `voiceEnabled` | boolean | No | Legacy alias for `voice.enabled`. Prefer the `voice` object | | `wheelScrollAccelerationEnabled` | boolean | No | **Default**: `true`. In fullscreen rendering, accelerate mouse-wheel scroll speed during fast scroll | | `workflowKeywordTriggerEnabled` | boolean | No | **Default**: `true`. Whether the keyword `ultracode` in a prompt triggers a dynamic workflow. Set to | | `wslInheritsWindowsSettings` | boolean | No | (Windows managed settings only) When `true`, Claude Code on WSL reads managed settings from the Wind | | `autoCompactWindow` | number | no | Context window used for auto-compaction, 100000 to 1000000 tokens | | `autoContinueAtUsageLimit` | boolean | no | Continue automatically when a usage limit resets | | `bashOutputMaxChars` | number | no | Positive integer limit for Bash output; runtime clamps to its supported range | | `crossSessionInbound` | string | no | Inbound session messages: accept, hold, or refuse | | `desktopSessionCleanupPeriodDays` | number | no | Nonnegative number of days before desktop session cleanup | | `dialogExpiry` | string | no | Dialog timeout: 60s, 5m, 10m, or never | | `disableBrowserExternalNavigation` | boolean | no | Disable browser navigation outside permitted surfaces | | `disableCommandPluginSources` | boolean | no | Block command-based plugin sources | | `disableDesktopLocalSessions` | boolean | no | Disable desktop local sessions | | `disableMobileSimulatorTools` | boolean | no | Disable mobile simulator tools | | `emojiCompletionEnabled` | boolean | no | Enable emoji completion | | `enableWorkflows` | boolean | no | Enable workflow support | | `fastMode` | boolean | no | Enable fast mode | | `feedbackDrafts` | string | no | Feedback drafts: notify, quiet, or off | | `includeCoAuthoredBy` | boolean | no | Deprecated commit attribution toggle | | `isolatePeerMachines` | boolean | no | Isolate peer machines | | `keybindingFlavor` | string | no | Keyboard bindings: classic or readline | | `managedMcpServers` | object | no | Managed remote HTTP or SSE MCP servers keyed by name | | `managedSourcesBehavior` | string | no | Managed settings composition: first-wins or merge | | `maxEffortLevel` | string | no | Maximum effort: low, medium, high, xhigh, or max | | `modelPicker` | object | no | Model picker options and optional replacement of built-in choices | | `modelPricing` | object | no | Pricing multiplier and per-model input, output, cache-read, and cache-write rates | | `modelSettings` | object | no | Per-model effortLevel and maxEffortLevel | | `pluginConfigs` | object | no | Non-sensitive plugin options and per-server configuration values | | `processWrapper` | string | no | Command prefix used to wrap child processes | | `promptCacheTtl` | string | no | Prompt cache TTL: 5m or 1h | | `promptSuggestionEnabled` | boolean | no | Enable prompt suggestions | | `remote` | object | no | Default cloud environment in defaultEnvironmentId | | `skipAutoPermissionPrompt` | boolean | no | Dismiss the auto-permission introduction prompt | | `skipDangerousModePermissionPrompt` | boolean | no | Dismiss the bypass-permissions introduction prompt | | `spellcheck` | object | no | Spellcheck enabled state, checker, language, and color | | `sshHostAllowlist` | string\[] | no | Allowed SSH hosts | | `subagentPromptCacheTtl` | string | no | Subagent prompt cache TTL: 5m or 1h | | `subagentStatusLine` | object | no | Command-based subagent status line | | `switchModelsOnFlag` | boolean | no | Allow model switching on feature flag changes | | `syncClaudeAiSkills` | boolean | no | Sync skills from claude.ai | | `taskOutputMaxChars` | number | no | Positive integer task output limit; runtime clamps to its supported range | | `terminalTitleFromRename` | boolean | no | Use session rename for the terminal title | | `timeFormat` | string | no | Clock display format or pattern | | `timeZone` | string | no | IANA time zone for clock display | | `vimInsertModeRemaps` | object | no | Map two-character sequences to `` | | `workflowSizeGuideline` | string | no | Workflow size: unrestricted, small, medium, or large | | `worktree` | object | no | baseRef (fresh or head), symlinkDirectories, sparsePaths, and bgIsolation (worktree or none) |