Skip to main content

Settings

Struct Settings 

Source
#[non_exhaustive]
pub struct Settings {
Show 186 fields pub schema: Option<String>, pub api_key_helper: Option<String>, pub auto_memory_enabled: Option<bool>, pub auto_updates_channel: Option<UpdatesChannel>, pub aws_credential_export: Option<String>, pub aws_auth_refresh: Option<String>, pub claude_md_excludes: Option<Vec<String>>, pub cleanup_period_days: Option<u64>, pub env: Option<BTreeMap<String, String>>, pub attribution: Option<AttributionSetting>, pub include_git_instructions: Option<bool>, pub include_co_authored_by: Option<bool>, pub plans_directory: Option<String>, pub respect_gitignore: Option<bool>, pub permissions: Option<Permissions>, pub language: Option<String>, pub model: Option<String>, pub available_models: Option<Vec<String>>, pub model_overrides: Option<BTreeMap<String, String>>, pub effort_level: Option<EffortLevel>, pub fast_mode: Option<bool>, pub fast_mode_per_session_opt_in: Option<bool>, pub feedback_survey_rate: Option<f64>, pub enable_all_project_mcp_servers: Option<bool>, pub enabled_mcpjson_servers: Option<Vec<String>>, pub disabled_mcpjson_servers: Option<Vec<String>>, pub allowed_mcp_servers: Option<Vec<McpServerRule>>, pub denied_mcp_servers: Option<Vec<McpServerRule>>, pub http_hook_allowed_env_vars: Option<Vec<String>>, pub hooks: Option<Hooks>, pub disable_all_hooks: Option<bool>, pub allowed_channel_plugins: Option<Vec<ChannelPluginEntry>>, pub allowed_http_hook_urls: Option<Vec<String>>, pub allow_managed_hooks_only: Option<bool>, pub allow_managed_permission_rules_only: Option<bool>, pub status_line: Option<StatusLine>, pub file_suggestion: Option<CommandSetting>, pub enabled_plugins: Option<BTreeMap<String, PluginEnabled>>, pub extra_known_marketplaces: Option<BTreeMap<String, Marketplace>>, pub strict_known_marketplaces: Option<Vec<Source>>, pub skipped_marketplaces: Option<Vec<String>>, pub skipped_plugins: Option<Vec<String>>, pub force_login_method: Option<LoginMethod>, pub force_login_org_uuid: Option<OneOrMany>, pub otel_headers_helper: Option<String>, pub output_style: Option<String>, pub skip_web_fetch_preflight: Option<bool>, pub sandbox: Option<Sandbox>, pub spinner_verbs: Option<SpinnerVerbs>, pub spinner_tips_enabled: Option<bool>, pub spinner_tips_override: Option<SpinnerTips>, pub terminal_progress_bar_enabled: Option<bool>, pub show_turn_duration: Option<bool>, pub skill_overrides: Option<BTreeMap<String, SkillOverride>>, pub prefers_reduced_motion: Option<bool>, pub pr_url_template: Option<String>, pub always_thinking_enabled: Option<bool>, pub company_announcements: Option<Vec<String>>, pub teammate_mode: Option<TeammateMode>, pub worktree: Option<Worktree>, pub parent_settings_behavior: Option<SourcesBehavior>, pub plugin_trust_message: Option<String>, pub plugin_configs: Option<BTreeMap<String, PluginConfig>>, pub allow_managed_mcp_servers_only: Option<bool>, pub blocked_marketplaces: Option<Vec<Source>>, pub agent: Option<String>, pub auto_memory_directory: Option<String>, pub auto_mode: Option<AutoMode>, pub channels_enabled: Option<bool>, pub default_shell: Option<Shell>, pub disable_deep_link_registration: Option<DisableFlag>, pub disable_skill_shell_execution: Option<bool>, pub force_remote_settings_refresh: Option<bool>, pub minimum_version: Option<String>, pub show_clear_context_on_plan_accept: Option<bool>, pub show_thinking_summaries: Option<bool>, pub skip_dangerous_mode_permission_prompt: Option<bool>, pub strict_plugin_only_customization: Option<StrictCustomization>, pub tui: Option<Tui>, pub view_mode: Option<ViewMode>, pub use_auto_mode_during_plan: Option<bool>, pub voice_enabled: Option<bool>, pub wsl_inherits_windows_settings: Option<bool>, pub subagent_status_line: Option<CommandSetting>, pub advisor_model: Option<String>, pub auto_compact_enabled: Option<bool>, pub disable_agent_view: Option<bool>, pub editor_mode: Option<EditorMode>, pub enforce_available_models: Option<bool>, pub fallback_model: Option<Vec<String>>, pub file_checkpointing_enabled: Option<bool>, pub gcp_auth_refresh: Option<String>, pub managed_mcp_servers: Option<ManagedMcpServers>, pub skill_listing_max_desc_chars: Option<u64>, pub preferred_notif_channel: Option<NotifChannel>, pub plugin_suggestion_marketplaces: Option<Vec<String>>, pub required_maximum_version: Option<String>, pub required_minimum_version: Option<String>, pub respond_to_bash_commands: Option<bool>, pub skill_listing_budget_fraction: Option<f64>, pub ssh_configs: Option<Vec<SshConfig>>, pub ssh_host_allowlist: Option<Vec<String>>, pub theme: Option<Theme>, pub voice: Option<Voice>, pub wheel_scroll_acceleration_enabled: Option<bool>, pub disable_bundled_skills: Option<bool>, pub away_summary_enabled: Option<bool>, pub auto_scroll_enabled: Option<bool>, pub allow_all_claude_ai_mcps: Option<bool>, pub agent_push_notif_enabled: Option<bool>, pub ax_screen_reader: Option<bool>, pub claude_md: Option<String>, pub disable_artifact: Option<bool>, pub disable_auto_mode: Option<DisableFlag>, pub disable_claude_ai_connectors: Option<bool>, pub disable_remote_control: Option<bool>, pub disable_workflows: Option<bool>, pub footer_links_regexes: Option<Vec<FooterLink>>, pub input_needed_notif_enabled: Option<bool>, pub policy_helper: Option<PolicyHelper>, pub remote_control_at_startup: Option<bool>, pub syntax_highlighting_disabled: Option<bool>, pub verbose: Option<bool>, pub workflow_keyword_trigger_enabled: Option<bool>, pub ask_user_question_timeout: Option<DialogTimeout>, pub teammate_default_model: Option<Option<String>>, pub workflow_size_guideline: Option<WorkflowSize>, pub enable_artifact: Option<bool>, pub permission_explainer_enabled: Option<bool>, pub diff_tool: Option<DiffTool>, pub external_editor_context: Option<bool>, pub auto_connect_ide: Option<bool>, pub auto_install_ide_extension: Option<bool>, pub emoji_completion_enabled: Option<bool>, pub vim_insert_mode_remaps: Option<BTreeMap<String, String>>, pub process_wrapper: Option<String>, pub force_login_gateway_url: Option<String>, pub disable_sideload_flags: Option<bool>, pub browser_external_page_tools: Option<DisabledFlag>, pub disable_browser_external_navigation: Option<bool>, pub disable_mobile_simulator_tools: Option<bool>, pub require_cowork_full_vm_sandbox: Option<bool>, pub allow_claude_in_chrome_with_managed_mcp: Option<bool>, pub allowed_providers: Option<Vec<Provider>>, pub append_plugins: Option<Vec<String>>, pub auto_compact_window: Option<u64>, pub auto_continue_at_usage_limit: Option<bool>, pub available_models_match: Option<ModelMatch>, pub bash_edit_diff_enabled: Option<bool>, pub bash_output_max_chars: Option<u64>, pub cross_session_inbound: Option<InboundMode>, pub denied_models: Option<Vec<String>>, pub desktop_session_cleanup_period_days: Option<u64>, pub dialog_expiry: Option<DialogTimeout>, pub disable_command_plugin_sources: Option<bool>, pub disable_desktop_local_sessions: Option<bool>, pub disable_remote_preview_scripts: Option<bool>, pub enable_workflows: Option<bool>, pub feedback_drafts: Option<FeedbackDrafts>, pub gateway_internal_networks: Option<Vec<String>>, pub idle_compaction: Option<bool>, pub isolate_peer_machines: Option<bool>, pub keybinding_flavor: Option<KeybindingFlavor>, pub managed_sources_behavior: Option<SourcesBehavior>, pub max_effort_level: Option<EffortLevel>, pub max_prose_width: Option<u64>, pub model_picker: Option<ModelPicker>, pub model_pricing: Option<ModelPricing>, pub model_settings: Option<BTreeMap<String, ModelSettings>>, pub prepend_plugins: Option<Vec<String>>, pub prompt_cache_ttl: Option<CacheTtl>, pub prompt_suggestion_enabled: Option<bool>, pub skip_auto_permission_prompt: Option<bool>, pub spellcheck: Option<Spellcheck>, pub ssh_host_commands: Option<Vec<SshHostCommand>>, pub subagent_prompt_cache_ttl: Option<CacheTtl>, pub switch_models_on_flag: Option<bool>, pub sync_claude_ai_plugins: Option<bool>, pub sync_claude_ai_skills: Option<bool>, pub task_output_max_chars: Option<u64>, pub terminal_title_from_rename: Option<bool>, pub time_format: Option<TimeFormat>, pub time_zone: Option<String>, pub ultracode: Option<bool>, pub remote: Option<Remote>, pub extra: Extra,
}
Expand description

Claude Code’s settings.json: one settings file, a --settings document, or the merge of several.

Every key is an Option, written only when Some, so a document says only what it sets and Claude Code’s own default applies to the rest; each field’s docs give that default. Keys this crate doesn’t model (a newer Claude Code’s, or undocumented ones) are kept in extra and written back, so a document round-trips.

The struct is #[non_exhaustive], so new keys can be added without a breaking release: build one from Settings::default() and set its fields.

use claude_code_settings::{PermissionMode, Permissions, Settings};

let mut permissions = Permissions::default();
permissions.default_mode = Some(PermissionMode::AcceptEdits);

let mut settings = Settings::default();
settings.model = Some("sonnet".into());
settings.permissions = Some(permissions);
assert_eq!(
    settings.to_json_string()?,
    r#"{"permissions":{"defaultMode":"acceptEdits"},"model":"sonnet"}"#,
);

Docs: settings reference.

Fields (Non-exhaustive)§

This struct is marked as non-exhaustive
Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.
§schema: Option<String>

JSON Schema reference for Claude Code settings.

  • Values: string
  • Default: unset

Docs: not in the settings reference; listed in the JSON schema.

§api_key_helper: Option<String>

Run your own command to produce the credential Claude Code sends with model requests. Claude Code runs the command through the system shell, /bin/sh on macOS and Linux and cmd on Windows, and sends its output as both the X-Api-Key and Authorization: Bearer headers. Use it for dynamic or rotating credentials, such as short-lived tokens fetched from a vault.

  • Values: string, a shell command line
  • Default: unset, so Claude Code doesn’t run a helper
  • Scope: any settings file.

Docs: apiKeyHelper.

§auto_memory_enabled: Option<bool>

Turn auto memory on or off. When false, Claude doesn’t read from or write to the auto memory directory. You can also toggle it with /memory during a session, which writes this key to your user settings.

  • Values: Boolean
    • true: the same as unset; auto memory stays on unless something that outranks this key turns it off for the session, such as --bare, safe mode, or CLAUDE_CODE_DISABLE_AUTO_MEMORY
    • false: Claude doesn’t read from or write to the auto memory directory
  • Default: true
  • Scope: any settings file.

Docs: autoMemoryEnabled.

§auto_updates_channel: Option<UpdatesChannel>

Choose which release channel background auto-updates and claude update follow. Set "stable" for a version that is typically about one week old and skips releases with major regressions, or "latest" for the most recent release.

  • Values: string, one of:
    • "latest": updates follow the most recent release
    • "stable": updates follow a version that is typically about one week old and skips releases with major regressions
  • Default: unset, so Claude Code follows "latest"
  • Scope: any settings file. Set it in managed settings to enforce one channel across your organization.

Docs: autoUpdatesChannel.

§aws_credential_export: Option<String>

Run your own command that prints AWS credentials as JSON, so Claude Code can call Amazon Bedrock with credentials that don’t live in your .aws directory. Claude Code accepts the aws sts output shape and the flat aws configure export-credentials shape, and scopes the credentials to its own Bedrock client, so the shell commands Claude runs still see your ambient credentials.

  • Values: string, a shell command line
  • Default: unset, so Claude Code uses the ambient AWS credential chain
  • Scope: any settings file.

Docs: awsCredentialExport.

§aws_auth_refresh: Option<String>

Run your own command, such as aws sso login, to refresh the credentials in your .aws directory when the ones Claude Code has for Amazon Bedrock stop working. Claude Code checks the current credentials against STS first and runs the command only when that check fails, then reads the refreshed .aws directory. When the check fails at the same time in several Claude Code processes that use the same command and credentials, such as separate terminals or IDE windows, one process runs the command and the rest wait for that run instead of starting their own.

  • Values: string, a shell command line
  • Default: unset, so Claude Code doesn’t refresh AWS credentials for you
  • Scope: any settings file.

Docs: awsAuthRefresh.

§claude_md_excludes: Option<Vec<String>>

Skip specific CLAUDE.md files when Claude Code loads memory. In a large monorepo, use it to skip CLAUDE.md files from other teams that aren’t relevant to your work; Exclude irrelevant CLAUDE.md files in the large-codebases guide walks through that case. Patterns match against absolute file paths.

  • Values: array of strings, each a glob pattern or absolute path
  • Default: unset, so Claude Code loads every CLAUDE.md it finds
  • Scope: any settings file.

