Model and responses

Choose which models Claude Code uses and how it responds. For how these settings interact with the /model command and environment variables, see Model configuration.

advisorModel

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; when it isn't, Claude Code sends requests without the advisor. See Choose an advisor model.

You don't usually edit this key by hand. Run /advisor to open a picker that shows the current choice, the models that can advise, and No advisor. Claude Code saves your pick to this key in ~/.claude/settings.json. If you pick from a Remote Control client or in a session attached to a remote worker, the pick applies to that session only and doesn't change this key.

If your account requires the usage-credits consent, accept it first by running /model fable. Until you do, picking Fable in /advisor saves nothing and Claude Code tells you to run /model fable first.

• Scope: Any file
• Type: 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"
• Default: unset, so the advisor is off
• Per-session overrides: --advisor takes precedence over this key for one session. CLAUDE_CODE_DISABLE_ADVISOR_TOOL turns the advisor off, and this key can't turn it back on

{
  "advisorModel": "opus"
}

The key has no effect on providers where the advisor isn't available, such as Amazon Bedrock and Claude Platform on AWS. "fable" requires Fable access.

alwaysThinkingEnabled

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.

On models that always think, such as the Fable models, false has no effect. On third-party providers Claude Code omits the thinking parameter instead of turning thinking off, so adaptive-reasoning models may still think. With thinking turned off on the Anthropic API, Claude Code sends effort high instead of a higher level to models it knows don't accept that combination, such as Opus 5.

• Scope: Any file
• Type: 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
• Per-session overrides: MAX_THINKING_TOKENS takes precedence over this key for one session: 0 turns thinking off, under the same model and provider limits as false, and a positive value turns thinking on even when this key is false. On adaptive-reasoning models the number itself is ignored

{
  "alwaysThinkingEnabled": false
}

availableModels

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. On its own this doesn't touch the Default option; pair it with enforceAvailableModels for that.

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

This example lets people select only Sonnet and Haiku models:

{
  "availableModels": ["sonnet", "haiku"]
}

See Restrict model selection.

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. Before v2.1.251, /effort wrote this key.

Within the same settings file, Claude Code uses a model's saved level rather than this key. modelSettings states the cross-file precedence.

In a session attached to a remote worker, /effort applies to that session only. In a -p run or the Agent SDK it also applies to that session only, unless a hold on the model's default effort is in effect. Adjust effort level lists the interactive picks that also apply to that session only. The message that /effort prints says which happened.

• Scope: Any file
• Type: 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
• Per-session overrides: --effort takes precedence over this key for one session, and CLAUDE_CODE_EFFORT_LEVEL takes precedence over both

{
  "effortLevel": "xhigh"
}

On Opus 4.7, Opus 4.8, and Fable 5, Claude Code holds that model's default effort, organization-set or built-in; Adjust effort level states which ways of setting a level end the hold and which leave it in place. Once the hold ends, Claude Code resolves effort by the precedence stated at modelSettings.

enforceAvailableModels

The /model picker has a Default option that resolves to your organization default model when one applies, and otherwise to your account type's default. An availableModels allowlist limits the models you can name, but on its own it leaves Default alone, so Default can still resolve to a model outside the list. This key closes that gap. Requires Claude Code v2.1.175 or later.

When your organization deploys any managed settings, Claude Code reads this key from the managed source alone and ignores it in your other files.

• Scope: Any file
• Type: Boolean
  • true: when Default would resolve to a model outside availableModels, Claude Code resolves it to the first available model in the list
  • false: Default resolves as usual, even to a model outside availableModels
• Default: false

This example restricts named selections to Sonnet and Haiku models and makes Default resolve to the first of them that is available:

{
  "availableModels": ["sonnet", "haiku"],
  "enforceAvailableModels": true
}

This key has no effect when availableModels is unset or empty. See Enforce the allowlist for the Default model. Requires Claude Code v2.1.175 or later.

fallbackModel

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.

A switch means one turn with a cold prompt cache on the fallback model; your next message tries the primary model first again.

• Scope: Any file
• Type: array of model aliases or IDs; "default" expands to the default model
• Default: unset, so a failed request isn't retried on another model
• Per-session overrides: --fallback-model takes precedence over this key for one session

This example tries Sonnet 5 first, then Haiku 4.5, when your primary model fails:

{
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}

Unlike most array settings, this key doesn't merge across settings files: the highest-precedence file that defines it supplies the whole chain. If your project file sets ["claude-sonnet-5"] and your user file sets ["claude-haiku-4-5"], the chain is ["claude-sonnet-5"] only. Claude Code keeps at most three distinct allowed models from the list and ignores the rest. See Fallback model chains.

