To change the model in Claude Code, type /model in your session. Running it bare opens the model selection menu; passing a name changes the model directly:
/model sonnet
The switch takes effect on your very next prompt and lasts for the rest of the session. That is the whole answer for most people — the rest of this guide covers changing the model at launch, setting a persistent default, and pinning a model per project.
Model Names and Aliases
Claude Code accepts short aliases as well as full model names. The aliases always point at the current model in that family, so they keep working after a new release:
| Alias | What you get |
|---|---|
default | Whatever Claude Code selects for your account — the setting to return to after a temporary change |
fable | The most capable model available, for the hardest reasoning and long-running work |
opus | The flagship coding and agentic model |
sonnet | The balanced everyday model |
haiku | The fastest and cheapest model, for simple, high-volume work |
opusplan | Opus for plan mode, then the resting model once you accept the plan |
opus[1m], sonnet[1m] | The 1M-token context variants of Opus and Sonnet |
Full model names work anywhere an alias does — claude-opus-5, claude-sonnet-5, claude-haiku-4-5, claude-fable-5. Use the alias unless you specifically need a fixed version pinned; the full name is the one that goes stale.
If you pass a name Claude Code does not recognize, it warns you that it will assume a 200K context window for auto-compaction purposes, and the session then fails on the first request with a message that the model may not exist or you may not have access to it. Both are useful signals that you have a typo.
Method 1: Change the Model Mid-Session
This is the common case: you are already working and realize the current model is the wrong tool for the next task.
# Open the interactive picker
/model
# Or set it directly
/model opus
/model haiku
/model claude-sonnet-5
# Return to the account default
/model default
Claude Code confirms the change in the transcript. Your conversation history is preserved — the new model reads everything already in context, so you can escalate to Opus partway through a debugging session without losing your place, then drop back to Sonnet for the routine edits that follow.
The change is scoped to the session. Open a new session and you are back on your configured default.
Switching is also the fastest workaround when a model is unavailable rather than unsuitable. Capacity is tracked per model, so an API Error: 529 overloaded_error on one model often clears immediately after a /model switch to another.
Method 2: Choose the Model at Launch
Use the --model flag when you know up front which model the session needs:
# Start a session on Sonnet
claude --model sonnet
# Start on the most capable model for a hard problem
claude --model fable
# Full model names work too
claude --model claude-opus-5
# Works with -p for one-off, non-interactive runs
claude --model haiku -p "explain what this regex matches: ^\d{3}-\d{4}$"
Like /model, this applies to that session only and leaves your saved default untouched. It pairs well with shell aliases — a claude-cheap alias that runs claude --model haiku makes the low-cost path the easy one.
Method 3: Set a Persistent Default
claude config set model sonnet no longer works. The config subcommand was removed; running it now just prints the top-level help. If you have that command in a setup script or a README, it is silently doing nothing.
The current way is a model key in your settings file:
{
"model": "sonnet"
}
Put that in ~/.claude/settings.json and every new session starts on Sonnet. The value takes the same aliases and full model names as /model.
You can also change it without editing JSON by running /config inside a session and updating the model setting there.
Method 4: Pin a Model Per Project
Settings files cascade, so a project can override your personal default. Claude Code reads three files:
| File | Scope | Commit it? |
|---|---|---|
~/.claude/settings.json | Your personal default, all projects | N/A — outside the repo |
.claude/settings.json | This project, shared with the team | Yes |
.claude/settings.local.json | This project, just you | No — add to .gitignore |
To put a whole repository on Opus regardless of each developer's personal preference:
// .claude/settings.json
{
"model": "opus"
}
This is worth doing for a genuinely gnarly codebase, and worth doing in reverse — pinning haiku — for a docs or content repo where most of the work is mechanical. For a project-specific choice you do not want to impose on teammates, use .claude/settings.local.json instead.
A session started in that directory uses the project's model. A --model flag or an in-session /model still overrides it for that session.
Overrides You Might Not Expect
Several things can change the model without you touching any of the above. If a session is not on the model you expect, check these:
- Subagents. Each agent definition in
.claude/agents/*.mdcarries its ownmodelin its frontmatter, so a delegated task can run on a different model than the session that spawned it.CLAUDE_CODE_SUBAGENT_MODELsets a default for subagents that do not specify one. - Skills and slash commands. These can set a model in their frontmatter, which applies for the duration of that turn and then reverts.
- Environment variables.
ANTHROPIC_MODELsets the model, andANTHROPIC_SMALL_FAST_MODELsets the lightweight model used for background work. Because these live in your shell profile or CI config rather than in the repo, they are the easiest override to forget about. --fallback-model. This flag takes a comma-separated list and switches to the next model when the primary one is overloaded or unavailable, retrying the primary at the start of each user turn. It only works with--print, so it is a batch and CI feature rather than an interactive one.
Choosing the Right Model
The models differ mainly in how much reasoning they do before acting, which shows up as both quality and cost:
- Fable — the hardest problems: long autonomous runs, large migrations, deep research. Highest cost per turn; reach for it when the task has defeated something cheaper.
- Opus — complex multi-file refactoring, architecture decisions, subtle debugging, security-sensitive code. The default choice for work where being wrong is expensive.
- Sonnet — most day-to-day coding: implementations, bug fixes, code review, tests, documentation. Close to Opus on ordinary tasks at meaningfully lower cost.
- Haiku — quick questions, formatting, mechanical search-and-replace, and any high-volume work where speed matters more than depth.
A practical pattern is to default to Sonnet, keep opusplan in mind when a task needs careful planning but routine execution, and escalate to Opus or Fable only when a task actually stalls. Model choice is a per-task decision, not a per-person one — /model exists precisely because the right answer changes several times a day.
Separately from model choice, fast mode (toggled with /fast) runs Opus with faster output rather than substituting a smaller model. It is a latency setting, not a capability downgrade.
Verifying What You Are Running
Run /model with no argument at any point — the picker shows the currently selected model. If it is not what you expected, work down the override list above in order: session flag, in-session change, project settings, personal settings, environment variables.
For a broader look at where Claude Code reads configuration from, see where configuration files are stored.
Next Steps
- Learn about rate limits and quota management to get more out of your subscription
- Explore working with large codebases for efficient token usage
- Configure CLAUDE.md with project-specific instructions
- Read about using multiple AI tools when Claude quota is exhausted