Docs: claudeMdExcludes.

§cleanup_period_days: Option<u64>

Set how many days Claude Code keeps session transcripts and other application data before deleting them. Claude Code runs the deletion as a background sweep after a session starts, as long as it can safely determine the retention period. The sweep deletes transcripts without showing a message, so a session you haven’t used for longer than the retention period no longer appears in the /resume picker.

  • Values: number of days, a whole number, minimum 1
  • Default: 30
  • Scope: any settings file.

Docs: cleanupPeriodDays.

§env: Option<BTreeMap<String, String>>

Set environment variables for every session and for the subprocesses Claude Code starts from it. Most variables in the environment variables reference can go here, which is how you apply one to every session or roll it out to your team. Project and local settings can’t set some of them.

  • Values: object mapping variable names to string values
  • Default: unset
  • Scope: any settings file.

Docs: env.

§attribution: Option<AttributionSetting>

Customize the attribution Claude Code adds to git commits and pull requests. Commits get a git trailer such as Co-Authored-By by default; pull request descriptions get plain text. Set each part separately with the sub-keys below.

  • Values: object with commit and pr strings and a sessionUrl Boolean, or false to hide all attribution. The false value requires Claude Code v2.1.281 or later; earlier versions reject it and skip the whole user, project, or local settings file that holds it
  • Default: unset, so Claude Code uses the standard attribution shown under each sub-key
  • Scope: any settings file.

Docs: attribution.

§include_git_instructions: Option<bool>

Claude Code gives Claude two git-related pieces of context: its built-in instructions for how to write commits and pull requests, in the Bash tool’s description, and a git status snapshot of your repository. The snapshot holds the current branch, the main branch, git status output, and recent commits. Claude Code reads it when a conversation starts.

  • Values: Boolean
    • true: Claude Code includes its built-in commit and pull request workflow instructions and the git status snapshot. Cloud sessions never include the snapshot
    • false: Claude Code leaves both out
  • Default: true
  • Scope: any settings file.

Docs: includeGitInstructions.

§include_co_authored_by: Option<bool>

Warning: Deprecated since v2.0.62, when attribution replaced it. Claude Code still reads it, but new configurations should set attribution. Use attribution instead, which replaces this key and lets you change or hide the commit trailer, the pull request text, and the session link separately.

  • Values: Boolean
    • true: the same as unset; Claude Code adds the commit trailer and the pull request attribution text
    • false: Claude Code omits both the commit trailer and the pull request attribution text, unless attribution sets commit or pr, in which case the attribution rules apply
  • Default: true
  • Scope: any settings file.

Docs: includeCoAuthoredBy.

§plans_directory: Option<String>

Choose where Claude Code stores the plan files it writes in plan mode. Claude Code resolves the path relative to the project root.

  • Values: string, a path relative to the project root
  • Default: unset, so Claude Code uses ~/.claude/plans
  • Scope: any settings file.

Docs: plansDirectory.

§respect_gitignore: Option<bool>

Control whether the @ file picker leaves out files that match .gitignore patterns. Appears in /config as Respect .gitignore in file picker.

  • Values: Boolean
    • true: the @ file picker leaves out files that match .gitignore patterns
    • false: the @ file picker includes files that match .gitignore patterns
  • Default: true
  • Scope: any settings file. When no settings file sets it, Claude Code falls back to respectGitignore in ~/.claude.json, which the /config toggle writes.

Docs: respectGitignore.

§permissions: Option<Permissions>

Control which tools Claude can use without asking, which ones prompt, and which ones are blocked. Also set the default permission mode for new sessions. Every permissions.* key below nests under this object.

  • Values: object with allow, ask, deny, additionalDirectories, blockReadsOutsideWorkingDirectories, blockWritesOutsideWorkingDirectories, defaultMode, denyInsteadOfPrompting, disableBypassPermissionsMode, and disableAutoMode
  • Default: unset
  • Scope: any settings file.

Docs: permissions.

§language: Option<String>

Have Claude respond in a language other than English by default. There is no fixed list for responses: Claude Code passes the value verbatim to Claude as an instruction to always respond in that language, so any language name Claude can read works. Claude Code doesn’t check the value, so a misspelled name reaches Claude as written rather than producing an error.

  • Values: string, any language name, such as "japanese", "spanish", or "french"; Claude Code doesn’t validate it
  • Default: unset; session titles then match the language of your conversation
  • Scope: any settings file.

Docs: language.

§model: Option<String>

Set the model every new session uses, so you don’t have to pick one with /model each time. Setting it here doesn’t stop you from switching mid-session. If your admin set an organization default model to override user selection, you get that model even when you set this key in user, project, or local settings.

  • Values: string, a model alias or full model ID
  • Default: unset, so Claude Code uses your account’s default model
  • Scope: any settings file.

Docs: model.

§available_models: Option<Vec<String>>

Restrict which models people can select for the main session, subagents, skills, and the advisor. A managed list constrains /model, --model, and the model key in a developer’s own files; a model outside it can’t be selected. With the default prefix matching, this doesn’t touch the Default option on its own; pair it with enforceAvailableModels for that.

  • Values: array of model aliases or IDs
  • Default: unset, so every model is available
  • Scope: any settings file. Deploy it in managed settings to enforce it for an organization.

Docs: availableModels.

§model_overrides: Option<BTreeMap<String, String>>

Map Anthropic model IDs to provider-specific model IDs, such as Amazon Bedrock inference profile ARNs. Each model picker entry then uses its mapped value when calling the provider API. Administrators use this on Amazon Bedrock, Google Cloud’s Agent Platform, and Microsoft Foundry to route each model version to a specific inference profile, version name, or deployment for governance, cost allocation, or regional routing.

  • Values: object mapping model ID to provider model ID
  • Default: unset
  • Scope: any settings file.

Docs: modelOverrides.

§effort_level: Option<EffortLevel>

Set a default effort level for models you haven’t saved a level for. Lower levels are faster and cheaper on straightforward tasks, and higher levels reason more deeply on complex problems. When you run /effort low, medium, high, or xhigh in an interactive session on your machine, Claude Code saves the level for the active model under modelSettings rather than writing this key.

  • Values: string, one of:
    • "low": the least reasoning, for short, scoped, latency-sensitive tasks that aren’t intelligence-sensitive
    • "medium": reduces token usage for cost-sensitive work that can trade off some intelligence
    • "high": balances token usage and intelligence
    • "xhigh": deeper reasoning at higher token spend
  • Default: unset
  • Scope: any settings file.

Docs: effortLevel.

§fast_mode: Option<bool>

Turn fast mode on for sessions where it’s available, for interactive work such as rapid iteration or live debugging where you want speed at a higher cost per token. You don’t usually edit this key yourself. Running /fast writes fastMode: true to ~/.claude/settings.json, and running it again to turn fast mode off removes the key.

  • Values: Boolean
    • true: Claude Code turns fast mode on for sessions where it’s available. On Fable 5.2, you must also run /fast while using Fable 5.2
    • false: fast mode stays off
  • Default: unset, so fast mode is off
  • Scope: any settings file.

Docs: fastMode.

§fast_mode_per_session_opt_in: Option<bool>

Normally, running /fast saves fastMode to a person’s user settings, so new sessions on a supported model start with fast mode on. On Fable 5.2, that happens only if they turned it on while using Fable 5.2. To make each person run /fast in each session they want it, set this key to true.

  • Values: Boolean
    • true: a saved fastMode: true no longer turns fast mode on at session start, so each person runs /fast in each session they want it; a fastMode: true passed with --settings still counts for that session unless managed settings set this key
    • false: a saved fastMode: true works as fastMode describes
  • Default: false
  • Scope: any settings file.

Docs: fastModePerSessionOptIn.

§feedback_survey_rate: Option<f64>

Set the probability that the session quality survey appears when a session is eligible for it. Set 0 to keep the survey from appearing.

  • Values: number between 0 and 1
  • Default: unset, so Claude Code uses the rate Anthropic sets remotely, or its built-in rate of 0.005 on Amazon Bedrock, Google Cloud’s Agent Platform, and Microsoft Foundry, which don’t receive remote configuration
  • Scope: any settings file.

Docs: feedbackSurveyRate.

§enable_all_project_mcp_servers: Option<bool>

Approve every MCP server defined in project .mcp.json files without a prompt. Claude Code writes this key to .claude/settings.local.json when you choose to approve all servers in the approval dialog.

  • Values: Boolean
    • true: Claude Code approves every MCP server defined in project .mcp.json files without a prompt
    • false: Claude Code asks you to approve each server. In a trusted folder, a false in a higher-precedence file overrides a true in a lower one; in a folder you haven’t trusted, a true in any honored file is enough
  • Default: unset, so Claude Code asks you to approve each server
  • Scope: any settings file. In a folder whose trust dialog you haven’t accepted, Claude Code honors it from user settings, managed settings, and --settings and ignores it in the shared project file, both in the session and for claude mcp list and claude mcp get; Project server approvals and workspace trust says when an untracked .claude/settings.local.json counts too.

Docs: enableAllProjectMcpServers.

§enabled_mcpjson_servers: Option<Vec<String>>

Approve specific servers defined in project .mcp.json files so Claude Code connects them without asking. Claude Code writes this key to .claude/settings.local.json when you approve a server in the approval dialog.

  • Values: array of strings, the server names as they appear in .mcp.json
  • Default: unset
  • Scope: any settings file. In a folder whose trust dialog you haven’t accepted, Claude Code honors it from user settings, managed settings, and --settings and ignores it in the shared project file, both in the session and for claude mcp list and claude mcp get; Project server approvals and workspace trust says when an untracked .claude/settings.local.json counts too.

Docs: enabledMcpjsonServers.

§disabled_mcpjson_servers: Option<Vec<String>>

Reject specific servers defined in a project’s .mcp.json file so Claude Code never connects them or asks you to approve them. A rejection in any settings file applies, including a project .claude/settings.json checked into the repository.

  • Values: array of strings, the server names as they appear in .mcp.json
  • Default: unset
  • Scope: any settings file.

Docs: disabledMcpjsonServers.

§allowed_mcp_servers: Option<Vec<McpServerRule>>

Allowlist the MCP servers people can add. Claude Code blocks any server that doesn’t match an entry wherever it’s defined, including plugin servers, servers a user passes with --mcp-config, and servers from claude.ai. Built-in servers such as Claude in Chrome, the ide server Claude Code connects to in a running VS Code or JetBrains IDE, and servers the CLI itself configures are exempt from the allowlist, and the denylist still applies to them.

  • Values: array of objects, each with exactly one key. Use serverName, a string limited to letters, numbers, hyphens, and underscores; serverCommand, an array of the command and its arguments matched exactly; or serverUrl, a URL pattern with * wildcards
  • Default: unset, so every server is allowed; an empty array blocks every server users add
  • Scope: any settings file. Entries from every file merge into one allowlist unless allowmanagedmcpserversonly is set.

Docs: allowedMcpServers.

§denied_mcp_servers: Option<Vec<McpServerRule>>

Block specific MCP servers. Claude Code refuses to load a matching server wherever it’s defined, including plugin servers, servers passed with --mcp-config, servers from managed-mcp.json, servers from managedMcpServers, and the claude.ai connectors it fetches itself. In-process type: "sdk" servers are exempt; the app that started the session registers them.

  • Values: array of objects, each with exactly one key: serverName, a string, so a claude.ai connector’s display name such as "claude.ai Slack" works; serverCommand, an array of the command and its arguments matched exactly; or serverUrl, a URL pattern with * wildcards
  • Default: unset, so no server is blocked; an empty array also blocks nothing
  • Scope: any settings file. Entries from every file merge into one denylist, and allowmanagedmcpserversonly doesn’t change that.

Docs: deniedMcpServers.

§http_hook_allowed_env_vars: Option<Vec<String>>

An HTTP hook 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.

  • Values: array of environment variable names
  • Default: unset, so each hook’s own allowedEnvVars list applies
  • Scope: any settings file. Arrays merge across settings files.

Docs: httpHookAllowedEnvVars.

§hooks: Option<Hooks>

Run your own commands, prompts, agents, HTTP requests, or MCP tools as hooks at points in Claude Code’s lifecycle, such as before a tool call or when a session starts; the hooks reference 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.

  • Values: object keyed by hook event; 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
  • Scope: any settings file. Hooks merge across files rather than replacing each other, and hooks from managed settings can’t be removed from other files.

Docs: hooks.

§disable_all_hooks: Option<bool>

Turn off hooks, any custom status line, and any custom file suggestion command. Use it to turn all of these off temporarily without deleting them from your settings.

  • Values: 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
  • Scope: any settings file. Only managed settings can disable managed hooks.

Docs: disableAllHooks.

§allowed_channel_plugins: Option<Vec<ChannelPluginEntry>>

Choose which channel 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.

  • Values: array of objects, each with marketplace and plugin strings. An entry can instead be a "plugin@marketplace" string such as "telegram@claude-plugins-official", which Claude Code treats as the equivalent object. The string form requires Claude Code v2.1.267 or later; earlier versions reject the whole allowedChannelPlugins value when it contains one
  • Default: unset, so Claude Code uses the default Anthropic allowlist
  • Scope: managed.

Docs: allowedChannelPlugins.

§allowed_http_hook_urls: Option<Vec<String>>

