Models and Effort

These variables choose which model Claude Code uses and how hard it thinks. They also pin what the aliases opus, sonnet, haiku, and fable mean, add your own entry to the /model picker, and limit output size. Use them when you want the same model in every session or when a gateway needs custom model IDs.

This page lists 84 variables. A --model flag or /model overrides ANTHROPIC_MODEL. CLAUDE_CODE_EFFORT_LEVEL overrides --effort and /effort.

Example

~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_MODEL": "opus",
    "CLAUDE_CODE_EFFORT_LEVEL": "high"
  }
}

Every new session starts on the opus alias with high effort.

Variables

The table is sorted by name. See Environment Variables for what each column and badge means.

Variable	Status	What it does	Values and default	Notes
`ANTHROPIC_BETAS`	Documented	Adds extra `anthropic-beta` values to API requests.	Text. Ignored with a debug message when the org policy turns off experimental betas	All sessions. Not set from project `env` before trust
`ANTHROPIC_CUSTOM_MODEL_OPTION`	Documented	Adds this model ID as an extra entry in the `/model` picker. Claude Code also accepts it as a valid model.	Text. The entry does not appear twice if the ID is already listed	Model picker, all. Project `env` can set it before trust
`ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION`	Documented	Sets the picker description for the custom model entry.	Text. Default is `Custom model (<id>)`	Model picker, all. Project `env` can set it before trust
`ANTHROPIC_CUSTOM_MODEL_OPTION_NAME`	Documented	Sets the picker label for the custom model entry.	Text. Without it, the label is the known model name or the model ID	Model picker, all. Project `env` can set it before trust
`ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES`	Documented	Lists the capabilities of the custom model, such as `effort,thinking`.	A comma-separated list. A table pairs each model var with its capabilities var and reads it by name	Model picker and capability checks. Project `env` can set it before trust
`ANTHROPIC_DEFAULT_FABLE_MODEL`	Documented	Sets the model ID that the `fable` alias resolves to. A set value also makes Fable available.	Text. The picker row for `fable` shows only when the model picker check passes	All sessions. Project `env` can set it before trust
`ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION`	Documented	Sets the picker description of the pinned Fable model.	Text, starts by default	Model picker, all. Project `env` can set it before trust
`ANTHROPIC_DEFAULT_FABLE_MODEL_NAME`	Documented	Sets the picker name of the pinned Fable model.	Text. Used only when `ANTHROPIC_DEFAULT_FABLE_MODEL` is set	Model picker, all. Project `env` can set it before trust
`ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES`	Documented	Lists the capabilities of the pinned Fable model, such as `effort,thinking`.	A comma-separated list. A table pairs each model var with its capabilities var and reads it by name	Model capability checks. Project `env` can set it before trust
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	Documented	Sets the model ID that the `haiku` alias resolves to. It also marks the small fast model as set.	Text	All sessions. Project `env` can set it before trust
`ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION`	Documented	Sets the picker description of the pinned Haiku model.	Text, starts by default	Model picker, all. Project `env` can set it before trust
`ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME`	Documented	Sets the picker name of the pinned Haiku model.	Text. Used only when `ANTHROPIC_DEFAULT_HAIKU_MODEL` is set	Model picker, all. Project `env` can set it before trust
`ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES`	Documented	Lists the capabilities of the pinned Haiku model, such as `effort,thinking`.	A comma-separated list. A table pairs each model var with its capabilities var and reads it by name	Model capability checks. Project `env` can set it before trust
`ANTHROPIC_DEFAULT_MODEL`	Documented	Sets the model that new sessions start on.	Text. Trimmed. `default` and `inherit` are handled as special values	All sessions. Project `env` can set it before trust
`ANTHROPIC_DEFAULT_OPUS_MODEL`	Documented	Sets the model ID that the `opus` alias resolves to.	Text. Claude Code compares it with a seeded value (`CLAUDE_CODE_3P_SEEDED_OPUS_DEFAULT`) to see if it set the value itself	All sessions. Project `env` can set it before trust
`ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION`	Documented	Sets the picker description of the pinned Opus model.	Text, starts by default. Claude Code sets it for a Bedrock cross-tier fallback	Model picker, all. Project `env` can set it before trust
`ANTHROPIC_DEFAULT_OPUS_MODEL_NAME`	Documented	Sets the picker name of the pinned Opus model.	Text	Model picker, all. Project `env` can set it before trust
`ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES`	Documented	Lists the capabilities of the pinned Opus model, such as `effort,thinking`.	A comma-separated list. A table pairs each model var with its capabilities var and reads it by name	Model capability checks. Project `env` can set it before trust
`ANTHROPIC_DEFAULT_SONNET_MODEL`	Documented	Sets the model ID that the `sonnet` alias resolves to.	Text. Claude Code compares it with a seeded value (`CLAUDE_CODE_3P_SEEDED_SONNET_DEFAULT`) to see if it set the value itself	All sessions. Project `env` can set it before trust
`ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION`	Documented	Sets the picker description of the pinned Sonnet model.	Text, starts by default	Model picker, all. Project `env` can set it before trust
`ANTHROPIC_DEFAULT_SONNET_MODEL_NAME`	Documented	Sets the picker name of the pinned Sonnet model.	Text. Used only when `ANTHROPIC_DEFAULT_SONNET_MODEL` is set	Model picker, all. Project `env` can set it before trust
`ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES`	Documented	Lists the capabilities of the pinned Sonnet model, such as `effort,thinking`.	A comma-separated list. A table pairs each model var with its capabilities var and reads it by name	Model capability checks. Project `env` can set it before trust
`ANTHROPIC_MODEL`	Documented	Selects the model for the session. It beats the `model` setting.	Text. An explicit CLI or session choice still wins over it	All sessions. Project `env` can set it before trust
⛔ `ANTHROPIC_SMALL_FAST_MODEL`	Documented	Deprecated. Sets the model for background tasks. Use `ANTHROPIC_DEFAULT_HAIKU_MODEL` instead.	Text. A set value counts as a small-fast-model override and changes fallback logic	All sessions. Project `env` can set it before trust
`CLAUDE_CODE_3P_PROBE_WROTE_HAIKU_DEFAULT`	Undocumented	Records the Haiku default that the third-party model probe wrote. It lets Claude Code tell that value from a user-set one.	Text. Claude Code sets it. Code compares it with `ANTHROPIC_DEFAULT_HAIKU_MODEL`	Third-party providers. Not set from project `env` before trust
`CLAUDE_CODE_3P_PROBE_WROTE_OPUS_DEFAULT`	Undocumented	Records the Opus default that the third-party model probe wrote. It lets Claude Code tell that value from a user-set one.	Text. Claude Code sets it. Code compares it with `ANTHROPIC_DEFAULT_OPUS_MODEL`	Third-party providers. Not set from project `env` before trust
`CLAUDE_CODE_3P_PROBE_WROTE_SONNET_DEFAULT`	Undocumented	Records the Sonnet default that the third-party model probe wrote. It lets Claude Code tell that value from a user-set one.	Text. Claude Code sets it. Code compares it with `ANTHROPIC_DEFAULT_SONNET_MODEL`	Third-party providers. Not set from project `env` before trust
`CLAUDE_CODE_3P_SEEDED_OPUS_DEFAULT`	Undocumented	Records the Opus default that Claude Code seeded into `ANTHROPIC_DEFAULT_OPUS_MODEL`.	Text. Claude Code sets it. Code compares it with `ANTHROPIC_DEFAULT_OPUS_MODEL` to see who set the value	Third-party providers. Not set from project `env` before trust
`CLAUDE_CODE_3P_SEEDED_SONNET_DEFAULT`	Undocumented	Records the Sonnet default that Claude Code seeded into `ANTHROPIC_DEFAULT_SONNET_MODEL`.	Text. Claude Code sets it. Code compares it with `ANTHROPIC_DEFAULT_SONNET_MODEL` to see who set the value	Third-party providers. Not set from project `env` before trust
`CLAUDE_CODE_ACT_DONT_REDERIVE`	Undocumented Gated	Turns on the system prompt rule that says to act once enough is known and not to re-derive settled facts.	On, off, or unset, `true` by default. Overrides a feature flag, default `true`. Claude Code logs the source as `env` or `growthbook`	Main prompt. gated by a feature flag flag when unset. Not set from project `env` before trust
`CLAUDE_CODE_ALLOW_OTHER_MODELS`	Undocumented	With `--client-data-url`, starts on a model that has no entry in the client data document. Claude Code then applies no per-model client data.	On or off. Same as the `--allow-other-models` flag per its help text	Sessions started with `--client-data-url`. Not set from project `env` before trust
`CLAUDE_CODE_ALWAYS_ENABLE_EFFORT`	Documented	Sends the effort parameter on every request even for unknown model ids.	On or off. Models that reject effort stay excluded: `claude-3-*`, Opus 4.0 and 4.1, Sonnet 4.0 and 4.5, Haiku 4.5	API requests with custom model ids. Project `env` can set it before trust
`CLAUDE_CODE_AMBER_ASTROLABE`	Undocumented	It overrides a per-model prompt flag. A Probes run saw an "operating autonomously" block added to the system prompt.	On or off. A truthy value is passed as an override. A falsy value passes `undefined`	Model prompt selection. Not set from project `env` before trust
`CLAUDE_CODE_APPEND_PROMPT_HEAD`	Undocumented	Names the head of the appended system prompt. Claude Code checks it against a hash and the prompt start, then splits base and append text.	Text. Claude Code reads it once and unsets it. Telemetry records the outcome in a feature flag	SDK hosts with appended prompts. Not set from project `env` before trust
`CLAUDE_CODE_AUTO_MODE_MODEL`	Undocumented	Sets the model for the auto mode classifier. A server-configured classifier model wins and Claude Code logs a warning.	Text. Used when no server model is set	Auto mode
`CLAUDE_CODE_AUTO_MODE_TEMPERATURE`	Undocumented	Sets the sampling temperature of the auto mode classifier requests.	A number, `1` by default	Auto mode
`CLAUDE_CODE_BISON_CAIRN`	Undocumented	Forces the `delivering_work_max` system prompt section on or off.	On, off, or unset. Unset leaves the choice to a model check and the `bison_cairn` rollout	All sessions
`CLAUDE_CODE_BREEZY_HORIZON`	Undocumented	Maps a model to another model id for the `breezy_horizon` experiment. A falsy value turns the mapping off.	Text. Claude Code logs a warning and ignores a value that is not a model id	All sessions
`CLAUDE_CODE_CLIENT_DATA_URL`	Undocumented	Gives the URL of a signed configuration document with per-model client data. Same as `--client-data-url`, but the URL stays out of the process list.	Text. It must be an `https` URL without credentials or a port. Claude Code exits if it cannot load the document	All sessions
`CLAUDE_CODE_COZY_TEAPOT`	Undocumented Gated	Overrides the bash-first steer variant. The feature flag otherwise picks it, with `strict` as the fallback.	Other values are ignored	All sessions, experiment override
`CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`	Documented	Falls back to fixed thinking budgets on Opus 4.6 and Sonnet 4.6.	On or off	All sessions. Project `env` can set it before trust
`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`	Documented	Strips pre-release `anthropic-beta` headers and beta fields from API requests.	On or off. Also passed on to child auto mode classifier processes	First party, AWS and Foundry paths. Project `env` can set it before trust
`CLAUDE_CODE_DISABLE_EXPLORE_INHERIT_CAP`	Undocumented	Makes the built-in Explore agent inherit the parent model instead of a cap at the `opus` tier.	On or off, off by default. Read when Claude Code resolves the Explore agent model	Explore agent
`CLAUDE_CODE_DISABLE_FAST_MODE`	Documented	Turns off fast mode.	On or off. Code allows fast mode only for the first-party provider and when this is off	First-party API. Project `env` can set it before trust
`CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP`	Documented	Stops the remap of Opus 4 and Opus 4.1 ids to the current Opus.	On or off. The remap list holds `claude-opus-4-20250514`, `claude-opus-4-1-20250805`, `claude-opus-4-0` and `claude-opus-4-1`	Anthropic API. Project `env` can set it before trust
`CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK`	Documented	Stops the switch to an older model when the account loses access to the session model.	On or off. `CLAUDE_CODE_NO_MODEL_FALLBACK` does the same	Bedrock and Vertex per docs
`CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK`	Documented	Turns off the automatic model switch when a safety classifier flags a request.	On or off. Also gates the `switchModelsOnFlag` setting	All sessions
`CLAUDE_CODE_DISABLE_REFUSAL_RETRY`	Undocumented	Makes a refusal retry check return false. The check sits next to code about responses stopped by a safety classifier.	On or off, off by default	All sessions
`CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS`	Documented	Stops Claude Code from sending `output_config.format` and its `anthropic-beta` value.	On or off. Passed on to child auto mode classifier processes	Providers that support structured outputs
`CLAUDE_CODE_DISABLE_THINKING`	Documented	Omits the `thinking` parameter from API requests.	On or off, may by default. Docs: models that think by default may still think	All sessions. Project `env` can set it before trust
`CLAUDE_CODE_EFFORT_LEVEL`	Documented	Sets the effort level for the session and wins over `/effort` and settings.	Text. Trimmed `str`. `unset` and `auto` (any case) give the model default	All sessions. Project `env` can set it before trust
🧪 `CLAUDE_CODE_ENABLE_EXPERIMENTAL_ADVISOR_TOOL`	Undocumented Gated	Forces the server-side advisor tool on, and lets a base model with no advisor rank use it.	On or off, off by default. Still blocked by `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` and by provider checks	First-party and eligible providers
`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`	Documented	Fills the `/model` picker from the gateway `/v1/models` endpoint.	On or off, off by default. Needs the `firstParty` provider and a non-Anthropic `ANTHROPIC_BASE_URL`. The `gateway` provider also checks it at bootstrap	Gateway setups
`CLAUDE_CODE_FORCE_MID_CONVERSATION_SYSTEM`	Undocumented	Forces mid-conversation system messages on for every model.	On or off, off by default. Skips the model checks and the flags for system turns	API requests
`CLAUDE_CODE_MAX_OUTPUT_TOKENS`	Documented	Sets the maximum output tokens for most requests, clamped to the model cap.	A number. The default depends on the model. Claude Code lowers a value above the model cap to the cap	All sessions. Project `env` can set it before trust
`CLAUDE_CODE_MESSAGES_PROMPT_CACHE_TTL`	Undocumented	Forces the prompt cache TTL to `5m` for the requests that use this helper.	`enum` with the single value `5m`. Any other value leaves the chosen TTL as is	All sessions. Project `env` can set it before trust
`CLAUDE_CODE_MODEL_CAPABILITIES`	Undocumented	Overrides model capabilities. Syntax is `pattern=cap1,-cap2` entries split on a semicolon, and a leading `-` turns a capability off.	Text. A pattern ending in `*` matches by prefix. An entry with no `=` applies to all models	All sessions
`CLAUDE_CODE_MODEL_CATALOG`	Undocumented	Turns off the served model catalog when set to a false value.	Text. The catalog is also off for bare mode, essential-traffic-only, a unix socket, non-first-party, or policy	First-party logins
`CLAUDE_CODE_MODEL_CATALOG_URL`	Undocumented	Sets a custom URL for the published model catalog. A `file` URL is treated as a local file.	Text. Used when the managed config has no `url`. A bad URL turns the published path off	All sessions
`CLAUDE_CODE_NO_MODEL_FALLBACK`	Undocumented	Forbids model substitution. A fallback attempt then fails with a message that names this variable.	On or off. Works like `CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK` for the availability chain	All sessions
`CLAUDE_CODE_PROMPT_CACHE_TTL`	Documented	Sets the prompt cache TTL of the main conversation.	`enum` of `5m` or `1h`. `FORCE_PROMPT_CACHING_5M` wins over it	Main thread. Project `env` can set it before trust
`CLAUDE_CODE_REFUSAL_FALLBACK_CATCH_ALL`	Undocumented	Lets a refusal retry on the fallback model even when its category has no fallback map entry.	On, off, or unset, comes by default. A false value turns it off	Sessions with a fallback model
`CLAUDE_CODE_RUSTLING_PIXEL`	Undocumented Gated	Picks how Claude Code keeps thinking blocks that came from another model. Values are `all`, `upgrade`, or `none`.	Text, `all` by default. An invalid value logs a warning and uses `upgrade`. When unset, a server setting or the flag default `all` decides	Model calls that carry foreign thinking blocks. Needs an eligible account or provider
`CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT`	Documented Gated	Chooses the full or the shorter system prompt. `1` forces the short one. `0`, `false`, `no`, or `off` force the full one.	Unset lets the model, a feature flag, and a server config decide	All models. Docs list per-model defaults
`CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS`	Documented	Treats a failed fast mode availability check as available. A response of "disabled by your organization" still counts.	On or off. It applies only to network-type failure reasons	Fast mode on the first-party API
`CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK`	Documented	Skips the client-side fast mode availability check, for proxies that intercept the check instead of refusing it.	On or off. It has no effect in one account mode where the check always runs. The API still rejects requests if the org turns fast mode off	Fast mode on the first-party API
`CLAUDE_CODE_SNAPPY_PELICAN`	Undocumented Gated	Forces a feature flag behavior on or off. When it is off, relative `effort` values `lower` and `higher` are dropped from the input.	On, off, or unset. It is ignored when the subagent model is forced or not set to inherit	Subagent calls. gated by a feature flag
`CLAUDE_CODE_SUBAGENT_MODEL`	Documented	Sets the default model for subagents, teammates, and workflow agents with no model set another way.	Text. The values `inherit` and unset mean the parent model. Docs match	Subagents. Project `env` can set it before trust
`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`	Documented	Forces one model onto all subagents, teammates, and workflow agents. The `model` parameter is then ignored.	On or off. The coordinator prompt also reads it	Subagents, teammates, workflows
`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`	Documented	Sets the prompt cache TTL to `5m` or `1h` for requests outside the main conversation.	One of a fixed set of values. Enum `5m` or `1h`. It beats the `subagentPromptCacheTtl` setting	Subagents, workflows, background work. Project `env` can set it before trust
`CLAUDE_CODE_THISTLE_GREBE`	Undocumented Gated	Picks a prompt steer variant. Env wins over client data, then flag, then a per-model default.	Text. Accepts `default`, `no_nudges`, or `counter_steer`. Other values are ignored	All providers
`CLAUDE_CODE_TURN_UPDATES`	Undocumented	Forces the `turn_updates` system prompt section on or off. It asks the model to restate key mid-turn findings in its final message.	On, off, or unset. Without it, the prompt logic decides	All sessions
`CLAUDE_CODE_WILLOW_TERN`	Undocumented Gated	Forces a `willow_tern` prompt switch on. The code names it a writing override. Otherwise client data, the model, or a flag decides.	On or off. Only `true` forces it. A non-boolean client data value is ignored	Model-dependent
`CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL`	Undocumented	Sets the model for workflow subagents. The value `inherit` means no override.	Text. Ignored when `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` is on and the value came from project settings. Allowed in project `env`	Workflows
`CLAUDE_EFFORT`	Documented	Holds the effort level of the session for Bash subprocesses and hook commands.	Set by Claude Code when the model supports effort. Also the skill token `${CLAUDE_EFFORT}`	Bash tool and hooks
`DISABLE_INTERLEAVED_THINKING`	Documented	Stops sending the interleaved-thinking beta header.	On or off	-
`DISABLE_PROMPT_CACHING_OPUS`	Documented	Turns off prompt caching when the request model is the default Opus model.	On or off, Opus by default. Compared with the default Opus model id on each request	All sessions. Project `env` can set it before trust
`DISABLE_PROMPT_CACHING_SONNET`	Documented	Turns off prompt caching when the request model is the default Sonnet model.	On or off, Sonnet by default. Compared with the default Sonnet model id on each request	All sessions. Project `env` can set it before trust
`ENABLE_PROMPT_CACHING_1H`	Documented	Asks for the 1-hour prompt cache TTL in place of 5 minutes.	On or off. Lower priority than `FORCE_PROMPT_CACHING_5M`, the TTL env vars, settings, and agent frontmatter	All sessions. Project `env` can set it before trust
⛔ `ENABLE_PROMPT_CACHING_1H_BEDROCK`	Documented	Deprecated alias of `ENABLE_PROMPT_CACHING_1H` for Bedrock. It still asks for the 1-hour TTL.	On or off. Works only when the provider is `bedrock`	Bedrock. Project `env` can set it before trust
`FALLBACK_FOR_ALL_PRIMARY_MODELS`	Documented	Stops retrying after repeated overload errors for every model when no fallback model is set.	Text. Any non-empty string counts, so `0` still enables it	API requests. Project `env` can set it before trust
`FORCE_PROMPT_CACHING_5M`	Documented	Forces the 5-minute prompt cache TTL.	On or off. Checked first, ahead of the TTL env vars and `ENABLE_PROMPT_CACHING_1H`	All sessions. Project `env` can set it before trust
`MAX_STRUCTURED_OUTPUT_RETRIES`	Documented	Sets how many tries a structured output (`--json-schema` or workflow subagent) gets before the run fails.	A number	-
`MAX_THINKING_TOKENS`	Documented	Sets a fixed extended-thinking token budget. `0` turns thinking off.	A number	-

How It Works

Claude Code picks the model in a fixed order: the --model flag or /model first, then ANTHROPIC_MODEL, then the model setting, then ANTHROPIC_DEFAULT_MODEL. The ANTHROPIC_DEFAULT_*_MODEL variables change what an alias points to. They matter most on Bedrock, Vertex, Foundry, or a gateway, where model IDs differ. The _NAME, _DESCRIPTION, and _SUPPORTED_CAPABILITIES variants only change how the model shows in the picker and which features Claude Code allows for it.

Environment Variables: how Claude Code reads variables and which value wins.
Models and Providers
Cloud Providers: provider switches that also change model IDs.
Undocumented Items: every item that only the program shows.

Source: the program (variable names found in the 2.1.304 binary) and the Environment Variables page of the official docs.

Example​

Variables​

How It Works​

Related Pages​

Example

Variables

How It Works

Related Pages