Claude Code Model Config: Aliases, opusplan and Effort

To change the model in Claude Code, type /model <alias> in a session, start it with claude --model <alias>, or set "model" in a settings file. A reasonable setup for many teams is a cheaper default for daily work, opusplan for bigger changes, and a separate effort level that you raise only for hard tasks. This article covers the aliases, the order in which settings win, effort, subagent models, fallbacks and how to lock models down for a team.

Everything below comes from the Claude Code model configuration and subagent documentation. Version numbers are given where the docs state a minimum.

Which model aliases does Claude Code have?

An alias is a short name that resolves to the newest model of that family. You can use it anywhere a model name is accepted.

What an alias points to depends on your provider. On the Anthropic API, opus is Opus 5.5, sonnet is Sonnet 5.5 and haiku is Haiku 5.5. On Amazon Bedrock and Google Cloud's Agent Platform, opus is Opus 5.5 but sonnet and haiku resolve to 4.5 versions. On Microsoft Foundry, opus is Opus 4.6 and sonnet and haiku are 4.5 versions. If you run a mixed estate, check what each alias means on each provider before you write a runbook.

The docs list minimum Claude Code versions for the newest models: v2.1.280 for Opus 5.5, v2.1.284 for Sonnet 5.5, v2.1.293 for Haiku 5.5 and v2.1.257 for Fable 5.1. claude update upgrades an old install.

How do I set the model, and which setting wins?

There are five places, listed from highest priority to lowest:

1. In a session: /model <alias|name>, or /model alone for the picker.
2. At startup: claude --model <alias|name>.
3. The environment variable ANTHROPIC_MODEL.
4. The model field in a settings file.
5. ANTHROPIC_DEFAULT_MODEL, which only sets the default for new sessions.

claude --model opus

/model sonnet

{
  "permissions": { "allow": ["Bash(npm run lint)"] },
  "model": "opus"
}

Two details catch people out. In the picker, Enter switches and saves your choice as the model field in your user settings, while s switches for this session only. Typing /model <name> directly behaves like Enter. And in non-interactive mode (-p), /model applies to the current session only and is never saved (v2.1.205 or later).

ANTHROPIC_DEFAULT_MODEL (v2.1.236 or later) is the weakest. A new session uses it only when --model, ANTHROPIC_MODEL, any model value in a settings file (including a saved /model choice) and any organization default are all absent. It is ignored if set to default, inherit, opusplan or haiku.

Resumed sessions (--resume, --continue, /resume) restore the model saved in the transcript, except on Bedrock, Agent Platform and Foundry, where it is not restored. The --model flag and ANTHROPIC_MODEL override the restored model.

What is opusplan and when should I use it?

opusplan is a hybrid alias. Plan mode runs on opus, and when you approve the plan and execution starts, Claude Code switches to sonnet.

claude --model opusplan

The reasoning is cost. Choosing an approach, finding the files and spotting risks is where a stronger model earns its price. Applying a plan that is already written is often fine on Sonnet. If you already use plan mode, opusplan makes the model split automatic.

Both phases use the context window of their alias. /model opusplan[1m] asks for the 1M window on both phases where they do not already have it; it needs v2.1.265 or later, and on earlier versions you use --model or the model setting. If your admin has restricted models with availableModels and the newest Opus is excluded but an older one is allowed, planning uses the newest permitted Opus.

How does effort work, and how is it different from the model?

Effort is a separate dial that controls how much the model reasons before it acts. The levels are low, medium, high, xhigh and max on Fable 5.1, Fable 5, Opus 5.5, Sonnet 5.5, Haiku 5.5, Opus 5, Sonnet 5, Opus 4.8 and Opus 4.7. Opus 4.6 and Sonnet 4.6 have no xhigh. If a level is not supported, Claude Code uses the highest supported level at or below it, so xhigh runs as high on Opus 4.6. Models not in those lists do not support effort.

Defaults: high on effort-capable models, except Opus 5.5, Sonnet 5.5 and Haiku 5.5, which start at medium, and Opus 4.7, which starts at xhigh.

The resolution order, first match wins:

1. The CLAUDE_CODE_EFFORT_LEVEL environment variable
2. A level picked in the session (/effort, the /model picker)
3. --effort at launch
4. Settings: a saved per-model level or the effortLevel key
5. The model's default

claude --effort xhigh
export CLAUDE_CODE_EFFORT_LEVEL=auto   # send no effort level (unset also works)

/effort            # interactive slider
/effort high       # set directly
/effort auto       # clear the saved level for the active model
/effort status     # show the current level

max is accepted by the environment variable and /effort but not by the effortLevel settings key, which takes only low, medium, high or xhigh. max applies to the current session unless you set it through the environment variable. A top-level effortLevel in user settings does not apply to Opus 5.5, although it does in project, local and managed settings. Skill and subagent frontmatter can also set effort, which applies while that skill or subagent runs; the environment variable still takes precedence over it.