fastMode

Turn fast mode on for sessions where it's available, for interactive work like rapid iteration or live debugging where you want speed at a higher cost per token. You don't usually edit this key by hand: running /fast writes fastMode: true to ~/.claude/settings.json, and running it again to turn fast mode off removes the key. Fast mode runs only on Opus 5 and Opus 4.8: turning it on from another model switches you to Opus, and switching to an unsupported model turns it off. See Switch models while fast mode is on.

• Scope: Any file
• Type: Boolean
  • true: Claude Code turns fast mode on for sessions where it's available
  • false: fast mode stays off
• Default: unset, so fast mode is off
• Per-session overrides: CLAUDE_CODE_DISABLE_FAST_MODE turns fast mode off for one session, and this key can't turn it back on

{
  "fastMode": true
}

fastModePerSessionOptIn

Normally, running /fast saves fastMode to a person's user settings, so fast mode is on at the start of every later session. Set this key to true to stop that: a saved fastMode: true no longer turns fast mode on at session start, and each person has to run /fast in each session they want it. Claude Code leaves the fastMode key in their file, so turning this key off restores the old behavior. Owners on Team or Enterprise plans can deploy it organization-wide through server-managed settings.

• Scope: Any file
• Type: 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 turns fast mode on at the start of every later session
• Default: false

{
  "fastModePerSessionOptIn": true
}

See Require per-session opt-in.

language

Have Claude respond in a language other than English by default. There is no fixed list for responses: Claude Code adds the value verbatim to the system prompt 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. The same value sets the language for voice dictation, which does have a fixed list of supported dictation languages, and for auto-generated session titles.

• Scope: Any file
• Type: 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

{
  "language": "japanese"
}

maxEffortLevel

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

• Scope: Any file. Deploy it in managed settings to enforce it for an organization. When several scopes set a cap, the lowest applies, so a cap set in one scope can't be raised from another
• Type: string, one of "low", "medium", "high", "xhigh", or "max". A "max" value sets no cap
• Default: unset, so no cap applies
• Effect on ultracode: a cap below xhigh makes ultracode unavailable on the models the cap applies to
• Per-model caps: add maxEffortLevel to a model's modelSettings entry. That entry replaces this key for the model only within the settings source that sets both, such as your user settings or one managed source. Set "max" there to exempt the model from that source's cap; Claude Code still applies caps from other sources

This example caps every model at medium and exempts Sonnet 4.6:

{
  "maxEffortLevel": "medium",
  "modelSettings": {
    "claude-sonnet-4-6": {
      "maxEffortLevel": "max"
    }
  }
}

When your organization also sets an effort limit for a model, the lower of the two caps applies.

model

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.

• Scope: Any file
• Type: string, a model alias or full model ID
• Default: unset, so Claude Code uses your account's default model
• Per-session overrides: --model takes precedence over ANTHROPIC_MODEL, and both take precedence over this key for one session, including over a managed model; an availableModels list still applies to the pick

{
  "model": "claude-sonnet-5"
}

A value here outranks ANTHROPIC_DEFAULT_MODEL, which Claude Code uses only when nothing else selects a model.

modelOverrides

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.

• Scope: Any file
• Type: object mapping model ID to provider model ID
• Default: unset

This example routes every call for Opus 4.6 to the named Bedrock inference profile:

{
  "modelOverrides": {
    "claude-opus-4-6": "arn:aws:bedrock:us-east-1:123456789012:inference-profile/example"
  }
}

See Override model IDs per version.

modelPicker

List the models the /model picker offers, in the order you write them and under labels you choose, so the picker lists the models your organization runs, after the built-in lineup or instead of it. Each row's model is taken verbatim, so it accepts anything --model accepts: an alias such as opus, an Anthropic model ID, or a provider-format ID for Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or an LLM gateway. Requires Claude Code v2.1.242 or later.

• Scope: User or managed. Claude Code reads the key from managed settings, --settings, and user settings, and ignores it in project and local settings so a repository you clone can't relabel the picker. The highest of those three that sets the key supplies the whole lineup, and Claude Code never combines lineups from two sources.
• Type: object with an options array of rows and an optional replaceBuiltInOptions Boolean
• Default: unset, so the picker shows the built-in lineup

This example adds two Bedrock deployments after the built-in lineup, under names your team recognizes:

{
  "modelPicker": {
    "options": [
      { "model": "us.anthropic.claude-opus-4-8", "label": "Opus (production)" },
      {
        "model": "us.anthropic.claude-sonnet-4-6",
        "label": "Sonnet (production)",
        "description": "Day-to-day work"
      }
    ]
  }
}

<span id="modelpicker-options" />

<span id="modelpicker-replacebuiltinoptions" />

Fields for modelPicker

The key takes two fields, one for the rows themselves and one for whether they replace the built-in lineup or add to it.

Field	Type	What it does
options	array of rows, each with a required model and an optional label and description	The rows the picker shows, in this order, except that a grayed-out row moves to the bottom. Without a label, Claude Code titles the row with the built-in name for a model it knows, or the model ID otherwise, and without a description it writes a generic second line
replaceBuiltInOptions	Boolean, default false	Set it to true to show only these rows, Default, and a row for the model the session is already using. Leave it unset to add these rows after the built-in lineup

With replaceBuiltInOptions on, Claude Code hides every other row: the built-in lineup, the rows it adds for availableModels entries, the models gateway discovery found, and ANTHROPIC_CUSTOM_MODEL_OPTION. With it off, Claude Code skips a listed model that the built-in lineup already covers. A label changes what the picker shows, not which model Claude Code runs.

An availableModels allowlist still applies to these rows. Before you add a listed model to the allowlist, read Merge behavior: a specific model ID narrows its family's wildcard entry. Claude Code also checks each row against the session before it shows the picker:

• Dropped: a row Claude Code can't serve, such as a retired model or a model your organization has no access to
• Grayed out: a row you can't select yet, shown with the reason
• No row survives: Claude Code keeps the built-in lineup, filtered by the allowlist as usual

Claude Code drops a row it can't parse and keeps the rest. See Fix a broken settings file.

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. You supply the rates: Claude Code doesn't read them from your contract or the Claude Console. Requires Claude Code v2.1.242 or later.

• Scope: Managed. Deploy the key through server-managed settings, an MDM policy, a managed-settings.json file, or a policy helper. Claude Code ignores it in user, project, and local settings, in --settings, and on Windows in the user-writable HKCU registry. With server-managed settings, each session reports costs at list price until that session's settings fetch has confirmed the setting. A host application that embeds Claude Code and sets CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST can supply a table of its own through the SDK managedSettings option, which Claude Code uses only when no managed source sets the key and only in Claude Code v2.1.246 or later.
• Type: 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

This example sets contracted rates for Sonnet 4.6 and then reduces every figure, the Sonnet row included, by 15%. Set multiplier alone for a flat discount, overrides alone for per-model rates, or both:

{
  "modelPricing": {
    "multiplier": 0.85,
    "overrides": {
      "claude-sonnet-4-6": {
        "input": 2.4,
        "output": 12,
        "cacheRead": 0.24,
        "cacheWrite": 3
      }
    }
  }
}

For the steps, including how to confirm the rates are in effect, see Report spend at your contracted rates.

<span id="modelpricing-multiplier" />

<span id="modelpricing-overrides" />

Fields for modelPricing

Field	Type	What it does
multiplier	number greater than 0 and at most 1	Scales every cost Claude Code computes, whether or not an overrides row covers it
overrides	map of model ID to a rate object with input, output, cacheRead, and cacheWrite, each 0 to 10000	The USD-per-million-token rates for that model, all four required. cacheWrite covers both five-minute and one-hour cache writes. See Which models a row applies to

Claude Code uses a row's rates exactly as you wrote them, without adding the fast-mode surcharge or the US-only-inference rate. If you also set multiplier, Claude Code applies it on top of the row's rates. Claude Code drops a row with a rate it can't parse, or a multiplier it can't parse, and keeps the rest; see Fix a broken settings file.

Which models a modelPricing row applies to

Claude Code decides which models a row applies to from the row's key:

• A built-in model's ID: a key Claude Code itself uses for a built-in model, whether that key is the model's own ID, such as claude-sonnet-4-6, or its Bedrock, Agent Platform, or Foundry ID. Claude Code applies the row to every dated snapshot ID and provider-specific ID of that model.
• Any other key: a key that isn't a built-in model's ID, such as a gateway model alias. Claude Code applies the row to that one ID only. When a model ID matches one of your keys exactly and also falls under a row keyed by a built-in model's ID, Claude Code uses the exact match.
• A Bedrock application inference profile: once Claude Code has resolved the profile to the model it routes to, through your modelOverrides map or the bedrock:GetInferenceProfile lookup, Claude Code applies that model's row to the profile.

modelSettings

Save an effort level for each model you use. 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. The effortLevel entry lists the sessions where /effort applies to that session only. Requires Claude Code v2.1.251 or later.