Limit which URLs HTTP hooks can target. When you define this key, Claude Code runs an HTTP hook only if its URL matches one of the patterns and blocks the rest without running them; an empty array blocks every HTTP hook.

  • Values: array of URL patterns, with * as a wildcard
  • Default: unset, so any URL is allowed
  • Scope: any settings file. Arrays merge across settings files.

Docs: allowedHttpHookUrls.

§allow_managed_hooks_only: Option<bool>

Restrict hook execution to hooks your organization deploys.

  • Values: Boolean
    • true: only managed hooks run, plus Agent SDK hooks and hooks from plugins your managed settings force-enable. See What runs under allowManagedHooksOnly
    • false: hooks from every settings scope and plugin run
  • Default: unset, so hooks from every settings scope and plugin run
  • Scope: managed.

Docs: allowManagedHooksOnly.

§allow_managed_permission_rules_only: Option<bool>

Make managed settings the only settings source of permission rules. Claude Code then ignores allow, ask, and deny rules in user, project, local, and --settings files, ignores --allowedTools, hides the always-allow choices in permission prompts, and stops saving new rules. When parent settings from an embedding host apply, Claude Code treats them as part of the managed tier.

  • Values: Boolean
    • true: managed settings become the only settings source of permission rules
    • false: Claude Code applies permission rules from user, project, local, and --settings files in addition to the managed ones
  • Default: unset, so Claude Code applies permission rules from user, project, and local settings and from --settings, in addition to the managed ones
  • Scope: managed.

Docs: allowManagedPermissionRulesOnly.

§status_line: Option<StatusLine>

Run your own command to render a status line below the prompt with context such as the model, cost, or git branch. Optional fields adjust spacing, add periodic re-runs, and hide the built-in vim mode indicator when your script renders vim.mode itself.

  • Values: object with type set to "command" and a command string, plus optional padding as a number of characters, refreshInterval as a number of seconds, minimum 1, and hideVimModeIndicator as a Boolean
  • Default: unset, so no status line
  • Scope: any settings file. When allowmanagedhooksonly is on, or disableallhooks is set outside managed settings, only the managed settings value runs.

Docs: statusLine.

§file_suggestion: Option<CommandSetting>

Run your own command to supply @ file path autocomplete instead of the built-in file suggestion. The built-in suggestion uses fast filesystem traversal; a large monorepo may do better with project-specific indexing such as a pre-built file index.

  • Values: object with type, always "command", and command, the shell command to run
  • Default: unset, so Claude Code uses the built-in file suggestion
  • Scope: any settings file. Under the status line and file suggestion gates, Claude Code turns the command off or runs only a managed value, and skips yours without warning.

Docs: fileSuggestion.

§enabled_plugins: Option<BTreeMap<String, PluginEnabled>>

Turn individual plugins on or off, keyed by plugin-name@marketplace-name. A plugin with no entry at any scope falls back to its defaultEnabled value. When you enable or disable a plugin with /plugin or claude plugin enable, Claude Code writes this key for you.

  • Values: object mapping plugin-name@marketplace-name to a Boolean
  • Default: unset, so each plugin follows its defaultEnabled value
  • Scope: any settings file.

Docs: enabledPlugins.

§extra_known_marketplaces: Option<BTreeMap<String, Marketplace>>

Register additional plugin marketplaces by name, so that people who open the repository, or everyone your managed settings reach, get the marketplace without adding it themselves. Claude Code registers each marketplace it doesn’t already know. Whether a plugin that enabledPlugins names from it installs depends on the plugin’s source and which file enables it; Enabled in project settings but not installed has the rules.

  • Values: object mapping a marketplace name to an object with a source object and an optional autoUpdate Boolean
  • Default: unset
  • Scope: any settings file. Claude Code honors entries in a repository’s .claude/settings.json or .claude/settings.local.json only after you accept the workspace trust dialog for that folder; in a folder you haven’t trusted, including a -p run there, it ignores them without a message.

Docs: extraKnownMarketplaces.

§strict_known_marketplaces: Option<Vec<Source>>

Restrict which plugin marketplace sources people in your organization can add and install plugins from. Claude Code enforces the allowlist on marketplace add and on plugin install, update, refresh, and auto-update, before any network or filesystem operation, so a marketplace someone added before you set the policy can’t be used to fetch plugins once its source no longer matches. Blocked users see an error naming the managed policy.

  • Values: array of marketplace source objects; see Allowed source types
  • Default: unset, so users can add any marketplace. An empty array is a complete lockdown that blocks every marketplace source, including the official Anthropic marketplace
  • Scope: managed.

Docs: strictKnownMarketplaces.

§skipped_marketplaces: Option<Vec<String>>

List of marketplace names the user has chosen not to install when prompted.

  • Values: array of strings
  • Default: unset

Docs: not in the settings reference; listed in the JSON schema.

§skipped_plugins: Option<Vec<String>>

List of plugin IDs (plugin@marketplace format) the user has chosen not to install when prompted.

  • Values: array of strings
  • Default: unset

Docs: not in the settings reference; listed in the JSON schema.

§force_login_method: Option<LoginMethod>

Restrict which kind of account people can log in with: "claudeai" for claude.ai sign-in or "console" for Claude Console sign-in. Set "gateway" to send people to a cloud gateway instead of a first-party login. Administrators set it in managed settings and pair it with forceLoginOrgUUID to keep developers’ claude.ai logins inside one organization.

  • Values: string, one of:
    • "claudeai": claude.ai sign-in
    • "console": Claude Console sign-in
    • "gateway": Claude Code sends people to a cloud gateway instead of a first-party login
  • Default: unset, so people pick a login method
  • Scope: any settings file. Claude Code honors "gateway" from the same sources as forcelogingatewayurl and treats it as unset everywhere else.

Docs: forceLoginMethod.

§force_login_org_uuid: Option<OneOrMany>

From a managed source, require claude.ai account logins to belong to one Anthropic organization, given as a single UUID, or to any of several organizations, given as an array. From any settings file, Claude Code also uses a single UUID to pre-select that organization during a claude.ai or Claude Console login, and pre-selects nothing for an array. If you set the key in any settings file, Claude Code also stops offering the keyless Console sign-in in the sessions that file applies to and creates an API key instead.

  • Values: string, one UUID, or array of strings, several UUIDs
  • Default: unset, so any organization can log in
  • Scope: any settings file. In a settings file that isn’t a managed source, Claude Code doesn’t check which organization a login belongs to, and a single UUID pre-selects the organization during login.

Docs: forceLoginOrgUUID.

§otel_headers_helper: Option<String>

Run your own command to generate the headers Claude Code sends with OpenTelemetry exports, for backends whose tokens rotate. Claude Code runs it at startup and periodically after that, and expects a JSON object of string header values on stdout.

  • Values: string, an executable path or a shell command line
  • Default: unset, so Claude Code adds no helper-generated headers
  • Scope: any settings file.

Docs: otelHeadersHelper.

§output_style: Option<String>

Select an output style by name. An output style is a saved set of instructions that changes Claude’s role, tone, and output format, such as the built-in Explanatory and Learning styles or one you wrote yourself. If you change this key during a session, Claude uses the new style starting with your next message.

  • Values: string, the name of a built-in or custom output style
  • Default: unset, so Claude Code uses the default style
  • Scope: any settings file.

Docs: outputStyle.

§skip_web_fetch_preflight: Option<bool>

Skip the WebFetch domain safety check, which sends each requested hostname to api.anthropic.com before fetching. Set true in environments that block traffic to Anthropic, such as Amazon Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry deployments with restrictive egress.

  • Values: Boolean
    • true: Claude Code skips the WebFetch domain safety check
    • false: the check runs before the first fetch to each hostname in a session, and again for a hostname whose earlier check was blocked or failed
  • Default: unset, so the check runs before the first fetch to each hostname in a session
  • Scope: any settings file.

Docs: skipWebFetchPreflight.

§sandbox: Option<Sandbox>

Isolate the Bash commands Claude runs from your filesystem and network with sandboxing. Turn the sandbox on with enabled, then narrow or widen what sandboxed commands can touch with the filesystem, network, and credentials sub-objects. The sandbox runs on macOS, Linux, and WSL2.

  • Values: object with enabled, failIfUnavailable, autoAllowBashIfSandboxed, excludedCommands, allowUnsandboxedCommands, enableWeakerNestedSandbox, enableWeakerNetworkIsolation, allowAppleEvents, allowNestedUserNamespaces, bwrapPath, socatPath, ignoreViolations, and ripgrep, plus the filesystem, network, and credentials objects
  • Default: unset, so Claude Code runs commands without a sandbox
  • Scope: any settings file.

Docs: sandbox.

§spinner_verbs: Option<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.

  • Values: object with a verbs array of strings and mode, one of:
    • "append": Claude Code adds your verbs to the built-in set
    • "replace": Claude Code shows only your verbs
  • Default: unset, so Claude Code uses the built-in verbs
  • Scope: any settings file.

Docs: spinnerVerbs.

§spinner_tips_enabled: Option<bool>

While Claude works, the spinner line rotates through short tips about Claude Code features, such as “Use Plan Mode to prepare for a complex request before making changes. Press Shift+Tab twice to enable.” Set this key to false to hide them. Appears in /config as Show tips.

  • Values: Boolean
    • true: you see tips in the spinner while Claude is working
    • false: Claude Code hides spinner tips
  • Default: true
  • Scope: any settings file.

Docs: spinnerTipsEnabled.

§spinner_tips_override: Option<SpinnerTips>

Add your own tips to the spinner tips 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. If you set spinnerTipsEnabled to false, Claude Code hides all tips, yours included.

  • Values: object with tips, tipsFile, label, and excludeDefault fields, each optional
  • Default: unset, so Claude Code shows only the built-in tips
  • Scope: any settings file. 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.

Docs: spinnerTipsOverride.

§terminal_progress_bar_enabled: Option<bool>

Some terminals can show a progress indicator on the tab or in the taskbar for the program running in them. While Claude is working, Claude Code reports an in-progress state to the terminal, so you can see from another tab or window whether the session is still busy. The indicator stays visible after the turn ends while background subagents or dynamic workflows are still running, and clears once the session is idle.

  • Values: Boolean
    • true: you see the terminal progress bar in terminals that support it
    • false: Claude Code hides the terminal progress bar
  • Default: true
  • Scope: any settings file. A value in ~/.claude.json from an older version applies when no settings file sets it.

Docs: terminalProgressBarEnabled.

§show_turn_duration: Option<bool>

Show or hide the turn duration message after each response, such as “Cooked for 1m 6s · done 6:05 PM”. The clock after “done” shows when the turn finished; timeFormat and timeZone control its format and zone. Appears in /config as Show turn duration.

  • Values: Boolean
    • true: you see the turn duration message after each response
    • false: Claude Code hides the turn duration message
  • Default: true
  • Scope: any settings file. A value in ~/.claude.json from an older version applies when no settings file sets it.

Docs: showTurnDuration.

§skill_overrides: Option<BTreeMap<String, SkillOverride>>

Hide or collapse a skill 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.

  • Values: 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"
  • Scope: any settings file. The /skills menu writes to .claude/settings.local.json.

Docs: skillOverrides.

§prefers_reduced_motion: Option<bool>

Reduce or turn off interface animations such as the spinner, shimmer, and flash effects. Appears in /config as Reduce motion.

  • Values: Boolean
    • true: Claude Code reduces or turns off interface animations such as the spinner, shimmer, and flash effects
    • false: the same as unset; Claude Code shows its animations
  • Default: false
  • Scope: any settings file.

Docs: prefersReducedMotion.

§pr_url_template: Option<String>

Point the PR links Claude Code renders, in the footer badge and in tool-result summaries, at an internal code-review tool instead of github.com. Claude Code substitutes {host}, {owner}, {repo}, {number}, and {url} from the PR URL. GitLab merge request links on both surfaces keep their GitLab URL.

  • Values: string, a URL template using any of the five placeholders
  • Default: unset
  • Scope: any settings file.

Docs: prUrlTemplate.

§always_thinking_enabled: Option<bool>

Turn extended thinking off for every session by setting this to false. Thinking is on by default, so true changes nothing. Most people set this through /config rather than by editing the file.

  • Values: Boolean
    • true: no effect; thinking is already on
    • false: Claude Code turns extended thinking off for every session
  • Default: unset, so thinking is on for models that support it
  • Scope: any settings file.

Docs: alwaysThinkingEnabled.

§company_announcements: Option<Vec<String>>

Show your organization’s announcements to users at startup. When you list more than one, Claude Code picks one at random for each session; on a person’s very first launch it shows the first entry.

  • Values: array of strings
  • Default: unset, so no announcement shows
  • Scope: any settings file.

Docs: companyAnnouncements.

§teammate_mode: Option<TeammateMode>

Choose where Claude Code shows agent team teammates: inside your main terminal pane, or in split panes when your terminal supports them. See Choose a display mode.

  • Values: string, one of:
    • "in-process": teammates run inside your main terminal pane
    • "auto": split panes when you’re running inside tmux, or inside iTerm2 with it2 on your PATH or tmux installed; in-process otherwise
    • "tmux": split panes using tmux or iTerm2, detected from your terminal
    • "iterm2": iTerm2 native split panes through the it2 CLI
  • Default: "in-process"
  • Scope: any settings file. Claude Code also reads a value left in ~/.claude.json by older versions.

Docs: teammateMode.

§worktree: Option<Worktree>

Configure how Claude Code creates and manages git worktrees for --worktree, the EnterWorktree tool, and isolated subagents and background sessions.

  • Values: object with baseRef, symlinkDirectories, sparsePaths, and bgIsolation
  • Default: unset
  • Scope: any settings file.