A practical pattern: leave the default alone, raise effort for the one task that needs it, then drop back with /effort auto.

Which model do subagents use?

Subagents that inherit the main conversation's model follow the session's model at the time they start, so a /model switch reaches them. Switch to Opus before delegating and they run on Opus.

To keep a helper cheap, set model in its definition. It accepts sonnet, opus, haiku, fable, a full ID such as claude-opus-5-5, or inherit:

---
name: code-reviewer
description: Reviews code for quality and best practices
model: haiku
---

Since v2.1.251 a subagent's model is resolved in this order:

1. The model parameter on the Agent tool call (aliases only)
2. The model in the subagent's definition
3. The CLAUDE_CODE_SUBAGENT_MODEL environment variable
4. The main conversation's model

Setting CLAUDE_CODE_SUBAGENT_MODEL alone does not change the built-in Explore and Plan subagents. To force one model onto every subagent, also set CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 (v2.1.257 or later). While it is on, the model field in definitions is ignored and Claude cannot pass a model when starting a subagent:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Run /tasks while a subagent is running to see the model, and its effort level if set, on its row (v2.1.242 or later).

How do I pin a model version for CI or a team?

Aliases move. When a newer Sonnet replaces Sonnet 5.5, sonnet follows. For a pipeline that must behave the same next month, pin one of two ways: use the full model name (for example claude-opus-5-5), or set the matching variable so the alias keeps meaning what you chose:

• ANTHROPIC_DEFAULT_OPUS_MODEL
• ANTHROPIC_DEFAULT_SONNET_MODEL
• ANTHROPIC_DEFAULT_HAIKU_MODEL
• ANTHROPIC_DEFAULT_FABLE_MODEL

Pinning has a cost: you also have to notice when a pinned model is retired and move on purpose.

How do I restrict which models people can use?

In managed settings, availableModels is an allow-list. Entries can be a family (sonnet), a version prefix (claude-sonnet-4-5) or a full ID. A prefix also matches later IDs that extend it, so claude-fable-5 permits Fable 5 and 5.1.

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

• The list applies everywhere a user can name a model: /model, --model, ANTHROPIC_MODEL, the model setting, the model restored on resume, subagent and teammate models, skill and command models, and /fast.
• A blocked /model choice is rejected. A blocked --model, ANTHROPIC_MODEL or model value is replaced at startup with a warning, and a blocked subagent runs on a fallback model.
• enforceAvailableModels (v2.1.175 or later) applies the list to the Default option too. Without it, the model setting is only an initial selection and users can still pick Default in /model.
• deniedModels (v2.1.283 or later) blocks listed models even if availableModels permits them, and availableModelsMatch: "exact" makes each ID permit only the version it names. Both are read from managed settings only; set elsewhere, they are ignored with a warning.
• In managed settings, the availableModels list applies alone; user, project and local entries cannot extend it. Earlier versions ignore the newer keys, so also set requiredMinimumVersion to keep them from starting.

What happens when the model is overloaded?

You can give Claude Code a fallback chain:

claude --fallback-model sonnet,haiku

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

The flag overrides the setting, and chains are capped at three models after duplicates are removed. Fallback triggers on overloaded, unavailable or non-retryable server errors. It does not trigger on authentication, billing, rate-limit, request-size or transport errors, so it will not rescue you when you hit a plan limit. The switch lasts for the current turn only, entries outside availableModels are dropped, and fallback applies to subagents from v2.1.247. Because a fallback model may differ from the one you chose, look at the model in use when a run behaves oddly.

Other variables worth knowing

• CLAUDE_CODE_DISABLE_1M_CONTEXT=1 removes the [1m] variants from the picker and treats models with a 1M default as 200K.
• MAX_THINKING_TOKENS=0 turns thinking off on the Anthropic API, except on Opus 5.5, Sonnet 5.5, Haiku 5.5 and the Fable models, where it cannot be turned off.
• CLAUDE_CODE_AUTO_COMPACT_WINDOW sets the auto-compact window in tokens, such as 200000, and takes precedence over /autocompact.

A sensible starting setup

1. Set "model": "sonnet" in user settings for daily work.
2. Use /model opusplan before a large, unclear change.
3. Keep effort at the default and use /effort for one hard task, then /effort auto.
4. In CI, pin with a full model name and set CLAUDE_CODE_EFFORT_LEVEL explicitly.
5. For a team, publish availableModels and enforceAvailableModels in managed settings, with a requiredMinimumVersion.

Conclusion

Model choice in Claude Code is a stack of settings: the session beats the flag, which beats the environment, which beats the file. Learn that order and the effort order, pin versions where repeatability matters, and let opusplan spend the stronger model on planning. Most surprises come from one layer silently overriding another, so check /effort status and the picker before you blame the model.

Atlas, a team of AI engineers built on Claude Code, gives each engineer its own session with a model and effort suited to its role. Fallback chains are coming to Atlas, built in, so they will need no setup. Until then, set one yourself in Claude Code as shown above.