Model Settings

These keys choose the model Claude Code uses and how hard it thinks. Administrators also use them to allow or block models. Several keys have a matching environment variable that wins over the key.

Use /model or edit a settings file. fastMode, alwaysThinkingEnabled, and enforceAvailableModels switch features.

Keys

Source: Settings Reference for rows marked Documented. For rows marked Undocumented, Source: the program (its bundled settings schema). Where to Set It tells you which files may set the key. See Settings Files and Scopes.

Key	Status	Type	Default	What It Does	Where to Set It
advisorModel	Documented	string	-	Pick which model answers when Claude asks the advisor tool.	Any settings file
alwaysThinkingEnabled	Documented	boolean	-	Turn extended thinking off for every session.	Any settings file
availableModels	Documented	array of string	-	Restrict which models people can pick. Accepts family aliases (opus), version prefixes (opus-4-5), and full model IDs. An empty array leaves only the default model.	Any settings file
🔒 availableModelsMatch	Documented	enum: prefix, exact	-	Make each availableModels model ID entry permit only the version it names. prefix is the default. exact stops an entry from allowing other versions.	Managed settings only
🔒 deniedModels	Documented	array of string	-	Block specific models, even ones availableModels permits. A family alias blocks the family. Claude Code does not start if no allowed model is left for Default.	Managed settings only
effortLevel	Documented	enum: low, medium, high, xhigh	-	Set a default effort level for models without a saved level of their own. Saved for supported models.	Any settings file
enforceAvailableModels	Documented	boolean	-	Keep the /model Default choice inside your availableModels allowlist. Has no effect when availableModels is unset or empty.	Any settings file
fallbackModel	Documented	array of string	-	Name backup models for when the primary is overloaded. Models are tried in order. The --fallback-model flag wins. default expands to the default model.	Any settings file
fastMode	Documented	boolean	-	Turn fast mode on for sessions where it's available.	Any settings file
fastModePerSessionOptIn	Documented	boolean	-	Require people to turn fast mode on each session. Each session starts with fast mode off.	Any settings file
maxEffortLevel	Documented	string	-	Cap the effort level for every model or per model, on every provider. The lowest value across files wins. An effort set through CLAUDE_CODE_EXTRA_BODY is not clamped.	Any settings file
model	Documented	string	-	Change the model Claude Code starts with.	Any settings file
modelOverrides	Documented	object	-	Map model IDs to your provider's IDs, such as Bedrock ARNs. Usually set in managed settings.	Any settings file
modelPicker	Documented	object	-	Choose which models the /model picker lists, in your own order and with your own labels. Read only from managed, --settings, and user settings. The first source that sets it wins whole.	User or managed settings
🔒 modelPricing	Documented	object	-	Report spend at your organization's contracted rates instead of list price. overrides maps a model ID to USD rates per million tokens. The figures stay estimates.	Managed settings only
modelSettings	Documented	❓	-	Keep a saved effort level or auto-compact window per model, or cap one model's effort.	Any settings file
promptCacheTtl	Documented	string	-	Choose the prompt cache lifetime for the main conversation. 5m or 1h. Unset is 1 hour on a subscription and 5 minutes on an API key or cloud provider. CLAUDE_CODE_PROMPT_CACHE_TTL wins.	Any settings file
showThinkingSummaries	Documented	boolean	-	See summaries of Claude's thinking instead of a collapsed stub.	Any settings file
subagentPromptCacheTtl	Documented	string	-	Choose the prompt cache lifetime for subagent requests. 5m or 1h. Unset is 5 minutes unless ENABLE_PROMPT_CACHING_1H=1. CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL wins.	Any settings file
switchModelsOnFlag	Documented	boolean	-	Switch models automatically or pause when a safety classifier flags a request.	Any settings file
totalTokensReminder	Undocumented	enum: off, infinite, fixed, countdown, padded-countdown	padded-countdown	Add a "tokens left" reminder to the system prompt and after each tool result. Modes: off, infinite, fixed, countdown, padded-countdown. CLAUDE_CODE_TOTAL_TOKENS_REMINDER wins.	Settings files
totalTokensReminderAfterUserTurn	Undocumented	boolean	On	Repeat the "tokens left" reminder after each user prompt. When off, it shows only in the system prompt and after tool results. CLAUDE_CODE_TOTAL_TOKENS_REMINDER_AFTER_USER_TURN wins.	Settings files
totalTokensReminderBudget	Undocumented	integer	15000000	Set the starting token budget of padded-countdown. CLAUDE_CODE_TOTAL_TOKENS_REMINDER_BUDGET wins.	Settings files

Example

Opus at High Effort with a Fallback

This file starts each session on Opus at high effort. If Opus is overloaded, Claude Code tries Sonnet. The main conversation keeps its prompt cache for one hour.

~/.claude/settings.json

{
  "model": "opus",
  "effortLevel": "high",
  "fallbackModel": ["sonnet"],
  "promptCacheTtl": "1h"
}

Related Pages

• Settings Files and Scopes explains the scopes, precedence, and managed settings.
• Settings Reference is the official page for each key.
• Model and Effort Variables lists the variables that win over these keys.
• Models explains how model, effort, and retry choices are made.
• Models and Providers lists the model catalog and aliases.
• Model Configuration explains aliases and effort in the official docs.