Docs: worktree.

§parent_settings_behavior: Option<SourcesBehavior>

Choose whether Claude Code applies managed settings supplied by an embedding host process, such as the Agent SDK or an IDE extension, when an admin-deployed managed tier is also present. With "first-wins", Claude Code drops the host-supplied settings; with "merge", it applies them under the admin tier through a restrictive-only filter. Set "merge" when a host needs to pass its own restrictions to the sessions it launches, for example Claude Desktop delivering a gateway’s egress allowlist.

  • Values: string, one of:
    • "first-wins": Claude Code drops the host-supplied settings when an admin-deployed managed tier is present
    • "merge": Claude Code applies the host-supplied settings under the admin tier through a restrictive-only filter
  • Default: "first-wins"
  • Scope: managed. Claude Code reads it from the highest-priority admin-controlled managed source.

Docs: parentSettingsBehavior.

§plugin_trust_message: Option<String>

Add your organization’s own text to the plugin trust warning Claude Code shows before installation, for example to confirm that plugins from your internal marketplace are vetted.

  • Values: string
  • Default: unset, so Claude Code shows the standard warning alone
  • Scope: managed.

Docs: pluginTrustMessage.

§plugin_configs: Option<BTreeMap<String, PluginConfig>>

Store the non-sensitive answers you give a plugin’s userConfig configuration dialog, keyed by plugin ID. Claude Code writes this key to your user settings when you fill in the dialog, so you don’t need to edit it by hand. Claude Code stores sensitive options in the macOS Keychain instead, falling back to ~/.claude/.credentials.json when the Keychain rejects the write; on platforms without a supported keychain, it stores them in ~/.claude/.credentials.json.

  • Values: object mapping a plugin ID to an object with an options field, mapping each option name to a string, number, Boolean, or array of strings, and an optional mcpServers field holding per-server user configuration values in the same shape
  • Default: unset
  • Scope: user or managed.

Docs: pluginConfigs.

§allow_managed_mcp_servers_only: Option<bool>

Make the managed allowlist the only one that applies. Claude Code then reads allowedMcpServers from managed settings alone and ignores allowlists in user, project, and local settings; deniedMcpServers still merges from every settings scope, so users can still block servers for themselves. Administrators set it so a user’s own settings can’t broaden what the managed allowlist permits.

  • Values: Boolean
    • true: Claude Code reads allowedMcpServers from managed settings alone and ignores allowlists in user, project, and local settings
    • false: allowlists from every settings scope merge
  • Default: false, so allowlists from every settings scope merge
  • Scope: managed.

Docs: allowManagedMcpServersOnly.

§blocked_marketplaces: Option<Vec<Source>>

Block plugin marketplace sources for your organization. Claude Code checks the blocklist on marketplace add and on plugin install, update, refresh, and auto-update, so a marketplace someone added before you set the policy can’t be used to fetch plugins either. Blocked sources are checked before download, so they never touch the filesystem.

  • Values: array of marketplace source objects, in the same forms as strictKnownMarketplaces
  • Default: unset, so no marketplace is blocked
  • Scope: managed.

Docs: blockedMarketplaces.

§agent: Option<String>

Run the main thread as a named subagent, so Claude Code applies that subagent’s system prompt, tool restrictions, and model to your session. The same key sets the default agent for sessions you dispatch from claude agents.

  • Values: string, the name of a built-in or custom agent
  • Default: unset
  • Scope: any settings file.

Docs: agent.

§auto_memory_directory: Option<String>

Store auto memory in a directory of your choice instead of the per-project default.

  • Values: string, an absolute or ~/-prefixed directory path
  • Default: unset, so Claude Code uses ~/.claude/projects/<project>/memory/
  • Scope: any settings file.

Docs: autoMemoryDirectory.

§auto_mode: Option<AutoMode>

Add your own rules to what the auto mode classifier blocks and allows. Use it to tell the classifier which repos, buckets, and domains your organization trusts, so it stops blocking routine internal operations. The classifier ships with built-in allow and deny rules.

  • Values: object with environment, allow, soft_deny, and hard_deny arrays of prose rules, plus the classifyAllShell Boolean
  • Default: unset, so the classifier uses only its built-in rules
  • Scope: user or managed.

Docs: autoMode.

§channels_enabled: Option<bool>

Allow channels for your organization. On claude.ai Team and Enterprise plans, Claude Code blocks channels until you set this to true. For Anthropic Console accounts that authenticate with an API key, channels are allowed by default.

  • Values: Boolean
    • true: Claude Code allows channels for your organization
    • false: the same as unset; whether channels are blocked depends on your plan, as the Default says
  • Default: unset; channels are blocked on Team and Enterprise plans and on Console accounts with managed settings, and allowed on Pro, Max, and Ultra plans and on Console accounts without managed settings
  • Scope: managed.

Docs: channelsEnabled.

§default_shell: Option<Shell>

Choose whether Bash or PowerShell runs the shell commands you type with the ! prefix in the input box, the ones Claude Code runs directly and adds to the session. "powershell" works only while the PowerShell tool is on. The tool is on by default on Windows without Git Bash, and on Windows with Git Bash for claude.ai and Console accounts.

  • Values: string, one of:
    • "bash": Claude Code runs your ! commands in Bash
    • "powershell": Claude Code runs your ! commands in PowerShell
  • Default: "bash", or "powershell" on Windows when Bash isn’t available
  • Scope: any settings file.

Docs: defaultShell.

§disable_deep_link_registration: Option<DisableFlag>

Stop Claude Code from registering the claude-cli:// protocol handler with the operating system. Deep links let external tools open a Claude Code session with a pre-filled prompt. Set this in environments where protocol handler registration is restricted or managed separately.

  • Values: the string "disable"
  • Default: unset, so Claude Code registers the handler
  • Scope: any settings file.

Docs: disableDeepLinkRegistration.

§disable_skill_shell_execution: Option<bool>

