How to Change the Default Model in Claude Code (and the New Model-Switch Hooks in 2.1.251)

Set your claude code default model with /model

The key distinction is between saving a preference and temporarily switching models. By August 29, 2026, /model already supported both workflows.

Version 2.1.153 changed /model so that a selection saves as the default for new sessions. That behavior predates 2.1.251: the August release introduced model-switch hooks, not the ability to remember an interactive model selection.

The version-pinned changelog is the historical reference for this distinction. It records both the persistent selection behavior and the picker action for a temporary switch.

Save a preference for future sessions

Use the model picker:

/model

Select the model you want as your default. The persistence behavior introduced in 2.1.153 means that this selection is saved for new sessions.

This is the clearest historically supported answer to “How do I make my preferred model persist?” It does not require treating a feature introduced in an earlier release as a new capability of 2.1.251.

Switch for the current session only

Press s in the picker to switch models for the current session only. Use this action when the selection should be temporary.

The distinction matters when following older instructions or maintaining custom keyboard shortcuts. The picker’s previous d action became s, and the associated custom keybinding changed from modelPicker:setAsDefault to modelPicker:thisSessionOnly.

For broader model-selection context, see the Claude Code models guide. The release-specific point is simple: an ordinary selection saves a default, while the session-only action gives you a temporary switch.

Configuration files, ANTHROPIC_MODEL, and startup overrides

Model configuration also has settings-file, environment-variable, and startup-flag routes. However, the supplied research establishes a historical limitation: their exact documentation and precedence were not independently verified in a snapshot available by August 29, 2026.

The model configuration documentation and settings documentation describe these routes, but those pages contain subsequent updates. They cannot establish every detail of the behavior at this article’s cutoff.

The following table separates the documented options from what the dated evidence supports.

Which setting wins?

The supplied research reports documentation placing the startup flag above ANTHROPIC_MODEL, and the environment variable above the settings-file model value. It also explicitly marks that ordering as unverified for the publication cutoff.

Consequently, this article does not present that precedence chain as an established August 29 fact. The /model persistence change has a dated changelog anchor; the precise configuration hierarchy does not.

What about a default for one project?

The research identifies user, project, and personal project settings files in the documentation. It does not establish their exact historical wording or model-setting behavior through a pre-cutoff snapshot.

That leaves a narrower answer than a project-configuration tutorial: /model persistence is confirmed, while project-specific file instructions require historical verification. The CLI reference provides a useful companion for command-line configuration, but it does not remove this article’s evidence boundary.

What the model-switch hooks add in 2.1.251

Claude Code 2.1.251 was released on August 28, 2026. Its official release notes introduce two hooks with exact names:

• PreModelSwitch
• PostModelSwitch

The release describes their capabilities as blocking, confirming, or annotating a model switch. These hooks extend the model-selection workflow with controls around the switch.

That is the new feature to distinguish from default persistence. Saving a model preference was already available; the new hook events add ways to participate in a model change.

Can a hook block or request confirmation?

Yes, blocking and confirmation are capabilities explicitly named in the release announcement. Annotation is also listed.

The announcement does not supply the complete input and output schemas, matcher rules, or decision JSON. It therefore supports describing these capabilities, but not publishing a runnable configuration based on the announcement alone.

The same limit applies to details such as which payload fields identify the old and new models or how a confirmation response must be structured. Those details are absent from the supplied pre-cutoff evidence.

What is needed before implementing one?

A working implementation needs more than the event names: it needs the applicable configuration format and supported response contract. The release notes do not provide those pieces.

Use the Claude Code hooks guide for broader hook context. For this release, keep the confirmed scope precise: PreModelSwitch and PostModelSwitch exist, and the announcement describes blocking, confirmation, and annotation capabilities.

Inspect prompt-cache behavior and resume costs

Version 2.1.251 also adds diagnostics that help explain prompt-cache behavior. These additions expose cache activity and estimated rebuild cost; the release does not announce new token prices or numerical cache limits.

Read the new cache line in /cost

The existing command gains a per-session prompt-cache line:

/cost

That line reports four items:

• Hit ratio
• Misses
• Tokens re-cached
• Warm or cold state

Together, these provide a more detailed cache view than a cost figure alone. They distinguish cache hits from misses and expose how many tokens were re-cached.

Status-line scripts also gain a matching prompt_cache object. This makes cache diagnostics available in the status-line interface as well as through /cost.

The announcement does not provide a complete schema for that object. Treat prompt_cache as a confirmed object name, without assuming additional fields beyond the diagnostics described in the release.

Inspect resume information through SessionStart

On resume, SessionStart hooks now receive session staleness and the estimated cost of rebuilding the prompt cache.

This is distinct from the /cost display: the resume addition supplies information to hooks, while the command reports per-session cache diagnostics. Both additions concern cache visibility, but they expose that information through different interfaces.

The release notes do not give the exact payload key names for session staleness or estimated rebuild cost. A hook example that assumes those names would go beyond the available evidence.

Other model defaults and diagnostics changed

Several adjacent changes in 2.1.251 matter when interpreting a “default model.” They concern subagents, account defaults, effort preferences, and gateway spend visibility.

Subagent model precedence

CLAUDE_CODE_SUBAGENT_MODEL now supplies a default. An agent definition’s model: value and an explicitly selected model when spawning an agent take precedence over that variable.

This is a confirmed precedence change in the tagged changelog. It should be kept separate from the unverified historical ordering of the main model’s startup flag, environment variable, and settings-file value.

When examining a subagent’s model selection, account for those explicit choices before treating the environment variable as decisive. The subagents guide provides broader context for agent configuration.

Account defaults and effort preferences

Seat-based Enterprise subscriptions now default to Opus 5, matching other premium plans.

That account-level change is separate from a model preference saved through /model. The release also changes /effort persistence: it now saves a separate default effort level for each model.

The practical distinction is that model selection and effort persistence are separate settings. The new effort behavior remembers a default for each model rather than describing one shared effort default.

Gateway spend visibility

The /usage command gains a Spend limit bar for developers using a Claude apps gateway with spend limits:

/usage

Status-line scripts gain the corresponding rate_limits.spend_limit field. This is a diagnostics addition for that gateway context.

The changelog does not announce a universal dollar cap. The presence of a spend-limit display should therefore not be read as a fixed limit applying to every Claude Code user.

Key takeaways

• /model already saved a default for new sessions before 2.1.251; that behavior dates to 2.1.153.
• Press s in the model picker for a current-session-only switch. Custom keybindings use modelPicker:thisSessionOnly.
• Claude Code 2.1.251 adds PreModelSwitch and PostModelSwitch, with blocking, confirmation, and annotation capabilities described in the release.
• /cost, status-line cache data, and resume-time SessionStart information add visibility into prompt-cache activity and estimated rebuild costs.
• CLAUDE_CODE_SUBAGENT_MODEL supplies a default that explicit agent model choices can override. Exact historical main-model configuration precedence remains unverified in the supplied research.

FAQ

Does /model save the default model in Claude Code?

Yes. Version 2.1.153 changed /model so that a selection saves as the default for new sessions, and that behavior was already present before 2.1.251. Press s in the picker when you want a switch for the current session only.

Which wins: settings.json, ANTHROPIC_MODEL, or --model?

The supplied research reports documentation ordering the startup flag above ANTHROPIC_MODEL, and that variable above the settings-file model value. However, the exact ordering was not independently verified in a pre-August 29, 2026 snapshot, so this article does not establish it as cutoff-specific behavior.

Can a Claude Code model switch hook block a change?

The 2.1.251 release describes PreModelSwitch and PostModelSwitch as supporting blocking, confirmation, and annotation of model switches. It does not provide complete schemas or decision JSON, so the announcement alone is insufficient for a runnable hook implementation.

Where can I see cache misses and estimated rebuild costs?

In 2.1.251, /cost reports per-session cache hit ratio, misses, tokens re-cached, and warm or cold state; status-line scripts gain a matching prompt_cache object. Separately, SessionStart hooks on resume receive session staleness and estimated prompt-cache rebuild cost, although the release notes do not specify those payload key names.