Page history
Claude Code settings reference
settings-reference
History
settings-reference Changed · +54 / -11 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 760
| [`skipWebFetchPreflight`](#skipwebfetchpreflight) | Skip the [WebFetch hostname check](/docs/en/tools-reference#webfetch-tool-behavior) when Anthropic is unreachable | Privacy and telemetry | Any file | | [`spellcheck`](#spellcheck) | Underline misspelled words in the prompt input with a [spell checker](/docs/en/interactive-mode#check-spelling-as-you-type) you install | Interface and terminal | User or managed | | [`spinnerTipsEnabled`](#spinnertipsenabled) | Hide tips in the spinner while Claude works | Interface and terminal | Any file | -| [`spinnerTipsOverride`](#spinnertipsoverride) | Replace or extend spinner tips with your own strings | Interface and terminal | Any file | +| [`spinnerTipsOverride`](#spinnertipsoverride) | Add your own tips to the spinner rotation, or replace the built-in tips | Interface and terminal | Any file | | [`spinnerVerbs`](#spinnerverbs) | Add or replace the verbs shown while a turn runs | Interface and terminal | Any file | | [`sshConfigs`](#sshconfigs) | Add [SSH connections](/docs/en/desktop#pre-configure-ssh-connections-for-your-team) to the Desktop environment dropdown | Remote, desktop, and notifications | User or managed | | [`sshHostAllowlist`](#sshhostallowlist) | Limit which hosts [Desktop SSH sessions](/docs/en/desktop#restrict-which-ssh-hosts-users-can-connect-to) can reach | Remote, desktop, and notifications | Managed |
from line 3055
### `spinnerTipsOverride` -Replace or extend the [spinner tips](#spinnertipsenabled), the short hints Claude Code rotates through while Claude works, with your own strings, such as a team reminder to run a review skill. Set `excludeDefault` to `true` and list at least one tip to show only your tips; when it's `false` or absent, or `tips` is empty, Claude Code keeps the built-in tips and adds yours. +Add your own tips to the [spinner tips](#spinnertipsenabled) that Claude Code shows while Claude works, or replace the built-in tips with yours. Claude Code puts your tips in the same rotation as the built-in ones: it picks the tip that has gone unshown the longest, skips tips still in their cooldown, and breaks ties by priority. -* **Scope**: [`Any file`](#scopes) -* **Type**: object with a `tips` array of strings and an optional `excludeDefault` Boolean +If you set [`spinnerTipsEnabled`](#spinnertipsenabled) to `false`, Claude Code hides all tips, yours included. + +* **Scope**: [`Any file`](#scopes). Claude Code honors tip objects, `tipsFile`, `label`, and `excludeDefault` from user settings, the `--settings` flag, and managed settings; from project and local settings it reads plain string tips only. +* **Type**: object with `tips`, `tipsFile`, `label`, and `excludeDefault` fields, each optional * **Default**: unset, so Claude Code shows only the built-in tips -This example replaces the built-in tips with a single tip of your own: +Tip objects, `tipsFile`, `label`, and the Scope line's rule that project and local settings contribute plain strings only require Claude Code v2.1.247 or later. On earlier versions, a project or local file's `excludeDefault` applies too. +Each `tips` entry is a plain string or an object with these fields: + +| Field | Required | Description | +| :----------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | Yes | Up to 64 letters, digits, `.`, `_`, or `-`. Claude Code keys the tip's show history on it, so the tip's cooldown survives reordering the list. Of two entries with the same id, Claude Code uses the first | +| `text` | Yes | The tip, one line of up to 500 characters. Claude Code strips ANSI escapes and control characters and collapses whitespace | +| `cooldownSessions` | No | Sessions Claude Code waits before showing the tip again, `0` to `1000`, default `0` | +| `priority` | No | Order among tips that have gone unshown equally long, higher first, `-10` to `10`, default `0` | + +Claude Code reads a plain string as a tip with those defaults and a position-based id, so its show history resets when you reorder the list. Give a tip an `id` to keep its history across edits. + +Claude Code reads at most 200 tips across `tips` and `tipsFile`, and drops an invalid entry with a debug warning instead of rejecting the settings file. + +Use the remaining fields to name a tips file, set the prefix, and hide the built-in tips: + +* `tipsFile`: an absolute or `~/` path to a local JSON file holding an array of the same entries, or an object with a `tips` array, up to 256 KB. Claude Code reads the file once per process, so it loads your edits at the next start. You can't set it through [server-managed settings](/docs/en/server-managed-settings); deploy inline `tips` there, or deploy the path in an on-disk `managed-settings.json`. +* `label`: the prefix Claude Code shows before tips from user, `--settings`, and managed settings, up to 40 characters. The default is `Tip`, the same prefix as the built-in tips, and tips from project and local settings always use it. +* `excludeDefault`: set it to `true` to hide the built-in tips and show only yours. When Claude Code can't load any of your tips, for example because `tipsFile` doesn't exist or every entry is invalid, it keeps the built-in rotation instead of an empty spinner. + +When more than one settings file sets the key, Claude Code shows tips from all of them and takes `tipsFile`, `label`, and `excludeDefault` from whichever of managed settings, the `--settings` flag, and user settings is the highest-precedence one that sets each. + +This example, in your user settings, adds a plain string tip and an object tip to the rotation under the `Acme tip` prefix: + ```json settings.json theme={null} { "spinnerTipsOverride": { - "excludeDefault": true, - "tips": ["Run /review before opening a PR"] + "label": "Acme tip", + "tips": [ + "Run /review before opening a PR", + { + "id": "gateway-errors", + "text": "Seeing 5xx errors? Check the gateway status page first", + "cooldownSessions": 5, + "priority": 2 + } + ] } } ``` +Each field in the example changes one thing about how Claude Code shows the tips: + +* `label`: Claude Code shows both tips as `Acme tip: ...` instead of `Tip: ...`. +* The plain string: Claude Code gives it the defaults, so it can come up again in the very next session. +* `id`: Claude Code keys the second tip's show history on `gateway-errors`, so its cooldown still applies after you add or reorder tips. +* `cooldownSessions`: after Claude Code shows the `gateway-errors` tip, it doesn't show that tip again until five sessions later. +* `priority`: when the `gateway-errors` tip and another tip have gone unshown for the same number of sessions, for example when neither has been shown yet, Claude Code shows `gateway-errors` first. The plain string has the default priority, `0`. + +While Claude works, Claude Code shows your tips in the spinner with your prefix, such as `Acme tip: Run /review before opening a PR`. + ### `spinnerVerbs` While a turn is in progress, the spinner shows a rotating verb such as "Accomplishing", "Architecting", or "Baking". Use this key to add your own verbs to that rotation or replace the built-in list with yours.
from line 3567
#### What runs under `allowManagedHooksOnly` -When you set it to `true`, Claude Code changes which hooks and hook-like commands load: - -* **Managed and SDK hooks run**: hooks from managed settings and hooks the [Agent SDK](/docs/en/agent-sdk/overview) registers in process -* **Force-enabled plugin hooks run**: hooks from plugins your managed settings force-enable through [`enabledPlugins`](#enabledplugins). Claude Code matches on the full `plugin@marketplace` ID, so a plugin with the same name from a different marketplace stays blocked. This lets you distribute vetted hooks through an organization marketplace while blocking everything else -* **Everything else is blocked**: user, project, and local hooks, hooks from other plugins, and hooks declared in agent frontmatter -* **Command-sourced plugins are disabled**: Claude Code also disables plugins with a [`command` source](/docs/en/plugin-marketplaces#command-sources), including plugins force-enabled in managed `enabledPlugins`, unless you set [`disableCommandPluginSources`](#disablecommandpluginsources) to `false` explicitly -* **Marketplace `headersHelper` commands are blocked**: Claude Code also blocks marketplace [`headersHelper` commands](/docs/en/plugin-marketplaces#authenticate-archive-downloads) unless [`disableCommandPluginSources`](#disablecommandpluginsources) is explicitly set to `false`, except for a marketplace that managed settings themselves declare. Requires Claude Code v2.1.238 or later -* **Status line and file suggestion narrow to managed settings**: Claude Code reads [`statusLine`](/docs/en/statusline), [`fileSuggestion`](#filesuggestion), and [`subagentStatusLine`](/docs/en/statusline#subagent-status-lines) from managed settings only, following the [status line and file suggestion gates](#status-line-and-file-suggestion-gates) - -The [`/goal`](/docs/en/goal) command can't run while this key is set, because it depends on hooks. - -### `disableAllHooks` - -Turn off [hooks](/docs/en/hooks#disable-or-remove-hooks), any custom [status line](/docs/en/statusline), and any custom [file suggestion](#filesuggestion) command. Use it to turn all of these off temporarily without deleting them from your settings. - -* **Scope**: [`Any file`](#scopes). Only managed settings can disable managed hooks. -* **Type**: Boolean - * `true`: Claude Code turns off hooks, any custom status line, and any custom file suggestion command - * `false`: hooks, the status line, and the file suggestion command run -* **Default**: unset, so hooks run - -```json settings.json theme={null} -{ - "disableAllHooks": true -} -``` - -The reach depends on which file carries the key: - -* **In managed settings**: Claude Code disables every configured hook, including managed ones, and keeps running the hooks the [Agent SDK](/docs/en/agent-sdk/overview) registers in process -* **In any other settings file**: Claude Code disables user, project, local, and plugin hooks; managed hooks, Agent SDK hooks, and hooks from plugins force-enabled in managed [`enabledPlugins`](#enabledplugins) keep running - -Keeping Agent SDK hooks running when managed settings set this key requires Claude Code v2.1.242 or later. - -The [`/goal`](/docs/en/goal) command can't run while hooks are disabled, and the `/hooks` menu shows a notice instead of your hooks. - -#### Status line and file suggestion gates - -Claude Code makes two decisions for `statusLine`, `fileSuggestion`, and `subagentStatusLine`, in this order: - -* **Off entirely**: when managed settings set `disableAllHooks`, or when the folder isn't trusted under the same [workspace trust rule as hooks in settings files](/docs/en/permissions#what-runs-before-you-trust-a-folder) -* **Narrowed to managed settings**: when [`allowManagedHooksOnly`](#allowmanagedhooksonly) is set, when `disableAllHooks` is `true` outside managed settings after [settings precedence](/docs/en/hooks#disable-or-remove-hooks) applies, or when you start Claude Code with `--safe-mode` - -Under narrowing, Claude Code runs a managed value if one is deployed. Otherwise it skips your value without warning: the status line is disabled, and `@` autocomplete falls back to the built-in file suggestion. - -### `disableWorkflows` - -Turn off [dynamic workflows](/docs/en/workflows#turn-workflows-off) and the bundled workflow commands for everyone your settings reach, such as an organization through managed settings. To turn workflows on or off just for yourself, use [`enableWorkflows`](#enableworkflows) instead, which the **Dynamic workflows** toggle in `/config` writes to your user settings. - -* **Scope**: [`Any file`](#scopes) -* **Type**: Boolean - * `true`: Claude Code turns off dynamic workflows and the bundled workflow commands for everyone your settings reach - * `false`: the same as unset; whether workflows are on then follows [`enableWorkflows`](#enableworkflows) and your plan's default -* **Def +When you set it to `true`, Claude Cod
settings-reference Changed · +22 / -1 lines
### `feedbackDrafts`
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 658
| [`fallbackModel`](#fallbackmodel) | Name [backup models](/docs/en/model-config#fallback-model-chains) for when the primary is overloaded | Model and responses | Any file | | [`fastMode`](#fastmode) | Turn [fast mode](/docs/en/fast-mode) on for sessions where it's available | Model and responses | Any file | | [`fastModePerSessionOptIn`](#fastmodepersessionoptin) | Require people to turn [fast mode](/docs/en/fast-mode) on each session | Model and responses | Any file | +| [`feedbackDrafts`](#feedbackdrafts) | Control whether Claude queues [feedback drafts](/docs/en/tools-reference#sendfeedback-tool-behavior) for you to review | Privacy and telemetry | User or managed | | [`feedbackSurveyRate`](#feedbacksurveyrate) | Change how often the [session quality survey](/docs/en/data-usage#session-quality-surveys) appears | Privacy and telemetry | Any file | | [`fileCheckpointingEnabled`](#filecheckpointingenabled) | Turn off or on the file snapshots that [`/rewind`](/docs/en/checkpointing) restores | Memory and context | Any file | | [`fileSuggestion`](#filesuggestion) | Supply [`@` file autocomplete](/docs/en/interactive-mode#quick-commands) from your own command | Interface and terminal | Any file |
from line 3577
* **Type**: Boolean * `true`: Claude Code turns off dynamic workflows and the bundled workflow commands for everyone your settings reach * `false`: the same as unset; whether workflows are on then follows [`enableWorkflows`](#enableworkflows) and your plan's default -* **Default**: `false` -* **Per-session overrides**: [`CLAUDE_CODE_DISABLE_WORKFLOWS`](/docs/en/env-vars) turns workflows off for one session; whichever of the two turns them off, the other can't turn them back on - -```json settings.json theme={null} -{ - "disableWorkflows": true -} -``` - -### `enableWorkflows` - -Turn [dynamic workflows](/docs/en/workflows) on or off for yourself when your plan's defa +* **Def
settings-reference Changed · +21 / -0 lines
### `disableDesktopLocalSessions`
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 636
| [`disableClaudeAiConnectors`](#disableclaudeaiconnectors) | Turn off [claude.ai connectors](/docs/en/mcp#disable-claude-ai-connectors) so Claude Code doesn't fetch them | MCP | Any file | | [`disableCommandPluginSources`](#disablecommandpluginsources) | Block [plugins](/docs/en/plugins) that install by running a marketplace-declared command | Plugins and skills | Managed | | [`disableDeepLinkRegistration`](#disabledeeplinkregistration) | Stop Claude Code from registering the [`claude-cli://` handler](/docs/en/deep-links) | Remote, desktop, and notifications | Any file | +| [`disableDesktopLocalSessions`](#disabledesktoplocalsessions) | Turn off [Desktop Code sessions](/docs/en/desktop#local-sessions-on-managed-devices) that run on the device, leaving SSH to other hosts and cloud | Remote, desktop, and notifications | Managed | | [`disabledMcpjsonServers`](#disabledmcpjsonservers) | Reject specific servers from a project's [`.mcp.json`](/docs/en/mcp#project-scope) | MCP | Any file | | [`disableMobileSimulatorTools`](#disablemobilesimulatortools) | Block Claude's tools in the [desktop](/docs/en/desktop) iOS Simulator pane | Tools | Managed | | [`disableRemoteControl`](#disableremotecontrol) | Turn off [Remote Control](/docs/en/remote-control) everywhere it can start | Remote, desktop, and notifications | Any file |
from line 3587
### `enableWorkflows` -Turn [dynamic workflows](/docs/en/workflows) on or off for yourself when your plan's default isn't what you want. Appears in `/config` as **Dynamic workflows**, which writes this key to your user settings and removes it again when you toggle back to your plan's default. To turn workflows off for everyone from managed settings, use [`disableWorkflows`](#disableworkflows) instead. - -* **Scope**: [`Any file`](#scopes) -* **Type**: Boolean - * `true`: Claude Code turns dynamic wor +Turn [dynamic workflows](/docs/en/workflows) on or off for yourself when your plan's defa
settings-reference Changed · +45 / -0 lines
### `promptCacheTtl` ### `subagentPromptCacheTtl`
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 700
| [`preferredNotifChannel`](#preferrednotifchannel) | Choose a [terminal bell or desktop notification](/docs/en/terminal-config#get-a-terminal-bell-or-notification) for task completion | Remote, desktop, and notifications | Any file | | [`prefersReducedMotion`](#prefersreducedmotion) | [Reduce or turn off](/docs/en/accessibility#accessibility-settings) spinner, shimmer, and flash animations | Interface and terminal | Any file | | [`processWrapper`](#processwrapper) | Run Claude Code's background processes through a [corporate launcher](/docs/en/corporate-launcher) on macOS and Linux | Agents, sessions, and worktrees | User or managed | +| [`promptCacheTtl`](#promptcachettl) | Choose the [prompt cache lifetime](/docs/en/prompt-caching#cache-lifetime) for the main conversation | Model and responses | Any file | | [`promptSuggestionEnabled`](#promptsuggestionenabled) | Hide the grayed-out [prompt suggestions](/docs/en/interactive-mode#prompt-suggestions) in the input box | Interface and terminal | Any file | | [`prUrlTemplate`](#prurltemplate) | Point PR links at an internal code-review tool instead of github.com | Git and attribution | Any file | | [`remote.defaultEnvironmentId`](#remote-defaultenvironmentid) | Pick the default [cloud environment](/docs/en/cloud-environments) for `claude --cloud`; a self-hosted `ccpool_` ID is read only from user and managed settings and `--settings` | Remote, desktop, and notifications | Any file |
from line 769
| [`strictPluginOnlyCustomization.hooks`](#strictpluginonlycustomization-hooks) | Lock [hooks](/docs/en/hooks) to plugin and managed sources | Plugins and skills | Managed | | [`strictPluginOnlyCustomization.mcp`](#strictpluginonlycustomization-mcp) | Lock [MCP servers](/docs/en/mcp) to plugin and managed sources | Plugins and skills | Managed | | [`strictPluginOnlyCustomization.skills`](#strictpluginonlycustomization-skills) | Lock [skills](/docs/en/skills) to plugin and managed sources | Plugins and skills | Managed | +| [`subagentPromptCacheTtl`](#subagentpromptcachettl) | Choose the [prompt cache lifetime](/docs/en/prompt-caching#cache-lifetime) for subagents and other requests outside the main conversation | Model and responses | Any file | | [`subagentStatusLine`](#subagentstatusline) | Rewrite rows in the [subagent](/docs/en/sub-agents) task display with your own command | Interface and terminal | Any file | | [`switchModelsOnFlag`](#switchmodelsonflag) | Switch models automatically or pause when a [safety classifier](/docs/en/model-config#ask-before-switching) flags a request | Model and responses | Any file | | [`syncClaudeAiSkills`](#syncclaudeaiskills) | Stop downloading the [skills enabled on your claude.ai account](/docs/en/skills#how-synced-skills-behave) and hide the ones already synced | Plugins and skills | User, local, or managed |
from line 1076
} ``` +### `promptCacheTtl` + +Choose how long the [prompt cache](/docs/en/prompt-caching) holds the main conversation. This key applies to your interactive, `-p`, and Agent SDK turns, together with the helpers Claude Code runs inline with them. The one-hour lifetime keeps the cache warm across longer breaks, and the API [bills each cache write at a higher rate](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing) than at the five-minute lifetime. Requires Claude Code v2.1.242 or later. + +* **Scope**: [`Any file`](#scopes) +* **Type**: string, one of: + * `"5m"`: the cache holds for five minutes + * `"1h"`: the cache holds for an hour +* **Default**: unset, so each main-conversation request gets [its default lifetime](/docs/en/prompt-caching#which-ttl-each-request-gets) +* **Per-session overrides**: [`FORCE_PROMPT_CACHING_5M`](/docs/en/env-vars) takes precedence over everything else, then [`CLAUDE_CODE_PROMPT_CACHE_TTL`](/docs/en/env-vars), then this key, and last [`ENABLE_PROMPT_CACHING_1H`](/docs/en/env-vars) + +This example keeps the main conversation on the one-hour lifetime and leaves subagents on five minutes: + +```json settings.json theme={null} +{ + "promptCacheTtl": "1h", + "subagentPromptCacheTtl": "5m" +} +``` + +For what each lifetime costs, see [Cache lifetime](/docs/en/prompt-caching#cache-lifetime). + ### `showThinkingSummaries` See summaries of Claude's [extended thinking](/docs/en/model-config#extended-thinking) in interactive sessions. Set it if you want the full summaries when you expand thinking with `Ctrl+O`. When unset or `false`, the Anthropic API redacts thinking blocks and Claude Code shows a collapsed stub; third-party providers don't redact.
from line 1116
Redaction only changes what you see, not what the model generates: to reduce thinking spend, [lower the budget or disable thinking](/docs/en/model-config#extended-thinking) instead. This setting has no effect in non-interactive mode (`-p`), the Agent SDK, or IDE extensions such as VS Code. +### `subagentPromptCacheTtl` + +Choose how long the [prompt cache](/docs/en/prompt-caching) holds the requests Claude Code makes outside the main conversation. This key applies to [subagents](/docs/en/sub-agents), [workflows](/docs/en/workflows), and Claude Code's own background and helper requests, such as compaction and session titles. The one-hour lifetime keeps the cache warm across longer breaks, and the API [bills each cache write at a higher rate](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing) than at the five-minute lifetime. Requires Claude Code v2.1.242 or later. + +* **Scope**: [`Any file`](#scopes) +* **Type**: string, one of: + * `"5m"`: the cache holds for five minutes + * `"1h"`: the cache holds for an hour +* **Default**: unset, so each of these requests gets [its default lifetime](/docs/en/prompt-caching#which-ttl-each-request-gets) +* **Per-session overrides**: [`FORCE_PROMPT_CACHING_5M`](/docs/en/env-vars) takes precedence over everything else, then [`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`](/docs/en/env-vars), then this key, and last [`ENABLE_PROMPT_CACHING_1H`](/docs/en/env-vars), which asks for the one-hour lifetime on every request + +This example gives subagents and the other requests outside the main conversation the one-hour lifetime: + +```json settings.json theme={null} +{ + "subagentPromptCacheTtl": "1h" +} +``` + +This key covers the requests [`promptCacheTtl`](#promptcachettl) doesn't, so set both to choose a lifetime for every request Claude Code makes. For how a subagent's cache differs from the main conversation's, see [Subagents and the cache](/docs/en/prompt-caching#subagents-and-the-cache). + ### `switchModelsOnFlag` Choose what happens when a [safety classifier flags a request](/docs/en/model-config#automatic-model-fallback): switch to the fallback model and continue, or pause so you can choose between switching and editing the prompt.
from line 3590
* **Scope**: [`Any file`](#scopes) * **Type**: Boolean - * `true`: Claude Code turns dynamic workflows on for you - * `false`: Claude Code turns dynamic workflows off for you -* **Default**: unset, so workflows are on unless you're on the Pro plan, where they're off -* **Per-session overrides**: [`CLAUDE_CODE_DISABLE_WORKFLOWS`](/docs/en/env-vars) turns workflows off for one session, and `true` here can't turn them back on while it's set - -```json settings.json theme={null} -{ - "enableWorkflows": true -} -``` - -[`disableWorkflows`](#disableworkflows) and your organization's workflows policy also take precedence: `enableWorkflows: true` can't turn workflows back on while any source turns workflows off. Claude Code hides the `/config` row while a source other than your user settings sets `enableWorkflows`, or sets `disableWorkflows` to `true`. - -### `hooks` - -Run your own commands, prompts, agents, HTTP requests, or MCP tools as [hooks](/docs/en/hooks) at points in Claude Code's lifecycle, such as before a tool call or when a session starts; the [hooks reference](/docs/en/hooks#hook-events) lists every event, its payload, and its exit codes. Each event maps to a list of matcher groups, and each group lists the handlers to run when the matcher applies. - -* **Scope**: [`Any file`](#scopes). Hooks merge across files rather than replacing each other, and hooks from managed settings can't be removed from other files. -* **Type**: object keyed by [hook event](/docs/en/hooks#hook-events); each value is an array of `{ "matcher", "hooks" }` groups whose `hooks` entries have a `type` of `"command"`, `"prompt"`, `"agent"`, `"http"`, or `"mcp_tool"` -* **Default**: unset, so no hooks run - -This example runs a script before every Bash tool call: - -```json settings.json theme={null} -{ - "hooks": { - "PreToolUse": [ - { - "matcher": "Bash", - "hooks": [ - { "type": "command", "command": "~/.claude/hooks/check-bash.sh" } - ] - } - ] - } -} -``` - -For every event, matcher pattern, and handler field, see the [hooks reference](/docs/en/hooks#configuration). To turn hooks off, see [`disableAllHooks`](#disableallhooks); to limit hooks to the ones your organization deploys, see [`allowManagedHooksOnly`](#allowmanagedhooksonly). - -### `httpHookAllowedEnvVars` - -An [HTTP hook](/docs/en/hooks#http-hook-fields) can put the value of an environment variable into a request header, for example an `Authorization: Bearer $HOOK_TOKEN` header, but only for variables the hook lists in its own `allowedEnvVars`. This key sets an outer limit on that list for every HTTP hook: a hook can use a variable only if both its own `allowedEnvVars` and this key name it. Use it to stop a hook from reading a secret it shouldn't, even when the hook's definition asks for it. - -* **Scope**: [`Any file`](#scopes). Arrays merge across settings files. -* **Type**: array of environment variable names -* **Default**: unset, so each hook's own `allowedEnvVars` list applies - -This example limits header interpolation to `MY_TOKEN` and `HOOK_SECRET`: - -```json settings.json theme={null} -{ - "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"] -} -``` - -The allowlist applies to hooks from every source, including managed settings. - -### `workflowKeywordTriggerEnabled` - -Choose whether typing the keyword `ultracode` in a prompt triggers a [dynamic workflow](/docs/en/workflows#ask-for-a-workflow-in-your-prompt). Set it to `false` to type the word without triggering one. Requires Claude Code v2.1.157 or later. - -* **Scope**: [`Any file`](#scopes). Appears in `/config` as **Ultracode keyword trigger**. -* **Type**: Boolean - * `true`: typing `ultracode` in a prompt triggers a dynamic workflow - * `false`: you can type the word without triggering one -* **Default**: `true` - -```json settings.json theme={null} -{ - "workflowKeywordTriggerEnabled": false -} -``` - -The `ultracode` effor + * `true`: Claude Code turns dynamic wor
settings-reference Changed · +53 / -2 lines
### `modelPicker` #### Fields for `modelPicker`
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 677
| [`minimumVersion`](#minimumversion) | Keep [auto-updates](/docs/en/setup#pin-a-minimum-version) from installing anything below a version | Updates and versioning | Any file | | [`model`](#model) | Change the [model](/docs/en/model-config#set-a-default-model-for-new-sessions) Claude Code starts with | Model and responses | Any file | | [`modelOverrides`](#modeloverrides) | [Map model IDs](/docs/en/model-config#override-model-ids-per-version) to your provider's IDs, such as Bedrock ARNs | Model and responses | Any file | +| [`modelPicker`](#modelpicker) | Choose which models the [`/model` picker](/docs/en/model-config#available-models) lists, in your own order and with your own labels | Model and responses | User or managed | | [`otelHeadersHelper`](#otelheadershelper) | Generate rotating [OpenTelemetry](/docs/en/monitoring-usage#dynamic-headers) headers with your own command | Authentication and providers | Any file | | [`outputStyle`](#outputstyle) | Change Claude's role, tone, and output format with an [output style](/docs/en/output-styles) | Model and responses | Any file | | [`parentSettingsBehavior`](#parentsettingsbehavior) | Apply or drop restrictions an [SDK or IDE host](/docs/en/managed-settings#let-an-embedding-host-add-policy) passes when you deploy [managed settings](/docs/en/managed-settings) | Enterprise and managed settings | Managed |
from line 1008
See [Override model IDs per version](/docs/en/model-config#override-model-ids-per-version). +### `modelPicker` + +List the models the `/model` picker offers, in the order you write them and under labels you choose, so the picker lists the models your organization runs, after the built-in lineup or instead of it. Each row's `model` is taken verbatim, so it accepts anything `--model` accepts: an alias such as `opus`, an Anthropic model ID, or a provider-format ID for Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or an LLM gateway. Requires Claude Code v2.1.242 or later. + +* **Scope**: [`User or managed`](#scopes). Claude Code reads the key from managed settings, `--settings`, and user settings, and ignores it in project and local settings so a repository you clone can't relabel the picker. The highest of those three that sets the key supplies the whole lineup, and Claude Code never combines lineups from two sources. +* **Type**: object with an `options` array of rows and an optional `replaceBuiltInOptions` Boolean +* **Default**: unset, so the picker shows the built-in lineup + +This example adds two Bedrock deployments after the built-in lineup, under names your team recognizes: + +```json managed-settings.json theme={null} +{ + "modelPicker": { + "options": [ + { "model": "us.anthropic.claude-opus-4-8", "label": "Opus (production)" }, + { + "model": "us.anthropic.claude-sonnet-4-6", + "label": "Sonnet (production)", + "description": "Day-to-day work" + } + ] + } +} +``` + +<span id="modelpicker-options" /> + +<span id="modelpicker-replacebuiltinoptions" /> + +#### Fields for `modelPicker` + +The key takes two fields, one for the rows themselves and one for whether they replace the built-in lineup or add to it. + +| Field | Type | What it does | +| :---------------------- | :------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `options` | array of rows, each with a required `model` and an optional `label` and `description` | The rows the picker shows, in this order, except that a grayed-out row moves to the bottom. Without a `label`, Claude Code titles the row with the built-in name for a model it knows, or the model ID otherwise, and without a `description` it writes a generic second line | +| `replaceBuiltInOptions` | Boolean, default `false` | Set it to `true` to show only these rows, **Default**, and a row for the model the session is already using. Leave it unset to add these rows after the built-in lineup | + +With `replaceBuiltInOptions` on, Claude Code hides every other row: the built-in lineup, the rows it adds for [`availableModels`](#availablemodels) entries, the models [gateway discovery](/docs/en/llm-gateway-protocol#model-discovery) found, and [`ANTHROPIC_CUSTOM_MODEL_OPTION`](/docs/en/model-config#add-a-custom-model-option). With it off, Claude Code skips a listed model that the built-in lineup already covers. A label changes what the picker shows, not which model Claude Code runs. + +An [`availableModels`](#availablemodels) allowlist still applies to these rows. Before you add a listed model to the allowlist, read [Merge behavior](/docs/en/model-config#merge-behavior): a specific model ID narrows its family's wildcard entry. Claude Code also checks each row against the session before it shows the picker: + +* **Dropped**: a row Claude Code can't serve, such as a retired model or a model your organization has no access to +* **Grayed out**: a row you can't select yet, shown with the reason +* **No row survives**: Claude Code keeps the built-in lineup, filtered by the allowlist as usual + +Claude Code drops a row it can't parse and keeps the rest. See [Fix a broken settings file](/docs/en/settings#fix-a-broken-settings-file). + ### `outputStyle` Select an [output style](/docs/en/output-styles) by name. An output style is a saved set of instructions that Claude Code adds to the system prompt to change Claude's role, tone, and output format, such as the built-in Explanatory and Learning styles or one you wrote yourself.
from line 3506
The reach depends on which file carries the key: -* **In managed settings**: Claude Code disables every hook, including managed ones -* **In any other settings file**: Claude Code disables user, project, local, and plugin hooks; managed hooks and hooks from plugins force-enabled in managed [`enabledPlugins`](#enabledplugins) keep running +* **In managed settings**: Claude Code disables every configured hook, including managed ones, and keeps running the hooks the [Agent SDK](/docs/en/agent-sdk/overview) registers in process +* **In any other settings file**: Claude Code disables user, project, local, and plugin hooks; managed hooks, Agent SDK hooks, and hooks from plugins force-enabled in managed [`enabledPlugins`](#enabledplugins) keep running +Keeping Agent SDK hooks running when managed settings set this key requires Claude Code v2.1.242 or later. + The [`/goal`](/docs/en/goal) command can't run while hooks are disabled, and the `/hooks` menu shows a notice instead of your hooks. #### Status line and file suggestion gates
from line 3619
} ``` -The `ultracode` effort setting, `/workflows`, and saved workflow commands are unaffected. Requires Claude Code v2.1.157 or later. Before v2.1.160, the trigger keyword was `workflow`. - -### `workflowSizeGuideline` - -Set the [agent count Claude aims for](/docs/en/workflows#set-a-size-guideline) in the dynamic workflows it writes. Claude Code sends the value to Claude as advice, not an enforced cap: `"small"` asks for fewer than 5 agents, `"medium"` fewer than 15, and `"large"` fewer than 50. Choose `"small"` when you want to bound what a workflow spends. Requires Claude Code v2.1.219 or later. - -* **Scope**: [`Any file`](#scopes). A value there takes precedence over the **Dynamic workflow size** choice in `/config`, which Claude Code stores in `~/.claude.json`, and Claude Code hides that row while a settings file sets the key. -* **Type**: string, one of: - * `"unrestricted"`: no guideline, so Claude sizes the workflow to the task - * `"small"`: Claude aims for fewer than 5 agents - * `"medium"`: Claude aims for fewer than 15 agents - * `"large"`: Claude aims for fewer than 50 agents -* **Default**: `"medium"` - -```json settings.json theme={null} -{ - "workflowSizeGuideline": "small" -} -``` - -Requires Claude Code v2.1.219 or later; on v2.1.202 through v2.1.218, set the guideline in `/config` instead. - -<span id="plugin-configuration" /> - -<span id="manage-plugins" /> - -<span id="plugin-settings" /> - -## Plugins and skills - -Enable plugins, register marketplaces, restrict which plugin sources an organization allows, and control which skills load. For installing and building plugins, see [Plugins](/docs/en/plugins). - -### `disableBundledSkills` - -Turn off the [skills](/docs/en/skills) and workflows included with Claude Code. Claude Code removes bundled skills and workflows entirely, while built-in commands such as `/init` stay typable but are hidden from the model. - -* **Scope**: [`Any file`](#scopes) -* **Type**: Boolean - * `true`: Claude Code removes bundled skills and workflows and hides built-in commands such as `/init` from the model - * `false`: bundled skills load -* **Default**: unset, so bundled skills load -* **Per-session overrides**: [`CLAUDE_CODE_DISABLE_BUNDLED_SKILLS`](/docs/en/env-vars) set to `1` turns bundled skills off for one session; whichever of the two turns them off, the other can't turn them back on - -```json settings.json theme={null} -{ - "disableBundledSkills": true -} -``` - -Skills from plugins, `.claude/skills/`, and `.claude/commands/` are unaffected. `/doctor` stays typable like the built-in commands; to hide it, set [`DISABLE_DOCTOR_COMMAND`](/docs/en/env-vars) instead. - -### `disableSkillShellExecution` - -Turn off inline shell execution for `` !`...` `` and ` ```! ` blocks in [skills](/en/skills) and custom commands from user, project, plugin, or additional-directory sources. Claude Code replaces each command with `[shell command execution disabled by policy]` instead of running it. - -* **Scope**: [`Any file`](#scopes). A `true` in managed settings can't be overridden by `false` elsewhere. -* **Type**: Boolean - * `true`: Claude Code replaces each inline shell command with `[shell command execution disabled by policy]` instead of running it - * `false`: inline shell runs -* **Default**: unset, so inline shell runs - -```json settings.json theme={null} -{ - "disableSkillShellExecution": true -} -``` - -Bundled skills and skills deployed through managed settings are unaffected. - -### `skillOverrides` - -Hide or collapse a [skill](/docs/en/skills#override-skill-visibility-from-settings) without editing its `SKILL.md`. Claude Code applies the value under each skill's name to the skill list Claude sees and to your `/` autocomplete. - -* **Scope**: [`Any file`](#scopes). The `/skills` menu writes to `.claude/settings.local.json`. -* **Type**: object mapping skill name to one of: - * `"on"`: Claude sees the skill and you can type `/name` - * `"name-only"`: Claude sees the skill by name without its description - * `"user-invocable-only"`: Claude doesn't see the skill, but you can still type `/name` - * `"off"`: Claude doesn't see the skill and `/name` is hidden from autocomplete -* **Default**: unset, so every skill is `"on"` - -This example lists `legacy-context` to Claude by name only and hides `deploy` from Claude and from `/` autocomplete: - -```json settings.json theme={null} -{ - "skillOverrides": { - "legacy-context": "name-only", - "deploy": "off" - } -} -``` - -`"name-only"` lists the skill to the model without its description, `"user-invocable-only"` hides it from the model but keeps `/name` typable, and `"off"` hides it from both. Overrides don't apply to plugin skills, which you manage through `/plugin`. - -### `syncClaudeAiSkills` - -Turn off the download of the [skills you enable on claude.ai](/docs/en/skills#how-synced-skills-behave). Claude Code downloads them into `~/.claude/skills/synced/` when you run it in [non-interactive mode](/docs/en/headless) with the `-p` flag and [`CLAUDE_CODE_SYNC_SKILLS`](/docs/en/env-vars#variables) set. Set `false` to stop that download and hide the skills it already synced. Claude Code honors only `false` +The `ultracode` effor
settings-reference Changed · +39 / -4 lines
### `autoContinueAtUsageLimit`
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 602
| [`autoCompactEnabled`](#autocompactenabled) | Turn [automatic compaction](/docs/en/context-window) off or on | Memory and context | Any file | | [`autoCompactWindow`](#autocompactwindow) | Set how full the context gets before Claude Code [compacts](/docs/en/context-window) | Memory and context | Any file | | [`autoConnectIde`](#autoconnectide) | Connect to a running [VS Code](/docs/en/vs-code) or [JetBrains](/docs/en/jetbrains#from-external-terminals) IDE automatically from an external terminal | Global config settings | Global config | +| [`autoContinueAtUsageLimit`](#autocontinueatusagelimit) | Wait in the open session and [continue the task automatically](/docs/en/interactive-mode#wait-for-a-usage-limit-to-reset) after a claude.ai usage limit resets | Interface and terminal | User or managed | | [`autoInstallIdeExtension`](#autoinstallideextension) | Turn off automatic install of the [IDE extension](/docs/en/vs-code#install-the-extension) from a VS Code terminal | Global config settings | Global config | | [`autoMemoryDirectory`](#automemorydirectory) | Store [auto memory](/docs/en/memory#auto-memory) in a directory you choose | Memory and context | Any file | | [`autoMemoryEnabled`](#automemoryenabled) | Turn [auto memory](/docs/en/memory#auto-memory) off or on | Memory and context | Any file |
from line 1533
} ``` -Claude Code enforces these lists at the OS sandbox boundary, so they apply to every subprocess a sandboxed command starts, such as `kubectl`, `terraform`, or `npm`, not only to Claude's file tools. Your [permission rules](/docs/en/sandboxing#permission-rules) feed the same lists: `Edit` allow and deny rules join `allowWrite` and `denyWrite`, `Read` deny rules join `denyRead`, and `WebFetch` allow and deny rules join the [`network`](#sandbox-network) domain lists. Every list merges across settings files. When you edit a list during a session, Claude Code [applies the change to the running session](/docs/en/settings#when-edits-take-effect). +Claude Code enforces these lists at the OS sandbox boundary, so they apply to every subprocess a sandboxed command starts, such as `kubectl`, `terraform`, or `npm`, not only to Claude's file tools. Your [permission rules](/docs/en/sandboxing#permission-rules) feed the same lists: `Edit` allow and deny rules join `allowWrite` and `denyWrite`, `Read` deny rules join `denyRead`, and `WebFetch(domain:...)` allow and deny rules join the [`network`](#sandbox-network) domain lists. Every list merges across settings files. When you edit a list during a session, Claude Code [applies the change to the running session](/docs/en/settings#when-edits-take-effect). #### Sandbox path prefixes
from line 2575
Appears in `/config` as **Question auto-continue timeout**, which writes this key to user settings; Claude Code hides the row while managed settings or the `--settings` flag set the key. Requires Claude Code v2.1.200 or later. +### `autoContinueAtUsageLimit` + +After a claude.ai usage limit stops your session, wait in the open session and continue the task automatically after the reset. See [Turn automatic continue off](/docs/en/interactive-mode#turn-automatic-continue-off). Requires Claude Code v2.1.234 or later. + +* **Scope**: [`User or managed`](#scopes). Read from user settings, `--settings`, and managed settings only. When none of those sets the key, a project or local settings file that sets it turns the feature off rather than being ignored. +* **Type**: Boolean + * `true`: after a claude.ai usage limit stops your session, Claude Code waits in the open session and continues the task automatically after the reset + * `false`: Claude Code doesn't start the wait on its own. You can still [start a wait yourself](/docs/en/interactive-mode#start-a-wait-yourself) from the usage-limit options menu +* **Default**: `true` + +```json settings.json theme={null} +{ + "autoContinueAtUsageLimit": false +} +``` + +Appears in `/config` as **Continue automatically at usage limit**, which writes this key to user settings; Claude Code hides the row while managed settings or the `--settings` flag set the key. + ### `autoScrollEnabled` Follow new output to the bottom of the conversation in [fullscreen rendering](/docs/en/fullscreen). Turn it off to stay where you scrolled while Claude keeps working; permission prompts still scroll into view.
from line 3434
* **Force-enabled plugin hooks run**: hooks from plugins your managed settings force-enable through [`enabledPlugins`](#enabledplugins). Claude Code matches on the full `plugin@marketplace` ID, so a plugin with the same name from a different marketplace stays blocked. This lets you distribute vetted hooks through an organization marketplace while blocking everything else * **Everything else is blocked**: user, project, and local hooks, hooks from other plugins, and hooks declared in agent frontmatter * **Command-sourced plugins are disabled**: Claude Code also disables plugins with a [`command` source](/docs/en/plugin-marketplaces#command-sources), including plugins force-enabled in managed `enabledPlugins`, unless you set [`disableCommandPluginSources`](#disablecommandpluginsources) to `false` explicitly +* **Marketplace `headersHelper` commands are blocked**: Claude Code also blocks marketplace [`headersHelper` commands](/docs/en/plugin-marketplaces#authenticate-archive-downloads) unless [`disableCommandPluginSources`](#disablecommandpluginsources) is explicitly set to `false`, except for a marketplace that managed settings themselves declare. Requires Claude Code v2.1.238 or later * **Status line and file suggestion narrow to managed settings**: Claude Code reads [`statusLine`](/docs/en/statusline), [`fileSuggestion`](#filesuggestion), and [`subagentStatusLine`](/docs/en/statusline#subagent-status-lines) from managed settings only, following the [status line and file suggestion gates](#status-line-and-file-suggestion-gates) The [`/goal`](/docs/en/goal) command can't run while this key is set, because it depends on hooks.
from line 3664
### `syncClaudeAiSkills` -Turn off the download of the [skills you enable on claude.ai](/docs/en/skills#how-synced-skills-behave). Claude Code downloads them into `~/.claude/skills/synced/` when you run it in [non-interactive mode](/docs/en/headless) with the `-p` flag and [`CLAUDE_CODE_SYNC_SKILLS`](/docs/en/env-vars#variables) set. Set `false` to stop that download and hide the skills it already synced. Claude Code honors only `false`: `true` is the same as unset and doesn't turn syncing on. - -* **Scope**: [`User, local, or managed`](#scopes). A repository can't turn it off for you. -* **Type**: Boolean - * `false`: Claude Code stops downloading synced skills and hides the ones already in `~/.claude/skills/synced/`. In user or managed settings, it also moves them to `~/.claude/skills/.trash/` - * `true`: the same as unset -* **Default**: unset, so a non-interactive run with `CLAUDE_CODE_SYNC_SKILLS` set downloads the skills - -This example keeps a machine from downloading the account's skills, whatever a session sets in its environment: - -```json settings.json theme={null} -{ - "syncClaudeAiSkills": false -} -``` - -### `allowedChannelPlugins` - -Choose which [channel](/docs/en/channels) plugins can push messages into sessions in your organization. When you set it, Claude Code uses your list in place of the default Anthropic allowlist; each entry names a plugin and the marketplace it comes from. - -* **Scope**: [`Managed`](#scopes) -* **Type**: array of objects, each with `marketplace` and `plugin` strings -* **Default**: unset, so Claude Code uses the default Anthropic allowlist - -This example turns channels on and allows only the Telegram plugin from the official Anthropic marketplace: - -```json managed-settings.json theme={null} -{ - "channelsEnabled": true, - "allowedChannelPlugins": [ - { "marketplace": "claude-plugins-official", "plugin": "telegram" } - ] -} -``` - -An empty array blocks every channel plugin. This key takes effect once channels pass the [`channelsEnabled`](#channelsenabled) gate for the account: on Team and Enterprise plans, and on Console accounts with managed settings, that means `channelsEnabled: true`. See [Restrict which channel plugins can run](/docs/en/channels#restrict-which-channel-plugins-can-run). - -### `blockedMarketplaces` - -Block plugin marketplace sources for your organization. Claude Code checks the blocklist on marketplace add and on plugin instal +Turn off the download of the [skills you enable on claude.ai](/docs/en/skills#how-synced-skills-behave). Claude Code downloads them into `~/.claude/skills/synced/` when you run it in [non-interactive mode](/docs/en/headless) with the `-p` flag and [`CLAUDE_CODE_SYNC_SKILLS`](/docs/en/env-vars#variables) set. Set `false` to stop that download and hide the skills it already synced. Claude Code honors only `false`
settings-reference Changed · +3 / -3 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 1318
} ``` -Permission rules layer on top of every mode: `deny` rules block in every mode, including `bypassPermissions`. See [Permission modes](/docs/en/permission-modes). `manual` names the permission mode labeled Manual in the CLI and the VS Code extension; the alias requires Claude Code v2.1.200 or later. Before v2.1.142, project settings could set `auto`. In Claude Code on the web, Claude Code honors only `acceptEdits`, `plan`, `default`, and `auto` from this key. For conversations the VS Code extension starts, see [which setting the extension reads for the starting permission mode](/docs/en/permission-modes#switch-permission-modes). +Permission rules layer on top of every mode: `deny` rules block in every mode, including `bypassPermissions`. See [Permission modes](/docs/en/permission-modes). `manual` names the permission mode labeled Manual in the CLI and the VS Code extension; the alias requires Claude Code v2.1.200 or later. In Claude Code on the web, Claude Code honors only `acceptEdits`, `plan`, `default`, and `auto` from this key. For conversations the VS Code extension starts, see [which setting the extension reads for the starting permission mode](/docs/en/permission-modes#switch-permission-modes). ### `permissions.disableBypassPermissionsMode`
from line 3683
### `blockedMarketplaces` -Block plugin marketplace sources for your organization. Claude Code checks t +Block plugin marketplace sources for your organization. Claude Code checks the blocklist on marketplace add and on plugin instal
settings-reference Changed · +5 / -3 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
settings-reference Changed · +9 / -22 lines
## Scopes
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 560
<BackToIndex href="#all-settings" label="Back to index" /> -This reference page lists each key Claude Code reads from a settings file, plus the [short group of keys](#global-config-settings) it keeps in `~/.claude.json` instead. +This reference page lists each key Claude Code reads from a settings file, plus the [short group of keys](#global-config-settings) it keeps in `~/.claude.json` instead. To pick a file, or check precedence, start with [Claude Code settings](/docs/en/settings). -Use the [index](#all-settings) to find a key by name or purpose and to see its topic and scope, then open the key's linked entry for what it lets you do, where Claude Code reads it from, its type and default, and a minimal example to paste. - -For how to apply these settings, which settings file to use, and which value Claude Code uses when a key is set in more than one place, see [Claude Code settings](/docs/en/settings). - -## Scopes - -Claude Code reads settings from four files, and not every key works in every file. The **Scope** of a key names the files that can set it. - -* **User**: `~/.claude/settings.json`. Yours, in every project. -* **Project**: `.claude/settings.json`. Checked into the repository, so everyone who clones it gets these settings. -* **Local**: `.claude/settings.local.json`. Yours, in this project only. Claude Code keeps it out of git when it creates the file. -* **Managed**: settings your organization deploys; see [Managed settings](/docs/en/managed-settings). - -`Any file` means all four. The `--settings` flag isn't a scope: it's a command line override that sits above the user, project, and local files and below managed settings in [settings precedence](/docs/en/settings#settings-precedence), and an entry says so when the flag is treated differently for its key. `Global config` keys aren't in a settings file at all: Claude Code keeps them in `~/.claude.json` and writes them when you change one in `/config`. - <span id="available-settings" /> +<span id="scopes" /> + ## All settings -Every key, grouped by topic below and listed here in one table. Filter the table by a key name or a word from its purpose, read the Scope column for which files can set the key, then follow the link to its entry. +Every key below links to its entry. Scope lists the [files](/docs/en/settings#settings-files-and-who-they-affect) it can go in: `User` is `~/.claude/settings.json`, `Project` is `.claude/settings.json`, `Local` is `.claude/settings.local.json`, and `Managed` is [what your organization deploys](/docs/en/managed-settings). `Any file` means all four, and `Global config` means [`~/.claude.json`](#global-config-settings). <ReferenceFilter noun="settings"
from line 2805
} ``` -See [Make Ctrl+W delete back to whitespace](/docs/en/interactive-mode#make-ctrl-w-delete-back-to-whitespace). Requires Claude Code v2.1.238 or later. +See [Make editing keys follow readline conventions](/docs/en/interactive-mode#make-ctrl-w-delete-back-to-whitespace) for the per-key behavior. ### `prefersReducedMotion`
from line 3103
* **Type**: string, one of: * `"default"`: the classic main-screen renderer * `"fullscreen"`: the flicker-free alt-screen renderer with virtualized scrollback -* **Default**: unset, so Claude Code picks the renderer by rollout: fullscreen if you first used Claude Code on or after May 6, 2026, otherwise the classic renderer +* **Default**: unset, so Claude Code [picks the renderer for you](/docs/en/fullscreen#fullscreen-by-default) * **Per-session overrides**: [`CLAUDE_CODE_NO_FLICKER`](/docs/en/env-vars) and [`CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN`](/docs/en/env-vars) take precedence over this key for one session: `CLAUDE_CODE_NO_FLICKER=1` turns fullscreen on, and `CLAUDE_CODE_NO_FLICKER=0` or `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1` turns it off; when both are set, Claude Code turns it off ```json settings.json theme={null}
from line 3662
### `allowedChannelPlugins` -Choose which +Choose which [channel](/docs/en/channels) plugins can push messages into sessions in your organization. When you set it, Claude Code uses your list in place of the default Anthropic allowlist; each entry names a plugin and the marketplace it comes from. + +* **Scope**: [`Managed`](#scopes) +* **Type**: array of objects, each with `marketplace` and `plugin` strings +* **Default**: unset, so Claude Code uses the default Anthropic allowlist + +This example turns channels on and allows only the Telegram plugin from the official Anthropic marketplace: + +```json managed-settings.json theme={null} +{ + "channelsEnabled": true, + "allowedChannelPlugins": [ + { "marketplace": "claude-plugins-official", "plugin": "telegram" } + ] +} +``` + +An empty array blocks every channel plugin. This key takes effect once channels pass the [`channelsEnabled`](#channelsenabled) gate for the account: on Team and Enterprise plans, and on Console accounts with managed settings, that means `channelsEnabled: true`. See [Restrict which channel plugins can run](/docs/en/channels#restrict-which-channel-plugins-can-run). + +### `blockedMarketplaces` + +Block plugin marketplace sources for your organization. Claude Code checks t
settings-reference New page · 5350 lines, new page
# Claude Code settings reference ## Scopes ## All settings ## Model and responses ### `advisorModel` ### `alwaysThinkingEnabled` ### `availableModels` ### `effortLevel` ### `enforceAvailableModels` ### `fallbackModel` ### `fastMode` ### `fastModePerSessionOptIn` ### `language` ### `model` ### `modelOverrides` ### `outputStyle` ### `showThinkingSummaries` ### `switchModelsOnFlag` ### `ultracode` ## Permission settings ### `allowManagedPermissionRulesOnly` ### `autoMode` ### `autoMode.classifyAllShell` ### `disableAutoMode` ### `permissions` ### `useAutoModeDuringPlan` ### `permissions.allow` #### Permission rule syntax ### `permissions.ask` ### `permissions.deny` ### `permissions.additionalDirectories` ### `permissions.defaultMode` ### `permissions.disableBypassPermissionsMode` ### `skipAutoPermissionPrompt` ### `skipDangerousModePermissionPrompt` ## Sandbox settings ### `sandbox` ### `sandbox.enabled` ### `sandbox.failIfUnavailable` ### `sandbox.autoAllowBashIfSandboxed` ### `sandbox.excludedCommands` ### `sandbox.allowUnsandboxedCommands` ### `sandbox.filesystem` #### Sandbox path prefixes ### `sandbox.filesystem.allowWrite` ### `sandbox.filesystem.denyWrite` ### `sandbox.filesystem.denyRead` ### `sandbox.filesystem.allowRead` ### `sandbox.filesystem.allowManagedReadPathsOnly` ### `sandbox.filesystem.disabled` ### `sandbox.ignoreViolations` ### `sandbox.enableWeakerNestedSandbox` ### `sandbox.enableWeakerNetworkIsolation` ### `sandbox.allowAppleEvents` ### `sandbox.ripgrep` ### `sandbox.bwrapPath` ### `sandbox.socatPath` ### `sandbox.credentials` #### Invalid credential entries in managed settings ### `sandbox.credentials.files` #### Mask fields for files ### `sandbox.credentials.envVars` #### Mask fields for environment variables ### `sandbox.credentials.allowPlaintextInject` ### `sandbox.credentials.awsPairs` ### `sandbox.credentials.sigv4` ### `sandbox.network` ### `sandbox.network.allowUnixSockets` ### `sandbox.network.allowAllUnixSockets` ### `sandbox.network.allowLocalBinding` ### `sandbox.network.allowMachLookup` ### `sandbox.network.allowedDomains` ### `sandbox.network.deniedDomains` ### `sandbox.network.strictAllowlist` ### `sandbox.network.allowManagedDomainsOnly` ### `sandbox.network.httpProxyPort` ### `sandbox.network.socksProxyPort` ### `sandbox.network.tlsTerminate` ## Memory and context ### `autoCompactEnabled` ### `autoCompactWindow` ### `autoMemoryDirectory` ### `autoMemoryEnabled` ### `claudeMd` ### `claudeMdExcludes` ### `env` #### How `env` values interact with your shell #### When Claude Code applies `env` values #### Variables Claude Code ignores in `env` ### `fileCheckpointingEnabled` ### `plansDirectory` ### `skillListingBudgetFraction` ### `skillListingMaxDescChars` ## Interface and terminal ### `askUserQuestionTimeout` ### `autoScrollEnabled` ### `axScreenReader` ### `companyAnnouncements` ### `defaultShell` ### `dialogExpiry` ### `editorMode` ### `emojiCompletionEnabled` ### `fileSuggestion` #### Command input and output ### `footerLinksRegexes` #### Badge constraints ### `keybindingFlavor` ### `prefersReducedMotion` ### `promptSuggestionEnabled` ### `respectGitignore` ### `respondToBashCommands` ### `showClearContextOnPlanAccept` ### `showTurnDuration` ### `spellcheck` ### `spinnerTipsEnabled` ### `spinnerTipsOverride` ### `spinnerVerbs` ### `statusLine` ### `subagentStatusLine` ### `syntaxHighlightingDisabled` ### `terminalProgressBarEnabled` ### `terminalTitleFromRename` ### `theme` ### `tui` ### `verbose` ### `viewMode` ### `vimInsertModeRemaps` ### `voice` ### `voiceEnabled` ### `wheelScrollAccelerationEnabled` ## Git and attribution ### `attribution` ### `includeCoAuthoredBy` ### `includeGitInstructions` ### `prUrlTemplate` ### `attribution.commit` ### `attribution.pr` ### `attribution.sessionUrl` ## Hooks and automation ### `allowedHttpHookUrls` ### `allowManagedHooksOnly` #### What runs under `allowManagedHooksOnly` ### `disableAllHooks` #### Status line and file suggestion gates ### `disableWorkflows` ### `enableWorkflows` ### `hooks` ### `httpHookAllowedEnvVars` ### `workflowKeywordTriggerEnabled` ### `workflowSizeGuideline` ## Plugins and skills ### `disableBundledSkills` ### `disableSkillShellExecution` ### `skillOverrides` ### `syncClaudeAiSkills` ### `allowedChannelPlugins` ### `blockedMarketplaces` ### `channelsEnabled` ### `disableCommandPluginSources` ### `pluginSuggestionMarketplaces` ### `pluginTrustMessage` ### `strictKnownMarketplaces` #### Allowed source types #### Owner wildcards #### Exact matching #### Allow only the official marketplace #### Combine with `extraKnownMarketplaces` ### `strictPluginOnlyCustomization` ### `strictPluginOnlyCustomization.skills` ### `strictPluginOnlyCustomization.agents` ### `strictPluginOnlyCustomization.hooks` ### `strictPluginOnlyCustomization.mcp` ### `enabledPlugins` ### `extraKnownMarketplaces` #### Marketplace source types #### Marketplace key aliases ### `pluginConfigs` ## MCP ### `allowAllClaudeAiMcps` ### `allowedMcpServers` ### `allowManagedMcpServersOnly` ### `deniedMcpServers` ### `disableClaudeAiConnectors` ### `disabledMcpjsonServers` ### `enableAllProjectMcpServers` ### `enabledMcpjsonServers` ## Agents, sessions, and worktrees ### `agent` ### `crossSessionInbound` ### `disableAgentView` ### `isolatePeerMachines` ### `processWrapper` ### `teammateMode` ### `worktree` ### `worktree.baseRef` ### `worktree.symlinkDirectories` ### `worktree.sparsePaths` ### `worktree.bgIsolation` ## Remote, desktop, and notifications ### `agentPushNotifEnabled` ### `awaySummaryEnabled` ### `disableArtifact` ### `disableDeepLinkRegistration` ### `disableRemoteControl` ### `enableArtifact` ### `inputNeededNotifEnabled` ### `preferredNotifChannel` ### `remote.defaultEnvironmentId` ### `remoteControlAtStartup` ### `sshConfigs` ### `sshHostAllowlist` ## Authentication and providers ### `apiKeyHelper` ### `awsAuthRefresh` ### `awsCredentialExport` ### `forceLoginMethod` ### `forceLoginGatewayUrl` ### `forceLoginOrgUUID` ### `gcpAuthRefresh` ### `otelHeadersHelper` ## Updates and versioning ### `autoUpdatesChannel` ### `minimumVersion` ### `requiredMaximumVersion` ### `requiredMinimumVersion` ## Tools ### `browserExternalPageTools` ### `disableBrowserExternalNavigation` ### `disableMobileSimulatorTools` ## Privacy and telemetry ### `cleanupPeriodDays` ### `feedbackSurveyRate` ### `skipWebFetchPreflight` ## Enterprise and managed settings ### `disableSideloadFlags` ### `forceRemoteSettingsRefresh` ### `parentSettingsBehavior` ### `policyHelper` #### Write the helper output ### `policyHelper.path` ### `policyHelper.timeoutMs` ### `policyHelper.refreshIntervalMs` ### `wslInheritsWindowsSettings` ## Global config settings ### `autoConnectIde` ### `autoInstallIdeExtension` ### `diffTool` ### `externalEditorContext` ### `permissionExplainerEnabled` ### `teammateDefaultModel` ## See also
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
A whole new page. There's nothing to diff it against, so here is what it says.
# Claude Code settings reference
> Complete reference for every Claude Code settings.json key: where each one goes, its type and default, and a paste-ready example, with an index of every key.
export const BackToIndex = ({href = '#all-settings', label = 'Back to index'}) => {
const [show, setShow] = useState(false);
useEffect(() => {
const onScroll = () => setShow(window.scrollY > window.innerHeight);
onScroll();
window.addEventListener('scroll', onScroll, {
passive: true
});
return () => window.removeEventListener('scroll', onScroll);
}, []);
return <div className="not-prose">
<style>{`
.bti-btn {
position: fixed; right: 20px; bottom: 20px; z-index: 40;
display: inline-flex; align-items: center; gap: 6px;
padding: 8px 12px; border-radius: 999px;
font-size: 13px; font-weight: 500; line-height: 1; text-decoration: none;
color: #1f1f1f; background: #ffffff; border: 1px solid #d9d9d9;
box-shadow: 0 2px 8px rgba(0,0,0,0.12);
opacity: 0; pointer-events: none; transform: translateY(6px);
transition: opacity 160ms ease, transform 160ms ease;
}
.bti-btn.bti-show { opacity: 1; pointer-events: auto; transform: translateY(0); }
.bti-btn:hover { border-color: #b3b3b3; }
.dark .bti-btn { color: #ececec; background: #1e1e1e; border-color: #3a3a3a; box-shadow: 0 2px 8px rgba(0,0,0,0.5); }
.dark .bti-btn:hover { border-color: #5a5a5a; }
@media print { .bti-btn { display: none; } }
`}</style>
<a className={'bti-btn' + (show ? ' bti-show' : '')} href={href} aria-hidden={!show} tabIndex={show ? 0 : -1}>
<svg width="12" height="12" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true"><path d="M8 13V3M3.5 7.5 8 3l4.5 4.5" /></svg>
{label}
</a>
</div>;
};
export const ReferenceFilter = ({placeholder, noun, facets, facetOrder, columnHelp, children}) => {
const useLive = init => {
const [v, setV] = useState(init);
const ref = useRef(init);
return [v, ref, x => {
ref.current = x;
setV(x);
}];
};
const cap = s => s.charAt(0).toUpperCase() + s.slice(1);
const plural = s => s.endsWith('y') ? s.slice(0, -1) + 'ies' : s + 's';
const facetNames = facets || ['category', 'topic', 'scope', 'where'];
const orderOf = {};
Object.keys(facetOrder || ({})).forEach(k => {
orderOf[k] = facetOrder[k].map(x => String(x).toLowerCase());
});
const rankIn = (col, v) => {
const list = orderOf[col];
if (!list) return -1;
const i = list.indexOf(String(v).toLowerCase());
return i < 0 ? list.length : i;
};
const cmpValues = col => (a, b) => {
const ra = rankIn(col, a);
const rb = rankIn(col, b);
if (ra !== rb) return ra - rb;
return a < b ? -1 : a > b ? 1 : 0;
};
const help = columnHelp || ({});
const FIRST_COL_HELP = 'Click an entry to open it.';
const optionLabel = (f, c) => c === 'All' ? 'All ' + plural(f.label.toLowerCase()) : c;
const nounText = noun || 'entries';
const placeholderText = placeholder || 'Filter this reference';
const rootRef = useRef(null);
const tablesRef = useRef(null);
const searchRef = useRef(null);
const menuRef = useRef({});
const [q, qRef, setQ] = useLive('');
const [sel, selRef, setSel] = useLive({});
const [sortBy, sortRef, setSortBy] = useLive(null);
const [menuOpen, menuOpenRef, setMenu] = useLive(null);
const [facetList, setFacetList] = useState([]);
const [firstHead, setFirstHead] = useState('');
const [counts, setCounts] = useState({
shown: 0,
total: 0
});
const [disabled, setDisabled] = useState(false);
const menuBtn = name => menuRef.current[name] ? menuRef.current[name].querySelector(':scope > button') : null;
const menuList = name => menuRef.current[name] ? menuRef.current[name].querySelector('[role="listbox"]') : null;
const closeMenu = name => {
setMenu(null);
const btn = menuBtn(name);
if (btn) btn.focus();
};
const focusSelected = name => {
const list = menuList(name);
if (!list) return;
const btn = list.querySelector('button[aria-selected="true"]') || list.querySelector('button');
if (btn) btn.focus();
};
const setFacet = (name, value) => {
setSel(Object.assign({}, selRef.current, {
[name]: value
}));
apply(qRef.current);
closeMenu(name);
};
const sortTables = by => {
(tablesRef.current || []).forEach(tab => {
const t = tab.el;
const idx = tab.heads.indexOf(by);
const body = t.querySelector('tbody');
if (idx < 0 || !body) return;
const rows = [...body.querySelectorAll('tr')];
const keyOf = r => r.children[idx] ? r.children[idx].textContent.trim().toLowerCase() : '';
const cmp = cmpValues(by);
rows.map((r, i) => ({
r,
i: Number(r.dataset.sfIndex !== undefined ? r.dataset.sfIndex : i),
k: keyOf(r)
})).sort((a, b) => cmp(a.k, b.k) || a.i - b.i).forEach(x => body.appendChild(x.r));
[...t.querySelectorAll('thead th')].forEach((h, i) => {
const sortable = tab.heads[i] === tab.heads[0] || facetNames.indexOf(tab.heads[i]) > -1;
if (sortable) h.setAttribute('aria-sort', i === idx ? 'ascending' : 'none'); else h.removeAttribute('aria-sort');
});
});
};
const scan = () => {
const tables = [];
let el = rootRef.current ? rootRef.current.nextElementSibling : null;
while (el) {
if (el.tagName === 'H2' || el.querySelector(':scope > h2')) break;
const found = el.tagName === 'TABLE' ? [el] : [...el.querySelectorAll('table')];
found.forEach(t => {
const headCells = [...t.querySelectorAll('thead th, thead td')];
const heads = headCells.map(h => h.textContent.trim().toLowerCase());
if (heads.length === 0) return;
const facetIdx = {};
heads.forEach((h, i) => {
if (facetNames.indexOf(h) > -1) facetIdx[h] = i;
});
if (!t.dataset.sfDecorated) {
t.dataset.sfDecorated = '1';
headCells.forEach((h, i) => {
const text = i === 0 ? help[heads[0]] || FIRST_COL_HELP : help[heads[i]];
if (text) h.title = text;
});
}
const rows = [...t.querySelectorAll('tbody tr')].map((r, i) => {
if (r.dataset.sfIndex === undefined) r.dataset.sfIndex = String(i);
const cells = r.querySelectorAll('td');
const fv = {};
Object.keys(facetIdx).forEach(h => {
fv[h] = cells[facetIdx[h]] ? cells[facetIdx[h]].textContent.trim() : '';
});
return {
el: r,
text: [...cells].map(c => c.textContent).join(' ').toLowerCase(),
facets: fv,
anchors: [...r.querySelectorAll('a[href^="#"]')].map(a => a.getAttribute('href').slice(1)),
ids: [...r.querySelectorAll('[id]')].map(n => n.id)
};
});
tables.push({
el: t,
box: t.closest('[data-table-wrapper]') || t,
rows,
heads
});
});
el = el.nextElementSibling;
}
tablesRef.current = tables;
if (sortRef.current) sortTables(sortRef.current);
return tables;
};
const apply = query => {
let tables = tablesRef.current || scan();
if (tables.some(t => !t.el.isConnected)) tables = scan();
const needle = query.trim().toLowerCase();
const sel = selRef.current;
const activeFacets = Object.keys(sel).filter(h => sel[h] && sel[h] !== 'All');
const show = (el, on) => {
const want = on ? '' : 'none';
if (el.style.display !== want) el.style.display = want;
};
let total = 0;
let shown = 0;
const visibleTargets = new Set();
tables.forEach(t => {
let tableVisible = 0;
t.rows.forEach(row => {
total += 1;
const catOk = activeFacets.every(h => {
const v = row.facets[h];
return v === sel[h] || v === '' || v === undefined;
});
const match = catOk && (needle === '' || row.text.includes(needle));
show(row.el, match);
if (match) {
tableVisible += 1;
row.anchors.forEach(a => visibleTargets.add(a));
}
});
show(t.box, !(t.rows.length > 0 && tableVisible === 0));
shown += tableVisible;
});
if (shown < total && visibleTargets.size > 0) {
tables.forEach(t => {
t.rows.forEach(row => {
if (row.el.style.display === 'none' && row.ids.some(id => visibleTargets.has(id))) {
show(row.el, true);
show(t.box, true);
shown += 1;
}
});
});
}
setCounts({
shown,
total
});
return total;
};
const deriveFacets = tables => {
const seen = {};
tables.forEach(t => t.rows.forEach(r => {
Object.keys(r.facets).forEach(h => {
if (!seen[h]) seen[h] = [];
if (r.facets[h] && seen[h].indexOf(r.facets[h]) === -1) seen[h].push(r.facets[h]);
});
}));
const list = facetNames.filter(h => seen[h] && seen[h].length > 0).map(h => ({
name: h,
label: cap(h),
values: seen[h].sort(cmpValues(h))
}));
setFacetList(list);
const first = tables[0] ? tables[0].heads[0] : '';
setFirstHead(first);
if (!sortRef.current && first) {
setSortBy(first);
sortTables(first);
}
const init = {};
list.forEach(f => {
init[f.name] = selRef.current[f.name] || 'All';
});
setSel(init);
};
const onChange = value => {
setQ(value);
apply(value);
};
const clearAll = () => {
const next = {};
Object.keys(selRef.current).forEach(k => {
next[k] = 'All';
});
setSel(next);
setQ('');
apply('');
if (searchRef.current) searchRef.current.focus();
};
useEffect(() => {
const tables = scan();
deriveFacets(tables);
const total = apply('');
let retryTimer;
if (total === 0) {
retryTimer = setTimeout(() => {
tablesRef.current = null;
if (apply(qRef.current) > 0) deriveFacets(tablesRef.current); else setDisabled(true);
}, 500);
}
const onKey = e => {
if (e.key === 'Escape' && menuOpenRef.current !== null) closeMenu(menuOpenRef.current);
if (!searchRef.current) return;
if (e.metaKey || e.ctrlKey || e.altKey) return;
const active = document.activeElement;
const tag = active && active.tagName;
const editable = active && active.isContentEditable;
const interactive = tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || tag === 'BUTTON' || tag === 'A' || editable || active && active.getAttribute && active.getAttribute('role');
if (e.key === '/' && !interactive) {
const r = rootRef.current ? rootRef.current.getBoundingClientRect() : null;
if (r && r.bottom > 0 && r.top < (window.innerHeight || 0)) {
e.preventDefault();
setMenu(null);
searchRef.current.focus();
}
}
if (e.key === 'Escape' && menuOpenRef.current === null && active === searchRef.current) {
onChange('');
searchRef.current.blur();
}
};
const onDocClick = e => {
const open = menuOpenRef.current;
if (open !== null && menuRef.current[open] && !menuRef.current[open].contains(e.target)) setMenu(null);
};
Cut at 300 lines.