Turn off inline shell execution for !`...` and ```! blocks in 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.

  • Values: 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
  • Scope: any settings file. A true in managed settings can’t be overridden by false elsewhere.

Docs: disableSkillShellExecution.

§force_remote_settings_refresh: Option<bool>

Block CLI startup until Claude Code has freshly fetched server-managed settings. If the fetch fails, Claude Code exits instead of continuing with cached or no settings. Set it when your environment can’t accept even a brief window in which a session runs without its managed policy.

  • Values: Boolean
    • true: Claude Code blocks startup until it has freshly fetched server-managed settings, and exits if the fetch fails
    • false: unless Anthropic requires the settings, Claude Code doesn’t block startup on the fetch, though at a sign-in startup it waits up to five seconds for the fetch
  • Default: false
  • Scope: managed. Claude Code honors a true from any admin-controlled managed source, even one that isn’t the highest-priority source.

Docs: forceRemoteSettingsRefresh.

§minimum_version: Option<String>

Keep background auto-updates and claude update from installing any version below this one, so moving to the "stable" channel doesn’t downgrade you from a newer "latest" build. Claude Code writes this key for you when you choose to stay on your current version while switching channels in /config, and clears it when you switch back to "latest".

  • Values: string, a version number such as "2.1.100"; a value that isn’t a valid version is ignored
  • Default: unset, so updates can install any version the channel offers
  • Scope: any settings file. Set it in managed settings to pin an organization-wide minimum that user and project settings can’t lower.

Docs: minimumVersion.

§show_clear_context_on_plan_accept: Option<bool>

When Claude finishes a plan in plan mode, it shows an approval menu. Planning can use a lot of context, so this key adds a first option to that menu, Yes, clear context and …, that approves the plan, clears the conversation context, and starts implementing from the plan alone. The rest of the label names the permission mode the session continues in, and shows how much of your context the planning used.

  • Values: Boolean
    • true: the plan approval menu gets a first option, Yes, clear context and …, that approves the plan and clears the conversation context
    • false: the plan approval menu shows no clear-context option
  • Default: false
  • Scope: any settings file.

Docs: showClearContextOnPlanAccept.

§show_thinking_summaries: Option<bool>

See summaries of Claude’s 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.

  • Values: Boolean
    • true: you see full thinking summaries when you expand thinking with Ctrl+O
    • false: the Anthropic API redacts thinking blocks and Claude Code shows a collapsed stub
  • Default: false
  • Scope: any settings file.

Docs: showThinkingSummaries.

§skip_dangerous_mode_permission_prompt: Option<bool>

Skip the confirmation dialog Claude Code shows before a session enters bypassPermissions mode, whether from --dangerously-skip-permissions or from defaultMode: "bypassPermissions". Claude Code writes true here in your user settings when you accept that dialog once.

  • Values: Boolean
    • true: Claude Code skips the confirmation dialog before a session enters bypassPermissions mode
    • false: the same as unset; the dialog appears unless another of these files sets true
  • Default: unset, so the dialog appears
  • Scope: user, local, or managed, and files passed with --settings. Background sessions count only user and managed settings.

Docs: skipDangerousModePermissionPrompt.

§strict_plugin_only_customization: Option<StrictCustomization>

Block skills, agents, hooks, and MCP servers from user and project sources. Combine it with strictKnownMarketplaces to choose which marketplaces users can install plugins from. Add disableSideloadFlags to reject the CLI flags that sideload plugins, agents, and MCP servers for a single run.

  • Values: true to lock all of them, or an array naming the ones to lock, from "skills", "agents", "hooks", and "mcp"
  • Default: unset, so nothing is locked
  • Scope: managed.

Docs: strictPluginOnlyCustomization.

§tui: Option<Tui>

Choose the terminal UI renderer. Use "fullscreen" for the flicker-free alt-screen renderer with virtualized scrollback, or "default" for the classic main-screen renderer. Running /tui fullscreen or /tui default writes this key for you.

  • Values: 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 for you
  • Scope: any settings file.

Docs: tui.

§view_mode: Option<ViewMode>

Set the transcript view Claude Code starts in: "default", "verbose", or "focus". When set, it overrides both the sticky /focus selection and the verbose setting.

  • Values: string, one of:
    • "default": the normal transcript with truncated tool output
    • "verbose": the transcript with full tool output
    • "focus": only your last prompt, a one-line summary of tool calls with edit diffstats, and the final response. Focus view needs the fullscreen renderer
  • Default: unset, so the verbose setting and your last /focus choice apply
  • Scope: any settings file.

Docs: viewMode.

§use_auto_mode_during_plan: Option<bool>

Choose whether Claude Code uses the auto mode classifier to review shell commands in plan mode. With the default true, the classifier reviews each command during planning when auto mode is available and you see no prompt, except for critical-path removals. Set false to get a permission prompt for every command outside the built-in read-only set.

  • Values: Boolean
    • true: the same as unset; when auto mode is available, the classifier reviews shell commands during planning
    • false: you get a permission prompt for every command outside the built-in read-only set
  • Default: true
  • Scope: user, local, or managed. A repository can’t turn it off for you. * A false in any of these files or in --settings turns it off, unless you leave that user or local file out with an option such as –setting-sources.

Docs: useAutoModeDuringPlan.

§voice_enabled: Option<bool>

Warning: Deprecated since v2.1.92, when the voice object replaced it. Claude Code still reads it so older settings files keep working, but new configurations should set voice.enabled. Turn voice dictation on with the single Boolean form that predates the voice object.

  • Values: Boolean
    • true: voice dictation is on when you’re logged in with a claude.ai account and your organization’s policy allows voice, unless voice.enabled is set
    • false: voice dictation is off, unless voice.enabled is set
  • Default: unset
  • Scope: any settings file.

Docs: voiceEnabled.

§wsl_inherits_windows_settings: Option<bool>

Have Claude Code on WSL read managed settings from the Windows policy chain, with HKLM and the Windows managed settings file taking priority over /etc/claude-code and HKCU below it. While the chain is on, Claude Code reads /etc/claude-code only when no Windows admin document is present in the HKLM registry value or the C:\Program Files\ClaudeCode\ folder. Set it to extend the policy you already deploy on Windows to WSL sessions on the same machine, so they follow the same rules as host sessions.

  • Values: Boolean
    • true: Claude Code on WSL reads managed settings from the Windows policy chain, and reads /etc/claude-code only when no Windows admin document is present
    • false: WSL reads only /etc/claude-code
  • Default: false, so WSL reads only /etc/claude-code
  • Scope: managed. In an admin-controlled Windows source.

Docs: wslInheritsWindowsSettings.

§subagent_status_line: Option<CommandSetting>

Status line configuration for subagent sessions.

  • Values: object
  • Default: unset

Docs: not in the settings reference; listed in the JSON schema.

§advisor_model: Option<String>

Pick which model answers when Claude calls the server-side advisor tool. Unset it to turn the advisor off. The advisor must be at least as capable as your main model.

  • Values: string, one of the aliases "fable", "opus", or "sonnet", which resolve to Claude Code’s current default version of that model family, or a full model ID such as "claude-opus-5-5"
  • Default: unset, so the advisor is off
  • Scope: any settings file.

Docs: advisorModel.

§auto_compact_enabled: Option<bool>

Have Claude Code compact the conversation automatically when context approaches the limit. Appears in /config as Auto-compact, and toggling it there writes this key to your user settings.

  • Values: Boolean
    • true: Claude Code compacts the conversation automatically when context approaches the limit
    • false: Claude Code doesn’t compact automatically
  • Default: true
  • Scope: any settings file.

Docs: autoCompactEnabled.

§disable_agent_view: Option<bool>

Turn off background agents and agent view: claude agents, --bg, /background, and the on-demand supervisor. Set it in managed settings to enforce it for an organization.

  • Values: Boolean
    • true: Claude Code turns off claude agents, --bg, /background, and the on-demand supervisor
    • false: agent view is available
  • Default: unset, so agent view is available
  • Scope: any settings file.

Docs: disableAgentView.

§editor_mode: Option<EditorMode>

Choose the key binding mode for the input prompt.

  • Values: string, one of:
    • "normal": standard key bindings in the prompt input
    • "vim": vim-style editing with NORMAL, INSERT, and VISUAL modes
  • Default: "normal"
  • Scope: any settings file.

Docs: editorMode.

§enforce_available_models: Option<bool>

The /model picker has a Default option, and default model setting describes the model it resolves to. An availableModels allowlist limits the models you can name, but with the default prefix matching it doesn’t remap your account type’s default, so Default can still resolve to a model outside the list. This key closes that gap.

  • Values: Boolean
    • true: when Default would resolve to a model outside availableModels, Claude Code resolves it to the first available model in the list
    • false: this key doesn’t change how Default resolves
  • Default: false
  • Scope: any settings file.

Docs: enforceAvailableModels.

§fallback_model: Option<Vec<String>>

Name backup models for Claude Code to try, in order, when your primary model is overloaded or unavailable. Claude Code switches to the next available model in the chain for the rest of the turn and shows a notice. Without a chain, Claude Code retries the same model and then surfaces the server’s error, and you retry or switch models yourself.

  • Values: array of model aliases or IDs; "default" expands to the default model
  • Default: unset, so a failed request isn’t retried on another model
  • Scope: any settings file.

Docs: fallbackModel.

§file_checkpointing_enabled: Option<bool>

Have Claude Code snapshot files before each edit so /rewind can restore them. Appears in /config as Rewind code (checkpoints), and toggling it there writes this key to your user settings.

  • Values: Boolean
    • true: Claude Code snapshots files before each edit so /rewind can restore them
    • false: Claude Code doesn’t snapshot files, so /rewind can’t restore them
  • Default: true
  • Scope: any settings file.

Docs: fileCheckpointingEnabled.

§gcp_auth_refresh: Option<String>

Run your own command to refresh Google Cloud Application Default Credentials when Claude Code finds they’ve expired or can’t be loaded, so Google Cloud’s Agent Platform requests keep working without you re-authenticating by hand. When several Claude Code processes that use the same command and credentials, such as separate terminals or IDE windows, find them expired at the same time, one process runs the command and the rest wait for that run instead of starting their own. A process that has waited 60 seconds with a request pending runs the command itself.

  • Values: string, a shell command line
  • Default: unset, so Claude Code’s credential error tells you to run gcloud auth application-default login yourself
  • Scope: any settings file.

Docs: gcpAuthRefresh.

§managed_mcp_servers: Option<ManagedMcpServers>

Provide remote MCP servers to every user from managed settings. Users keep the servers they add themselves and can’t edit or remove the ones you provide. Requires Claude Code v2.1.259 or later.

  • Values: object keyed by server name. Each entry has the .mcp.json shape for an http or sse server: a required https:// url, and optionally headers, oauth, and the other HTTP and SSE options. Claude Code drops entries that fail validation, and What an entry can contain lists the conditions
  • Default: unset, so managed settings provide no servers
  • Scope: managed. Claude Code drops the key with a warning in user, project, and local settings, and doesn’t read it in the Claude Desktop app’s Code tab on a third-party deployment or in the app’s Cowork sessions, where Claude Desktop supplies and locks those sessions’ MCP servers itself.

Docs: managedMcpServers.

§skill_listing_max_desc_chars: Option<u64>

Each turn, Claude sees a listing of your skills that shows each skill’s description and when_to_use text. This key caps how many characters of that text Claude Code shows per skill; longer text is cut at the cap.

  • Values: number of characters, a positive integer
  • Default: 1536
  • Scope: any settings file.

Docs: skillListingMaxDescChars.

§preferred_notif_channel: Option<NotifChannel>

Choose how Claude Code notifies you when a task completes or a permission prompt is waiting. A mod’s notifications use the same setting. Appears in /config as Local notifications.

  • Values: string, one of:
    • "auto": Claude Code sends a desktop notification when it detects iTerm2, Ghostty, or Kitty, rings the bell in Terminal.app only when its audible bell is off, and does nothing elsewhere
    • "terminal_bell": Claude Code rings the bell character in any terminal
    • "iterm2": Claude Code sends an iTerm2 desktop notification
    • "iterm2_with_bell": Claude Code sends an iTerm2 desktop notification and rings the bell
    • "kitty": Claude Code sends a Kitty desktop notification
    • "ghostty": Claude Code sends a Ghostty desktop notification
    • "notifications_disabled": Claude Code sends no notification
  • Default: "auto"
  • Scope: any settings file. Claude Code also reads a value left in ~/.claude.json by older versions.

Docs: preferredNotifChannel.

§plugin_suggestion_marketplaces: Option<Vec<String>>

Name the marketplaces whose plugins can appear as contextual install suggestions, in spinner tips and pinned at the top of the /plugin Discover tab. The built-in first-party frontend-design tip is unaffected. Suggestions come from each plugin’s relevance declaration in its marketplace entry.

  • Values: array of marketplace names
  • Default: unset, so no marketplace-declared suggestions surface
  • Scope: managed.

Docs: pluginSuggestionMarketplaces.

§required_maximum_version: Option<String>

Set the newest Claude Code version your organization allows to start. When the running version is newer, Claude Code exits at startup and tells the user to install an approved version through your organization’s approved method; claude install <version> may also work. Requires Claude Code v2.1.163 or later.

  • Values: string, a version number such as "2.1.150"; a value that isn’t a valid version is ignored
  • Default: unset, so no ceiling applies
  • Scope: managed. Claude Code gives no warning when it ignores the key elsewhere.

Docs: requiredMaximumVersion.

§required_minimum_version: Option<String>

Set the oldest Claude Code version your organization allows to start. When the running version is older, Claude Code exits at startup and tells the user to update through your organization’s approved method. The check runs at startup only, so a session that’s already running continues.

  • Values: string, a version number such as "2.1.150"; a value that isn’t a valid version is ignored
  • Default: unset, so no floor applies
  • Scope: managed. Claude Code gives no warning when it ignores the key elsewhere.

Docs: requiredMinimumVersion.

§respond_to_bash_commands: Option<bool>

Choose whether Claude responds after you run a shell command with the ! prefix in the input box. By default, Claude Code adds the command’s output to the conversation and Claude replies to it. Set this key to false to add the output to context without a reply, so you can run several commands and ask about them together.

  • Values: Boolean
    • true: Claude Code adds the command’s output to the conversation and Claude replies to it
    • false: Claude Code adds the output to context without a reply
  • Default: true
  • Scope: any settings file.

Docs: respondToBashCommands.

§skill_listing_budget_fraction: Option<f64>

Each turn, Claude sees a listing of your skills with their descriptions, and Claude Code caps that listing at a share of the context window. When the listing is over the cap, Claude Code keeps every skill’s name but drops the descriptions of the least-used skills, so Claude can still invoke those skills but is less likely to choose one on its own. Raise this key to keep more descriptions visible at the cost of more context per turn.

  • Values: number, a fraction greater than 0 and at most 1
  • Default: 0.01, which reserves 1% of the context window
  • Scope: any settings file.

Docs: skillListingBudgetFraction.

§ssh_configs: Option<Vec<SshConfig>>

Add SSH connections to the Desktop environment selector. Administrators use sshConfigs to distribute shared connections to a team. Users can select a managed connection and set their own Worktree folder for it.

  • Values: array of objects, each with required id, name, and sshHost and optional sshPort and sshIdentityFile
  • Default: unset
  • Scope: user or managed. The desktop app reads this key.

Docs: sshConfigs.

§ssh_host_allowlist: Option<Vec<String>>

Limit the hosts a Desktop SSH session can connect to. Only the Desktop app reads this key; the CLI doesn’t. Patterns are case-insensitive: * matches any host, *.example.com matches example.com and every subdomain, and anything else is an exact match against the hostname after ~/.ssh/config resolution.

  • Values: array of hostname patterns
  • Default: unset, so any host is allowed
  • Scope: managed. By default, Desktop reads the key from one managed source.

Docs: sshHostAllowlist.

§theme: Option<Theme>

Pick the color theme for the interface. Appears in /config as Theme.

  • Values: string, one of:
    • "auto": matches your terminal’s light or dark background
    • "dark": the dark theme
    • "light": the light theme
    • "dark-daltonized": the dark theme with colorblind-friendly colors
    • "light-daltonized": the light theme with colorblind-friendly colors
    • "dark-ansi": the dark theme using only your terminal’s ANSI color palette
    • "light-ansi": the light theme using only your terminal’s ANSI color palette
    • "custom:<slug>" or "custom:<plugin-name>:<slug>": a custom theme from ~/.claude/themes/ or a plugin
  • Default: "dark"
  • Scope: any settings file. A value in ~/.claude.json from an older version applies when no settings file sets it.

Docs: theme.

§voice: Option<Voice>

Turn on voice dictation and choose how the dictation key behaves. Claude Code writes this object for you when you run /voice.

  • Values: object with enabled as a Boolean, autoSubmit as a Boolean that applies in hold mode only, and mode, one of:
    • "hold": you hold the dictation key while speaking and release it to stop
    • "tap": you tap the key once to start recording and again to send
  • Default: unset, so dictation is off; when enabled is true and mode is unset, Claude Code uses "hold"
  • Scope: any settings file.

Docs: voice.

§wheel_scroll_acceleration_enabled: Option<bool>

Accelerate mouse-wheel scroll speed during fast scrolls in fullscreen rendering. Set it to false for a constant scroll rate per wheel notch.

  • Values: Boolean
    • true: Claude Code accelerates mouse-wheel scroll speed during fast scrolls
    • false: Claude Code scrolls at a constant rate per wheel notch
  • Default: true
  • Scope: any settings file.

Docs: wheelScrollAccelerationEnabled.

§disable_bundled_skills: Option<bool>

Turn off the 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.

  • Values: 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
  • Scope: any settings file.

Docs: disableBundledSkills.

§away_summary_enabled: Option<bool>

Show a one-line session recap when you return to the terminal after a few minutes away. Set it to false, or turn off Session recap in /config, to stop the recap.

  • Values: Boolean
    • true: you see a one-line session recap when you return after a few minutes away
    • false: Claude Code shows no recap
  • Default: unset, so the recap is on
  • Scope: any settings file.

Docs: awaySummaryEnabled.

§auto_scroll_enabled: Option<bool>

Follow new output to the bottom of the conversation in fullscreen rendering. Turn it off to stay where you scrolled while Claude keeps working; permission prompts still scroll into view.

  • Values: Boolean
    • true: the conversation follows new output to the bottom
    • false: you stay where you scrolled while Claude keeps working; permission prompts still appear below the transcript
  • Default: true
  • Scope: any settings file.

Docs: autoScrollEnabled.

§allow_all_claude_ai_mcps: Option<bool>

Load the claude.ai connectors Claude Code fetches itself alongside a deployed managed-mcp.json. Without this key, managed-mcp.json takes exclusive control of MCP servers and suppresses those connectors.

  • Values: Boolean
    • true: Claude Code loads the claude.ai connectors alongside a deployed managed-mcp.json
    • false: a deployed managed-mcp.json takes exclusive control of MCP servers and suppresses the claude.ai connectors Claude Code fetches itself
  • Default: false, so a deployed managed-mcp.json suppresses the claude.ai connectors Claude Code fetches itself
  • Scope: managed. Users can’t re-enable connectors that exclusive control suppressed.

Docs: allowAllClaudeAiMcps.

§agent_push_notif_enabled: Option<bool>

Allow Claude to send a push notification to your phone when it decides one is worth sending, for example when a long task finishes. In a local session, Claude can send one while Remote Control is connected. Appears in /config as Push when Claude decides. When you change it there, Claude Code also saves the value to your account.

  • Values: Boolean
    • true: Claude can send a push notification to your phone when it decides one is worth sending
    • false: Claude doesn’t send those notifications
  • Default: false
  • Scope: any settings file. Claude Code also reads a value left in ~/.claude.json by older versions.

Docs: agentPushNotifEnabled.

§ax_screen_reader: Option<bool>

Render screen-reader friendly output: flat text without decorative borders or animations. Screen-reader mode uses the classic renderer, so the tui setting has no effect while it is active; attached background sessions still render fullscreen.

  • Values: Boolean
    • true: Claude Code renders flat text without decorative borders or animations, using the classic renderer
    • false: Claude Code renders normally
  • Default: unset, so screen-reader mode is off
  • Scope: user or managed. You can also set the key in a file you pass with --settings.

Docs: axScreenReader.

§claude_md: Option<String>

Inject CLAUDE.md-style instructions as organization-managed memory without deploying a separate file. Claude Code loads the text as a managed memory entry ahead of user and project CLAUDE.md files.

  • Values: string, the text of a CLAUDE.md file; write it as you would the file, Markdown included, with line breaks as \n
  • Default: unset
  • Scope: managed.

Docs: claudeMd.

§disable_artifact: Option<bool>

Warning: Deprecated, and replaced by enableArtifact. Claude Code still honors disableArtifact: true as equivalent to enableArtifact: false, and ignores disableArtifact: false. Use enableArtifact instead to turn off the Artifact tool, which publishes session output as a private web page on claude.ai.

  • Values: Boolean
    • true: Claude Code turns the Artifact tool off for every session the file applies to, and no other file turns it back on
    • false: ignored; to leave the tool on, remove the key
  • Default: unset, so the tool follows your account’s availability
  • Scope: any settings file.

Docs: disableArtifact.

§disable_auto_mode: Option<DisableFlag>

Remove auto mode from the Shift+Tab cycle. Any session that would otherwise start in auto mode, whether from --permission-mode auto, a settings file, or the built-in default, starts in default instead. Administrators set it in managed settings to prevent developers in their organization from using auto mode.

  • Values: the string "disable"
  • Default: unset
  • Scope: any settings file. Most useful in managed settings, where users can’t override it.

Docs: disableAutoMode.

§disable_claude_ai_connectors: Option<bool>

Turn off the claude.ai MCP connectors Claude Code fetches itself, so it neither fetches nor connects them. A true in any settings file applies: a checked-in project .claude/settings.json can opt a repository out of those connectors, but a project-level false can’t override a user- or managed-level true.

  • Values: Boolean
    • true: Claude Code neither fetches nor connects those connectors
    • false: the same as unset; Claude Code fetches your connectors unless another settings file or ENABLE_CLAUDEAI_MCP_SERVERS turns them off
  • Default: false, so Claude Code fetches your connectors
  • Scope: any settings file.

Docs: disableClaudeAiConnectors.

§disable_remote_control: Option<bool>

Turn off Remote Control: Claude Code then refuses claude remote-control, the --remote-control flag, auto-start, and the in-session toggle, and reports that your organization’s policy disabled it. Place it in managed settings for per-device MDM enforcement.

  • Values: Boolean
    • true: Claude Code refuses claude remote-control, the --remote-control flag, auto-start, and the in-session toggle
    • false: Remote Control stays available
  • Default: false
  • Scope: any settings file.

Docs: disableRemoteControl.

§disable_workflows: Option<bool>

Turn off dynamic workflows 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 instead, which the Dynamic workflows toggle in /config writes to your user settings.

  • Values: 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 and your plan’s default
  • Default: false
  • Scope: any settings file.

Docs: disableWorkflows.

§footer_links_regexes: Option<Vec<FooterLink>>

Render extra clickable badges in the footer below the input box when a regex matches turn output: tool results, including file contents and fetched pages, and Claude’s own responses. Use it to turn IDs printed by project CLIs, such as review tools and issue trackers, into session links.

  • Values: array of objects, each with type set to "regex", a pattern regex, a url template, and an optional label; {name} placeholders in url and label are filled from named capture groups in pattern
  • Default: unset, so no badges render
  • Scope: user or managed.

Docs: footerLinksRegexes.

§input_needed_notif_enabled: Option<bool>

Get a push notification on your phone when a permission prompt or question is waiting for your input. In a local session, Claude Code sends these only while Remote Control is connected. Appears in /config as Push when actions required.

  • Values: Boolean
  • Default: false
  • Scope: any settings file. Claude Code also reads a value left in ~/.claude.json by older versions.

Docs: inputNeededNotifEnabled.

§policy_helper: Option<PolicyHelper>

Run an executable you deploy that computes managed settings at startup, so you can derive policy from device posture, identity, or a remote service instead of a static file. Claude Code runs the helper before it accepts the first prompt and treats the settings it emits as the managed settings for the session.

  • Values: object with path, timeoutMs, and refreshIntervalMs
  • Default: unset, so no helper runs
  • Scope: managed. Read from the macOS plist, the Windows HKLM registry, or the managed settings file.

Docs: policyHelper.

§remote_control_at_startup: Option<bool>

Connect Remote Control automatically when each interactive session starts, instead of waiting for /remote-control. Set it to true to turn auto-connect on, false to turn it off. Appears in /config as Enable Remote Control for all sessions.

  • Values: Boolean
    • true: Claude Code connects Remote Control automatically when each interactive session starts
    • false: Claude Code waits for /remote-control
  • Default: unset, so the auto-connect default applies
  • Scope: any settings file. Claude Code also reads a value left in ~/.claude.json by older versions.

Docs: remoteControlAtStartup.

§syntax_highlighting_disabled: Option<bool>

Claude Code colors code by language in the diffs, code blocks, and file previews it shows in the terminal, with its built-in highlighter. Set this key to true to show them as plain text instead, for example if the colors clash with your terminal theme or slow a screen reader.

  • Values: Boolean
    • true: Claude Code turns off syntax highlighting in diffs, code blocks, and file previews
    • false: Claude Code highlights syntax
  • Default: false
  • Scope: any settings file.

Docs: syntaxHighlightingDisabled.

§verbose: Option<bool>

By default, the transcript collapses each tool call to a short summary, such as the command Claude ran and a line count of its output, and you press Ctrl+O to switch the whole transcript to the expanded view when you want the details. Set this key to true to show every tool call’s full input and output inline as it happens, which is useful when you’re debugging a hook, an MCP server, or a long shell command. Appears in /config as Verbose output.

  • Values: Boolean
    • true: you see full tool output
    • false: you see truncated summaries of tool output
  • Default: false
  • Scope: any settings file. A value in ~/.claude.json from an older version applies when no settings file sets it.

Docs: verbose.

§workflow_keyword_trigger_enabled: Option<bool>

Choose whether typing the keyword ultracode in a prompt triggers a dynamic workflow. Set it to false to type the word without triggering one.

  • Values: Boolean
    • true: typing ultracode in a prompt triggers a dynamic workflow
    • false: you can type the word without triggering one
  • Default: true
  • Scope: any settings file. Appears in /config as Ultracode keyword trigger.

Docs: workflowKeywordTriggerEnabled.

§ask_user_question_timeout: Option<DialogTimeout>

Let an unanswered AskUserQuestion dialog auto-continue after a period of idle time, submitting whatever options you had already selected. Set it when you step away and want Claude to continue without you. With the default, questions wait until you answer them.

  • Values: string, one of "60s", "5m", "10m", or "never"
  • Default: "never"
  • Scope: user or managed.

Docs: askUserQuestionTimeout.

§teammate_default_model: Option<Option<String>>

Warning: Removed in v2.1.234, together with its /config row Default teammate model. Setting it has no effect on current versions. Through v2.1.233, you set this key to the model for agent team teammates your prompt didn’t name a model for: an alias such as "sonnet", or null to follow the lead’s model. For the model Claude Code picks for such teammates now, see specify teammates and models.

  • Values: string, a model alias or full model ID, or null
  • Default: unset
  • Scope: global config. On v2.1.233 and earlier.

Docs: teammateDefaultModel.

§workflow_size_guideline: Option<WorkflowSize>

Set the agent count Claude aims for 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 10, and "large" fewer than 50. Choose "small" when you want to bound what a workflow spends.

  • Values: 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 10 agents
    • "large": Claude aims for fewer than 50 agents
  • Default: "medium", or "small" when you’re signed in on a Pro plan with Claude Code v2.1.271 or later
  • Scope: any settings file. 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.

Docs: workflowSizeGuideline.

§enable_artifact: Option<bool>

Turn off the Artifact tool, which publishes session output as a private web page on claude.ai. When you turn the Artifacts row off in /config, Claude Code writes this key to your user settings, so you don’t usually edit it by hand.

  • Values: Boolean
    • false: Claude Code turns the Artifact tool off for every session the file applies to
    • true: the same as leaving the key unset, because it never overrides a false from another file, from CLAUDE_CODE_DISABLE_ARTIFACT, or from your organization’s admin setting
  • Default: unset, so the tool follows your account’s availability
  • Scope: any settings file. Every file can turn the tool off, and none can turn it back on.

Docs: enableArtifact.

§permission_explainer_enabled: Option<bool>

Warning: Removed in v2.1.257, together with the Ctrl+E command explanation on Bash and PowerShell permission prompts. Setting it has no effect on current versions. Through v2.1.256, you could press Ctrl+E on a Bash or PowerShell permission prompt to see a model-generated explanation of the command, and set this key to false to turn that shortcut off.

  • Values: Boolean
  • Default: true
  • Scope: global config. On v2.1.256 and earlier.

Docs: permissionExplainerEnabled.

§diff_tool: Option<DiffTool>

Choose where Claude Code shows the diff of an Edit or Write change it proposes when a VS Code or JetBrains IDE is connected: "auto" opens it in the IDE’s diff viewer, "terminal" keeps it in the terminal. Appears in /config as Diff tool only while Claude Code is connected to a VS Code or JetBrains IDE.

  • Values: string, one of:
    • "auto": Claude Code opens the diff in the IDE’s diff viewer when a VS Code or JetBrains IDE is connected
    • "terminal": Claude Code keeps the diff in the terminal
  • Default: "auto"
  • Scope: global config.

Docs: diffTool.

§external_editor_context: Option<bool>

When you press Ctrl+G, Claude Code opens the prompt you’re typing in your external editor. With this key on, the editor buffer starts with Claude’s previous response as # comment lines, so you can read it while you write, and Claude Code strips those lines when you save. Appears in /config as Show last response in external editor.

  • Values: Boolean
    • true: the editor buffer starts with Claude’s previous response as # comment lines, which Claude Code strips when you save
    • false: the editor buffer opens with only your prompt
  • Default: false
  • Scope: global config.

Docs: externalEditorContext.

§auto_connect_ide: Option<bool>

Connect to a running IDE automatically when you start Claude Code from an external terminal. Appears in /config as Auto-connect to IDE (external terminal) when you run Claude Code outside a VS Code or JetBrains terminal.

  • Values: Boolean
    • true: Claude Code connects to a running IDE automatically when you start it from an external terminal
    • false: Claude Code doesn’t connect automatically from an external terminal; inside a VS Code or JetBrains terminal, or with --ide, it still connects
  • Default: false
  • Scope: global config.

Docs: autoConnectIde.

§auto_install_ide_extension: Option<bool>

Let /ide install the Claude Code IDE extension in a running VS Code, Cursor, or Devin Desktop when you run the command from an external terminal. Claude Code doesn’t install or update the extension when you start claude. Before v2.1.318, Claude Code installs or updates the extension when you start claude in one of those editors’ terminals, unless this key is false.

  • Values: Boolean
    • true: /ide installs the extension
    • false: /ide doesn’t install the extension
  • Default: true
  • Scope: global config.

Docs: autoInstallIdeExtension.

§emoji_completion_enabled: Option<bool>

Show emoji suggestions when you type : plus a shortcode in the prompt input, and replace a completed shortcode such as :heart: with its emoji. Set it to false to turn off both.

  • Values: Boolean
    • true: Claude Code shows emoji suggestions after : and replaces a completed shortcode with its emoji
    • false: Claude Code neither suggests emoji nor replaces shortcodes
  • Default: true
  • Scope: any settings file.

Docs: emojiCompletionEnabled.

§vim_insert_mode_remaps: Option<BTreeMap<String, String>>

Map two-key INSERT-mode sequences to Escape in vim editor mode. Each key is exactly two printable characters typed in sequence, and "<Esc>" is the only supported target; Claude Code ignores other entries.

  • Values: object mapping a two-character sequence to "<Esc>"
  • Default: unset
  • Scope: user or managed. A repository can’t remap your keystrokes.

Docs: vimInsertModeRemaps.

§process_wrapper: Option<String>

On macOS and Linux, place a corporate launcher command in front of the background processes Claude Code starts. Claude Code runs the launcher with its own command line appended, so the launcher must exec into Claude Code; see Run Claude Code behind a corporate launcher for the launcher contract. Requires Claude Code v2.1.210 or later.

  • Values: string, the launcher command as an argv prefix, such as an absolute path with optional arguments
  • Default: unset, so background processes start unwrapped
  • Scope: user or managed.

Docs: processWrapper.

§force_login_gateway_url: Option<String>

Set the gateway URL the /login Cloud gateway screen connects to, so people reach your cloud gateway without typing its address. The screen has no URL field: with this key set, it shows your gateway URL and connects when the person presses Enter; without it, it tells them to contact their IT administrator. In managed settings, either this key or forceLoginMethod: "gateway" makes the machine gateway-only, except for sessions that select a cloud provider with CLAUDE_CODE_USE_*.

  • Values: string, a full URL including the scheme
  • Default: unset, so the Cloud gateway screen shows an error telling people to contact their IT administrator
  • Scope: user or managed. Read from a managed source on the machine: managed-settings.json, the macOS plist or Windows HKLM registry, or a policy helper.

Docs: forceLoginGatewayUrl.

§disable_sideload_flags: Option<bool>

Reject the --plugin-dir, --plugin-url, --agents, and --mcp-config CLI flags at startup, which users could otherwise pass to bypass strictKnownMarketplaces for a single run. Claude Code exits with an error naming the rejected flags. In cloud sessions, Claude Code instead starts the session and drops every server-delivered --mcp-config entry except in-process type: "sdk" entries and a Claude Tag session’s Slack tools.

  • Values: Boolean
    • true: Claude Code rejects --plugin-dir, --plugin-url, --agents, and --mcp-config at startup and exits with an error naming them. In cloud sessions, it instead starts the session and drops every server-delivered --mcp-config entry except in-process type: "sdk" entries and a Claude Tag session’s Slack tools
    • false: Claude Code accepts those flags
  • Default: false
  • Scope: managed.

Docs: disableSideloadFlags.

§browser_external_page_tools: Option<DisabledFlag>

Stop Claude from using its tools to read or act on external pages in the desktop app’s Browser pane. People in your organization can still open external sites themselves, and local dev server previews keep working with Claude’s tools. The desktop app reads this key; the terminal CLI ignores it.

  • Values: string, "disabled"; the desktop app also accepts "disable", in either case
  • Default: unset, so Claude’s tools work on external pages
  • Scope: managed.

Docs: browserExternalPageTools.

§disable_browser_external_navigation: Option<bool>

Turn off external browsing in the desktop app’s Browser pane for people and Claude alike. Localhost dev server previews keep working. HTML previews in SSH and WSL sessions still open, but they don’t run scripts.

  • Values: Boolean; only the JSON Boolean true takes effect
    • true: the desktop app turns off external browsing in the Browser pane for people and Claude alike; localhost previews keep working
    • false: external browsing stays on
  • Default: unset, so external browsing is on
  • Scope: managed.

Docs: disableBrowserExternalNavigation.

§disable_mobile_simulator_tools: Option<bool>

Block Claude’s tools for the desktop app’s iOS Simulator pane. People keep manual use of the pane; only Claude’s access is removed, and nobody can turn it back on from inside the app. The desktop app reads this key; the terminal CLI ignores it.

  • Values: Boolean; only the JSON Boolean true takes effect
    • true: the desktop app blocks Claude’s tools for the iOS Simulator pane
    • false: Claude’s simulator tools follow each person’s settings toggle in the desktop app
  • Default: unset, so Claude’s simulator tools follow each person’s settings toggle in the desktop app
  • Scope: managed.

Docs: disableMobileSimulatorTools.

§require_cowork_full_vm_sandbox: Option<bool>

(Managed settings only) Run Claude’s tools inside an isolated virtual machine instead of on your Mac. Disables the desktop app’s iOS Simulator pane and Claude’s simulator tools entirely, so the pane cannot attach a device while it is set.

  • Values: Boolean
  • Default: unset

Docs: not in the settings reference; listed in the JSON schema.

§allow_claude_in_chrome_with_managed_mcp: Option<bool>

Let the built-in Claude in Chrome server run alongside a deployed managed-mcp.json. Without this key, a deployed managed-mcp.json blocks Claude in Chrome in terminal sessions. Requires Claude Code v2.1.282 or later.

  • Values: Boolean
    • true: the built-in Claude in Chrome server can run alongside a deployed managed-mcp.json
    • false: a deployed managed-mcp.json blocks Claude in Chrome in terminal sessions
  • Default: false, so a deployed managed-mcp.json blocks Claude in Chrome in terminal sessions
  • Scope: managed, from the device’s own managed settings only: an MDM-deployed plist or HKLM registry key, or a system managed-settings.json file. Claude Code ignores it in server-managed settings, in the user-writable HKCU registry, and in user or project settings.

Docs: allowClaudeInChromeWithManagedMcp.

§allowed_providers: Option<Vec<Provider>>

List the services a machine may reach Claude through, such as the Anthropic API, Amazon Bedrock, or an LLM gateway. A session on a provider that isn’t listed is refused at startup, at login, and when it next contacts the API, so switching to an unlisted provider mid-session is refused too. The refusal message names what selected the provider and the steps to continue.

  • Values: array of strings, each one of:
  • Default: unset, so any provider can be used
  • Scope: managed. A list that the machine’s own admin sources set, MDM policies and managed settings files, keeps applying when server-managed settings also deliver one: a session may then use only the providers on both lists, so a server-managed list can narrow what the machine allows but never widen it.

Docs: allowedProviders.

§append_plugins: Option<Vec<String>>

List the managed plugins whose mods run after every mod a user installs, in the listed order. An id listed in both prependPlugins and appendPlugins is prepended. In managed settings, Claude Code skips an id whose plugin doesn’t count as your organization’s.

  • Values: array of plugin-name@marketplace-name strings
  • Default: unset
  • Scope: user or managed. Claude Code reads the key from managed settings.

Docs: appendPlugins.

§auto_compact_window: Option<u64>

Set how full the context window gets before Claude Code compacts automatically.

  • Values: number of tokens, from 100000 to 1000000. Claude Code caps the value at your model’s context window; the models overview lists each model’s window
  • Default: unset, so Claude Code picks a window tuned for your model
  • Scope: any settings file.

Docs: autoCompactWindow.

§auto_continue_at_usage_limit: Option<bool>

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. Requires Claude Code v2.1.234 or later.

  • Values: 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 from the usage-limit options menu
  • Default: true
  • Scope: user or managed. Read from user settings, --settings, and managed settings only.

Docs: autoContinueAtUsageLimit.

§available_models_match: Option<ModelMatch>

Choose how availableModels entries match model IDs. By default a model ID entry also permits later versions that extend it, so "claude-opus-5" permits Opus 5.5. With "exact", each model ID entry permits only the version it names, so a newer version of that model stays blocked until you list it.

  • Values: string, one of:
    • "prefix": a model ID entry permits its version and any model ID that extends it with another segment
    • "exact": a model ID entry permits only the version it names, so "claude-opus-5" permits Opus 5 but not claude-opus-5-5. An entry such as "claude-opus-4-5" also permits its dated Anthropic model ID claude-opus-4-5-20251101. A family alias such as "opus" still permits the whole family, and best, opusplan, and default entries are ignored
  • Default: "prefix"
  • Scope: managed. Claude Code ignores the key in user, project, and local settings and in --settings, with a warning.

Docs: availableModelsMatch.

§bash_edit_diff_enabled: Option<bool>

Choose whether Claude Code records which files changed in a Git repository while a Bash command runs. When it records them, you see their diff in the terminal after the command, and your PostToolUse Bash hooks receive the changed-file list. A listed file isn’t always one the command changed.

  • Values: Boolean
  • Default: unset, so Claude Code records changes in auto mode and bypassPermissions mode when it directs Claude to edit files through Bash
  • Scope: user or managed. A true counts only from your user settings, JSON passed with --settings, or managed settings, so a true in a repository’s .claude/settings.json or .claude/settings.local.json can’t turn the recording on.

Docs: bashEditDiffEnabled.

§bash_output_max_chars: Option<u64>

Set how many characters of a successful Bash or PowerShell command’s output Claude receives inline. When output passes the limit, Claude Code saves it to a file and Claude receives a short preview plus the file’s path. Raise the limit when command output, such as a verbose build or a full test-suite log, routinely overflows the default and you want Claude to read it without opening the file.

  • Values: number of characters, a positive integer. Claude Code clamps the value into the range 4000 to 128000
  • Default: unset, so Claude receives up to 30,000 characters inline
  • Scope: any settings file.

Docs: bashOutputMaxChars.

§cross_session_inbound: Option<InboundMode>

Choose what this session does with messages arriving from your other Claude Code sessions. When no value applies, Claude Code decides per message from the two sessions’ permission-mode classes.

  • Values: string, one of:
    • "accept": Claude Code delivers the message to Claude
    • "hold": Claude Code shows a notice for the message without delivering it
    • "refuse": Claude Code drops the message
  • Default: unset, so Claude Code decides per message
  • Scope: any settings file. A project or local value applies only when it’s stricter than the value managed settings, the --settings flag, or user settings give.

Docs: crossSessionInbound.

§denied_models: Option<Vec<String>>

Block specific models, with or without an availableModels allowlist and even when that list permits them. Claude Code hides a blocked model from the /model picker, and the model can’t be selected anywhere availableModels is enforced. A session on the Default option doesn’t run a blocked model either, as Block specific models or versions describes.

  • Values: array of model aliases or IDs
    • A family alias such as "opus" blocks every model in that family
    • A model ID such as "claude-opus-5-5" blocks that version in every spelling, including dated and provider-specific IDs
    • A model ID with no minor version, such as "claude-opus-5", also blocks later minor versions such as Opus 5.5. Write "claude-opus-5-0" to block Opus 5 alone
    • best, opusplan, and default entries are ignored
  • Default: unset, so no model is blocked
  • Scope: managed. Claude Code ignores the key in user, project, and local settings and in --settings, with a warning.

Docs: deniedModels.

§desktop_session_cleanup_period_days: Option<u64>

Set an age limit in days for the transcripts of sessions you started or most recently continued in Claude Desktop or Cowork. Without this key, Claude Code keeps those transcripts at any age, except in cases such as a session you deleted in Claude Desktop. Requires Claude Code v2.1.248 or later.

  • Values: number of days, a whole number, minimum 0
  • Default: 0, which sets no age limit
  • Scope: user or managed. Claude Code also reads the key from a file you pass with --settings, and ignores it in project and local settings.

Docs: desktopSessionCleanupPeriodDays.

§dialog_expiry: Option<DialogTimeout>

Set the deadline for dialogs Claude Code forwards to a remote client, such as a Remote Control or SDK host, and for the approval dialog for a held cross-session message. On Claude Code v2.1.236 or later, the same deadline bounds the mid-session Fable usage-credits consent prompt in a session that may have nobody at the terminal. When no answer arrives before the deadline, Claude Code cancels the dialog and continues with its no-action default.

  • Values: string, one of "60s", "5m", "10m", or "never", which disables the deadline
  • Default: "5m"
  • Scope: user or managed.

Docs: dialogExpiry.

§disable_command_plugin_sources: Option<bool>

Block the command plugin source, which installs a plugin by running a marketplace-declared command on the user’s machine. When you set it to true, Claude Code never runs the command, doesn’t install or update command-sourced plugins, and stops loading the ones already installed. Set it to false to allow them explicitly.

  • Values: Boolean
    • true: Claude Code never runs the marketplace-declared command, doesn’t install or update command-sourced plugins, and stops loading the ones already installed
    • false: Claude Code allows command-sourced plugins explicitly
  • Default: unset, so Claude Code follows allowManagedHooksOnly: an organization that restricts hook execution to managed settings gets command sources disabled too. An application that passes disableAllHooks: true in the Agent SDK’s managedSettings option doesn’t by itself disable command sources.
  • Scope: managed.

Docs: disableCommandPluginSources.

§disable_desktop_local_sessions: Option<bool>

Turn off Code sessions that run on the device in the desktop app, for deployments where developers should work on remote machines over SSH. With the key set to true, users see this in the Code tab:

  • Values: Boolean; only the JSON Boolean true takes effect
    • true: the desktop app offers no on-device Code sessions; existing local sessions stay listed but can’t continue
    • false: local sessions stay available
  • Default: unset, so local sessions are available
  • Scope: managed. By default, the desktop app reads the key from one managed source.

Docs: disableDesktopLocalSessions.

§disable_remote_preview_scripts: Option<bool>

Keep scripts from running when people preview an HTML file from an SSH or WSL session in the desktop app. External browsing in the Browser pane is unaffected. The desktop app reads this key; the terminal CLI ignores it.

  • Values: Boolean; only the JSON Boolean true takes effect
    • true: HTML previews in SSH and WSL sessions don’t run scripts
    • false: the key doesn’t turn scripts off
  • Default: unset, so the key has no effect
  • Scope: managed. The desktop app doesn’t read the key from the remote machine or the WSL distribution.

Docs: disableRemotePreviewScripts.

§enable_workflows: Option<bool>

Turn dynamic 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 instead.

  • Values: 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
  • Scope: any settings file.

Docs: enableWorkflows.

§feedback_drafts: Option<FeedbackDrafts>

Control Claude-drafted feedback: whether Claude can queue feedback drafts for you to review, and whether Claude Code shows a card when Claude queues one.

  • Values: string, one of "notify", "quiet", or "off"
    • "notify": Claude Code shows a card above the prompt when Claude queues a draft, up to three cards in a session by default
    • "quiet": Claude drafts without a card. You see the count of queued drafts in the prompt footer and review them in /feedback
    • "off": Claude Code removes the SendFeedback tool, so Claude can’t queue drafts
  • Default: "notify"
  • Scope: user or managed.

Docs: feedbackDrafts.

§gateway_internal_networks: Option<Vec<String>>

Declare the public IPv4 blocks that your organization numbers its internal network from, so /login accepts a cloud gateway there. Requires Claude Code v2.1.268 or later. Without this key, /login connects to any gateway on a private address and nothing else.

  • Values: array of strings, at most four IPv4 CIDR blocks, each /8 to /32, not overlapping one another, and none overlapping private space.
  • Default: unset, so /login accepts only gateways on private addresses
  • Scope: managed. Read only from a source on the machine: managed-settings.json, the macOS plist or Windows HKLM registry, or a policy helper.

Docs: gatewayInternalNetworks.

§idle_compaction: Option<bool>

Idle compaction compacts a long conversation that you’ve stepped away from. Your next message then sends a summary instead of the whole conversation. Once compacted, the conversation shows a notice:

  • Values: Boolean
    • true: Claude Code compacts idle conversations that meet the conditions
    • false: Claude Code doesn’t compact while your session is idle
  • Default: true
  • Scope: any settings file.

Docs: idleCompaction.

§isolate_peer_machines: Option<bool>

Require your explicit approval before Claude’s SendMessage reaches one of your sessions beyond this machine; see Require approval for cross-machine messages. The approval prompt appears even in bypassPermissions mode.

  • Values: Boolean
    • true: Claude Code asks for your approval before Claude’s SendMessage reaches one of your sessions beyond this machine
    • false: cross-machine messages don’t prompt
  • Default: unset, so cross-machine messages don’t prompt
  • Scope: any settings file. A true from any scope applies, so a checked-in project file can turn the requirement on but not off.

Docs: isolatePeerMachines.

§keybinding_flavor: Option<KeybindingFlavor>

Warning: Deprecated since v2.1.261 and has no effect. The prompt’s word-editing keys always follow readline conventions, as in Bash. Claude Code still accepts keybindingFlavor, so a settings file that sets it stays valid.

  • Values: string, "classic" or "readline"
  • Default: unset
  • Scope: any settings file.

Docs: keybindingFlavor.

§managed_sources_behavior: Option<SourcesBehavior>

Choose whether Claude Code applies only the highest-priority managed source your organization delivers, or combines every admin source it delivers. By default Claude Code takes the highest-priority source that carries a policy key and ignores the rest. A policy key is any settings key other than this one and wslInheritsWindowsSettings.

  • Values: string, one of:
    • "first-wins": the highest-priority source that carries a policy key supplies the policy, and lower sources contribute only the keys Claude Code reads from every admin source
    • "merge": every admin source you deliver contributes its keys, combined by the rules below
  • Default: "first-wins"
  • Scope: managed. Claude Code reads this key from the highest-priority source that carries either this key or a policy key, and ignores this key in every source ranked lower, so a lower source can’t opt itself into combining with the source above it.

Docs: managedSourcesBehavior.

§max_effort_level: Option<EffortLevel>

Cap the effort level a session can use, leaving lower levels available. Any higher level runs at the cap instead, including one from /effort, the /model picker, --effort, CLAUDE_CODE_EFFORT_LEVEL, a skill’s or subagent’s effort frontmatter, or the model’s own default. Claude Code applies the cap itself before each request, so it holds on every provider, including Amazon Bedrock, Google Cloud’s Agent Platform, and Microsoft Foundry.

  • Values: string, one of "low", "medium", "high", "xhigh", or "max". A "max" value sets no cap
  • Default: unset, so no cap applies
  • Scope: any settings file. Deploy it in managed settings to enforce it for an organization.

Docs: maxEffortLevel.

§max_prose_width: Option<u64>

Cap the width of the prose in Claude’s responses so lines stay readable in a wide terminal. Paragraphs, headings, lists, and blockquotes wrap within this many columns, while tables and code blocks keep the full terminal width. Requires Claude Code v2.1.282 or later.

  • Values: number of terminal columns, a whole number, minimum 40. Claude Code ignores any other value
  • Default: unset, so prose wraps at the terminal edge
  • Scope: any settings file.

Docs: maxProseWidth.

§model_picker: Option<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.

  • Values: object with an options array of rows and an optional replaceBuiltInOptions Boolean
  • Default: unset, so the picker shows the built-in lineup
  • Scope: user or managed. 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.

Docs: modelPicker.

§model_pricing: Option<ModelPricing>

Report spend at the rates your organization pays instead of list price. Set it when your organization has contracted rates, so the dollar figures developers see match your bill. Claude Code applies the rates in /usage, the status line, the Agent SDK’s total_cost_usd, the --max-budget-usd limit, and the OpenTelemetry cost metric and events.

  • Values: object with an optional multiplier and an optional overrides map
  • Default: unset, so Claude Code reports list price unless a host application supplies a table
  • Scope: managed. Deploy the key through server-managed settings, an MDM policy, a managed-settings.json file, or a policy helper.

Docs: modelPricing.

§model_settings: Option<BTreeMap<String, ModelSettings>>

Save an effort level for each model you use. Requires Claude Code v2.1.251 or later. In an interactive session on your machine, when you save low, medium, high, or xhigh as your default with /effort or the /model picker’s effort slider, Claude Code writes that level here under the model you’re using, so you rarely edit this key yourself.

  • Values: object mapping a model name to an object with any of these fields:
    • effortLevel: one of "low", "medium", "high", or "xhigh"
    • maxEffortLevel: the highest effort level the model may run at
    • autoCompactWindow: a number of tokens from 100000 to 1000000, or "auto" for the window tuned for the model. /autocompact saves here. For that model, the value takes precedence over a top-level autoCompactWindow in the same settings file. Requires Claude Code v2.1.288 or later
  • Default: unset
  • Scope: any settings file.

Docs: modelSettings.

§prepend_plugins: Option<Vec<String>>

List the managed plugins whose mods run before every mod a user installs, in the listed order. When you set this key in managed settings, name sec-default@builtin in the list to keep the built-in guard. In managed settings, Claude Code skips an id whose plugin doesn’t count as your organization’s.

  • Values: array of plugin-name@marketplace-name strings
  • Default: unset
  • Scope: user or managed. Claude Code reads the key from managed settings.

Docs: prependPlugins.

§prompt_cache_ttl: Option<CacheTtl>

Choose how long the prompt cache 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 than at the five-minute lifetime.

  • Values: 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
  • Scope: any settings file.

Docs: promptCacheTtl.

§prompt_suggestion_enabled: Option<bool>

Show or hide prompt suggestions, the grayed-out predictions that appear in your prompt input. Set it to false, or turn off Prompt suggestions in /config, to hide them.

  • Values: Boolean
    • true: you see prompt suggestions in your prompt input
    • false: Claude Code hides prompt suggestions
  • Default: true
  • Scope: any settings file.

Docs: promptSuggestionEnabled.

§skip_auto_permission_prompt: Option<bool>

Skip the one-time notice describing auto mode that Claude Code shows when you first enter auto mode yourself, for example through your own settings or the mode selector, rather than when the built-in default starts a session in it. Claude Code shows that notice once and then records that it was shown, so this key only matters where the notice hasn’t appeared yet.

  • Values: Boolean
    • true: Claude Code skips the notice
    • false: the same as unset; the notice appears once unless another of these files sets true
  • Default: unset, so the notice appears once
  • Scope: user or managed. A repository can’t set it for you.

Docs: skipAutoPermissionPrompt.

§spellcheck: Option<Spellcheck>

Underline misspelled words in the prompt input as you type, using a spell checker you install. Claude Code checks only the text in the input box. Check spelling as you type covers installing aspell, hunspell, or ispell and what the checker covers.

  • Values: object with enabled (Boolean), checker ("aspell", "hunspell", "ispell", or "auto"), language (string, passed to the checker as its dictionary name), and color (string, a terminal color name, #rrggbb, rgb(r,g,b), ansi256(n), or ansi:<name>)
  • Default: unset, so spell checking is off; checker defaults to "auto", the first of the three found on PATH; language defaults to the checker’s own dictionary; color defaults to the theme’s error color
  • Scope: user or managed. The block from the highest tier that sets it applies as a whole.

Docs: spellcheck.

§ssh_host_commands: Option<Vec<SshHostCommand>>

Add SSH connections whose host comes from a command to the Desktop environment selector. When you create a connection or create another machine for it, Desktop runs the entry’s command on your computer and connects to the host that the command prints. Requires Claude Desktop v3.6556.0 or later on macOS or Linux, or v4.16336.0 or later on Windows, signed in with a Claude account.

  • Values: array of objects, each with required id, name, and command and optional sshIdentityFile and startDirectory. Desktop doesn’t read command as shell syntax, so pipes and variables don’t work: write it as a program and its arguments.
  • Default: unset
  • Scope: user or managed. Only the desktop app reads this key.

Docs: sshHostCommands.

§subagent_prompt_cache_ttl: Option<CacheTtl>

Choose how long the prompt cache holds the requests Claude Code makes outside the main conversation. This key applies to subagents, 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 than at the five-minute lifetime.

  • Values: 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
  • Scope: any settings file.

Docs: subagentPromptCacheTtl.

§switch_models_on_flag: Option<bool>

Choose what happens when a safety classifier flags a request: switch to the fallback model and continue, or pause so you can choose between switching and editing the prompt.

  • Values: Boolean
    • true: Claude Code switches to the fallback model and continues
    • false: in an interactive session Claude Code pauses so you can choose between switching and editing the prompt; where no dialog can show, such as a -p run, the flagged request ends as an error
  • Default: unset. Claude Code switches automatically, though it may ask first in an interactive session
  • Scope: any settings file. Appears in /config as Switch models when a message is flagged, with the options Switch automatically and Ask each time.

Docs: switchModelsOnFlag.

§sync_claude_ai_plugins: Option<bool>

Turn off the download of the plugins enabled for your claude.ai account. Claude Code downloads them into ~/.claude/plugins/synced/ at the start of terminal sessions where you sign in with your claude.ai account and in Cowork sessions, and loads each one as <name>@synced. Set false to stop that download and stop loading the plugins it already synced.

  • Values: Boolean
    • false: Claude Code stops downloading synced plugins and stops loading the ones already in ~/.claude/plugins/synced/. In user or managed settings, it also moves them to ~/.claude/plugins/.trash/
    • true: the same as unset
  • Default: unset, so sessions signed in with your claude.ai account sync your plugins
  • Scope: user, local, or managed, and files passed with --settings. A repository can’t turn it off for you.

Docs: syncClaudeAiPlugins.

§sync_claude_ai_skills: Option<bool>

Turn off the download of the skills enabled for your claude.ai account. Claude Code downloads them into ~/.claude/skills/synced/ in terminal sessions where you sign in with your claude.ai account, interactive or non-interactive, and in Cowork and cloud sessions. Set false to stop that download and stop loading the skills it already synced.

  • Values: Boolean
    • false: Claude Code stops downloading synced skills and stops loading 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 sessions signed in with your claude.ai account sync your skills
  • Scope: user, local, or managed, and files passed with --settings. A repository can’t turn it off for you.

Docs: syncClaudeAiSkills.

§task_output_max_chars: Option<u64>

Warning: Removed in v2.1.277, together with the TaskOutput tool it sized. Setting it has no effect on current versions. Claude reads a background task’s output file with Read instead.

  • Values: a whole number of characters
  • Default: unset

Docs: taskOutputMaxChars.

§terminal_title_from_rename: Option<bool>

Claude Code sets your terminal tab’s title. By default it uses a title it generates from the conversation, and once you give the session a name with /rename or --name, the tab shows that name instead. Set this key to false to keep the generated title on the tab even after you name the session.

  • Values: Boolean
    • true: the terminal tab title shows the session name you set
    • false: the tab keeps the title Claude Code generates from your conversation
  • Default: true
  • Scope: any settings file.

Docs: terminalTitleFromRename.

§time_format: Option<TimeFormat>

Choose how Claude Code writes the times it shows in the interface, such as the done 6:05 PM at the end of each turn duration message and the timestamps in the transcript viewer. To pick a preset, run /config and set Time format. Requires Claude Code v2.1.257 or later.

  • Values: string, one of:
    • "auto": the same as unset; each time keeps its built-in format, which follows your locale on the turn duration message
    • "12-hour": a 12-hour clock
    • "24-hour": a 24-hour clock
    • "24-hour-utc": a 24-hour clock in UTC with Z after the minutes, such as 18:05Z; Claude Code ignores timeZone for this preset
    • A strftime pattern such as "%H:%M": Claude Code writes each time with the pattern. Any value that contains a % is a pattern, and any other value outside the presets counts as "auto"
  • Default: "auto"
  • Scope: any settings file.

Docs: timeFormat.

§time_zone: Option<String>

Show the times in the interface in a time zone other than your system’s. Set it to an IANA time zone name, such as "UTC" or "Europe/Dublin". The times that timeFormat controls then show in this zone.

  • Values: string, an IANA time zone name. When Claude Code doesn’t recognize the name, it uses your system time zone
  • Default: unset, so times show in your system time zone
  • Scope: any settings file.

Docs: timeZone.

§ultracode: Option<bool>

Start sessions with ultracode on. With it on, Claude plans a workflow for each substantive task instead of waiting for you to ask. Claude plans workflows only when dynamic workflows are enabled for you and your model supports xhigh effort.

  • Values: Boolean
    • true: sessions start with ultracode on when dynamic workflows are enabled for you and your model supports xhigh
    • false: sessions start with ultracode off
  • Default: unset, so ultracode is off
  • Scope: any settings file.

Docs: ultracode.

§remote: Option<Remote>

Defaults for cloud sessions.

  • Values: object with defaultEnvironmentId
  • Default: unset

Docs: remote.

§extra: Extra

Keys Claude Code accepts here that this crate doesn’t model (newer or undocumented ones), kept as written so the document round-trips.

Implementations§

Source§

impl Settings

Source

pub fn from_json_str(json: &str) -> Result<Self>

Parses a settings document.

§Errors

When json isn’t a JSON object, or a key this crate models holds a value of the wrong type (which Claude Code rejects as well).

Source

pub fn to_json_string(&self) -> Result<String>

The document as compact JSON: the argument of claude --settings.

§Errors

Only if a value can’t be written as JSON, which the types in this crate don’t produce; the error is returned rather than a panic.

Source

pub fn to_json_string_pretty(&self) -> Result<String>

The document as indented JSON, for a settings file.

§Errors

As to_json_string.

Source

pub fn merge(&mut self, higher: Settings) -> Result<()>

Layers higher over self the way Claude Code combines its settings sources: call it on the lowest layer with each higher one in turn (user, then project, then local, then --settings, then managed). merge_values has the rules.

§Errors

Only if the merged document doesn’t parse as Settings again, which two documents of these types can’t produce; self is left unchanged then.

Source

pub fn unknown_keys(&self) -> Vec<String>

The dotted paths of the keys this document holds but this crate doesn’t model (extra maps, hook types and hook events it doesn’t know), such as sandbox.network.newKey or hooks.NewEvent.

Trait Implementations§

Source§

impl Clone for Settings

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Settings

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Default for Settings

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl<'de> Deserialize<'de> for Settings

Source§

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>
where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer. Read more
Source§

impl PartialEq for Settings

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl Serialize for Settings

Source§

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>
where __S: Serializer,

Serialize this value into the given Serde serializer. Read more
Source§

impl StructuralPartialEq for Settings

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.