Edit the key by hand to change or remove a level you saved.

A model's effortLevel here takes precedence over the top-level effortLevel in the same settings file. Across files, Claude Code resolves each model separately: the highest-precedence settings file that sets either an effortLevel for that model or the top-level effortLevel decides, so an effortLevel in managed settings outranks a level you saved in user settings. Adjust effort level lists what else can override a saved level, such as --effort at launch.

To cap one model's effort rather than set its level, add a maxEffortLevel field to that model's entry. The field requires Claude Code v2.1.267 or later.

• Scope: Any file
• Type: object mapping a model name to an object with an effortLevel field, one of "low", "medium", "high", or "xhigh", a maxEffortLevel field, or both
• Default: unset

Claude Code writes each entry under the model's canonical name, such as claude-opus-5, and matches that model's alias, date-suffixed, [1m], and recognized provider-specific IDs to the same entry.

This example keeps Opus 5 at medium while other models use their own saved or default levels:

{
  "modelSettings": {
    "claude-opus-5": {
      "effortLevel": "medium"
    }
  }
}

Run /effort auto to clear your saved level for the model you're using. Claude Code leaves the other entries and any top-level effortLevel in place.

outputStyle

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. For what that message costs in prompt caching, see Changing output style. Before v2.1.251, the edit applied only after you ran /clear or started a new session.

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

This example selects the built-in Explanatory style, which adds educational insights between tasks:

{
  "outputStyle": "Explanatory"
}

promptCacheTtl

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

• Scope: Any file
• Type: string, one of:
  • "5m": the cache holds for five minutes
  • "1h": the cache holds for an hour
• Default: unset, so each main-conversation request gets its default lifetime
• Per-session overrides: FORCE_PROMPT_CACHING_5M takes precedence over everything else, then CLAUDE_CODE_PROMPT_CACHE_TTL, then this key, and last ENABLE_PROMPT_CACHING_1H

This example keeps the main conversation on the one-hour lifetime and leaves subagents on five minutes:

{
  "promptCacheTtl": "1h",
  "subagentPromptCacheTtl": "5m"
}

For what each lifetime costs, see Cache lifetime.

showThinkingSummaries

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; third-party providers don't redact.

• Scope: Any file
• Type: 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

{
  "showThinkingSummaries": true
}

Redaction changes only what you see, not what the model generates. To reduce thinking spend, lower the budget or disable thinking instead.

subagentPromptCacheTtl

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

• Scope: Any file
• Type: string, one of:
  • "5m": the cache holds for five minutes
  • "1h": the cache holds for an hour
• Default: unset, so each of these requests gets its default lifetime
• Per-session overrides: FORCE_PROMPT_CACHING_5M takes precedence over everything else, then CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL, then this key, then ENABLE_PROMPT_CACHING_1H, which asks for the one-hour lifetime on every request. For where a subagent's own frontmatter value ranks, see Choose the TTL yourself

This example gives subagents and the other requests outside the main conversation the one-hour lifetime:

{
  "subagentPromptCacheTtl": "1h"
}

This key covers the requests promptCacheTtl doesn't, so set both to choose a lifetime for every request Claude Code makes. For how a subagent's cache differs from the main conversation's, see Subagents and the cache.

switchModelsOnFlag

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.

• Scope: Any file. Appears in /config as Switch models when a message is flagged.
• Type: 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: true, switch automatically

{
  "switchModelsOnFlag": false
}

See Ask before switching.

ultracode

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, your model supports xhigh effort, and no effort cap below xhigh applies. Either way, ultracode: true runs the session at xhigh effort, or at the cap when an effort cap is lower. Claude Code reads this key but never writes it: /effort ultracode turns ultracode on for the current session only.

• Scope: Any file
• Type: Boolean
  • true: sessions start at xhigh effort, with ultracode on when dynamic workflows are enabled for you, your model supports xhigh, and no effort cap is below xhigh
  • false: sessions start with ultracode off
• Default: unset, so ultracode is off
• Per-session overrides: /effort ultracode turns ultracode on for one session without this key. So does --effort ultracode, which requires Claude Code v2.1.203 or later

{
  "ultracode": true
}

Ultracode runs the session at xhigh effort and takes precedence over effortLevel and modelSettings entries. If an effort cap below xhigh applies to the model, such as a maxEffortLevel setting, the session runs at the cap instead and ultracode stays off. Claude then doesn't plan workflows on its own, and /effort doesn't offer ultracode. An Agent SDK apply_flag_settings control request also accepts the key.