# Claude Code Model Config: Aliases, opusplan and Effort

> How to choose the model in Claude Code: aliases, opusplan, effort levels, fallback chains, subagent models and the order in which settings win.

Canonical: https://bridge-terminal.com/atlas/blog/claude-code-model-aliases-opusplan-effort/
Last updated: 2026-11-02

Published 2 November 2026 · Technical · How-to · 8 min read

## The short version

- Claude Code picks its model from a fixed order: /model in the session beats --model, which beats ANTHROPIC_MODEL, which beats the model key in settings.
- opusplan plans with Opus and executes with Sonnet, so the strongest model is used only for planning.
- Effort is a separate dial from the model, and the CLAUDE_CODE_EFFORT_LEVEL environment variable overrides every other way of setting it.
- Use full model names or the ANTHROPIC_DEFAULT_*_MODEL variables when a pipeline needs a pinned version, because aliases move to the latest release.
- Managed settings can allow-list or deny models, and a fallback chain of up to three models covers overload but not rate limits.

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.

| Alias | What it does |
|---|---|
| `default` | Clears any override and returns to the default for your account |
| `best` | Same model as `fable` where Fable is available, otherwise the same as `opus` |
| `fable` | Fable, for the hardest and longest-running tasks |
| `opus` | Latest Opus, for complex reasoning |
| `sonnet` | Latest Sonnet, for daily coding |
| `haiku` | Fast, efficient Haiku, for simple tasks |
| `sonnet[1m]`, `opus[1m]` | The same models with a 1M-token context window; no effect where the model already has 1M natively |
| `opusplan` | Opus in plan mode, then Sonnet for execution |

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.

```bash
claude --model opus
```

```text
/model sonnet
```

```json
{
  "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`.

```bash
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

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

```text
/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`:

```yaml
---
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:

```json
{
  "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.

```json
{
  "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:

```bash
claude --fallback-model sonnet,haiku
```

```json
{
  "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.

## Questions people ask

### How do I change the model in Claude Code?

Type /model followed by an alias such as sonnet or opus in a session, start with claude --model <alias>, or set the model field in a settings file. The session choice beats the flag, which beats ANTHROPIC_MODEL, which beats the settings file.

### What does opusplan do in Claude Code?

It uses Opus while you are in plan mode and switches to Sonnet when execution starts. You set it with /model opusplan or claude --model opusplan.

### What is the difference between model and effort in Claude Code?

The model is which Claude answers; effort is how much it reasons, from low to max on models that support it. They are set separately, and CLAUDE_CODE_EFFORT_LEVEL overrides every other way of setting effort.

### Does the fallback model help when I hit a usage limit?

No. Fallback applies on overload, unavailability or non-retryable server errors, not on authentication, billing, rate-limit or request-size errors. Chains are capped at three models.

### How do I stop a team from using certain models?

Set availableModels in managed settings, add enforceAvailableModels to cover the Default option, and use deniedModels to block specific versions. Add requiredMinimumVersion so older installs that ignore the newer keys cannot start.

## About Atlas: Model and effort per role, tuned for you

Atlas runs each engineer as its own Claude Code session, with the model and effort tuned to that engineer's role. Fallback chains for overloaded models are coming to Atlas, built in, so they need no setup. Until then, set one yourself in Claude Code as shown above. — https://bridge-terminal.com/atlas/

## Sources

- [Claude Code model configuration](https://code.claude.com/docs/en/model-config)
- [Claude Code subagents](https://code.claude.com/docs/en/sub-agents)

_Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._

## Related

- [Claude Code Ultrathink Now Raises Effort to xhigh](https://bridge-terminal.com/atlas/blog/claude-code-ultrathink-xhigh-effort-subagents/)
- [Claude Code Rules: Path-Scoped Instructions](https://bridge-terminal.com/atlas/blog/claude-code-rules-path-scoped-instructions/)
- [Claude Code Status Line: Show Context, Cost and Limits](https://bridge-terminal.com/atlas/blog/claude-code-status-line-context-cost-limits/)