skip to content

In Claude Code, how do you switch the model mid-session or at launch, and which method changes the default for new sessions?

level: juniorimportance: must knowfreq 30%

answer

  1. picker versus typed argument
  2. Enter versus s in the picker
  3. launch flag lasts one session
  4. the model key in user settings
  5. /status shows what is active

basics

~20 s

Use /model inside a session or claude --model at launch. A typed /model name, or Enter in the picker, switches now and saves the model key in ~/.claude/settings.json; s in the picker, --model and ANTHROPIC_MODEL affect only that session.

solid answer

~40 s

Inside a session, `/model` with no argument opens a picker and `/model sonnet` switches directly. A typed `/model <name>` and `Enter` in the picker both switch immediately **and** save the choice as your default by writing the `model` key in `~/.claude/settings.json`; pressing `s` on a picker row switches for this session only. At launch, `claude --model opus` or `ANTHROPIC_MODEL=opus` sets the model for the session it starts and saves nothing. The value is an alias such as `opus`, `sonnet`, `haiku` or `fable`, or a full model name. The session header and `/status` show which model is active, and a resumed session keeps the model it was using.

go deeper

for a junior

Know the three handles: /model inside a session, claude --model at launch, and the model key in settings. Be able to say which one saves your choice for next time.

for a middle

Explain Enter versus s in the picker, why --model and ANTHROPIC_MODEL leave the saved default alone, and the five-step priority order from /model down to ANTHROPIC_DEFAULT_MODEL.

for a senior

Diagnose a choice that does not stick: an exported ANTHROPIC_MODEL, a project or managed model value, a read-only settings file, or a resumed session that kept its own model.

for a principal

Weigh letting each developer pick models freely against pinning a project default, given that a mid-session switch costs an uncached turn and subagents follow the main model.

## What choosing a model means in Claude Code The main conversation in a Claude Code session runs on one Claude model at a time. You can name it two ways: - **An alias** such as `opus`, `sonnet`, `haiku`, `fable`, `best` or `opusplan` (plus `opus[1m]` and `sonnet[1m]`). Aliases point at the recommended version for your provider and move forward over time. - **A full model name** such as `claude-opus-5-5` on the Anthropic API. On third-party providers the full name is the provider's own form: an inference profile ARN on Amazon Bedrock, a deployment name on Microsoft Foundry, a version name on Google Cloud's Agent Platform. `default` is a special value rather than an alias: it clears any override and returns to the default for your account. ## Switching inside a session with `/model` `/model` is the everyday control, and how you confirm decides whether the choice outlives the session: | What you do | Switches now | Saved as your default | |---|---|---| | `/model`, then `Enter` on a row | yes | yes | | `/model`, then `s` on a row | yes | no | | `/model sonnet` typed directly | yes | yes | | `/model sonnet` inside a `claude -p` run | yes | no | "Saved as your default" means Claude Code writes the `model` key in `~/.claude/settings.json`, so new sessions start on it. There is no restart: once you confirm, the switch applies even while a response is still running. For models that support it, the picker also carries an **effort slider** you move with the left and right arrow keys. A mid-conversation switch is not free. Each model keeps its own prompt cache, so the first request after a switch reads the whole conversation uncached, and Claude Code may ask you to confirm first. Pick the model at the top of a session when you can. ## Choosing at launch - `claude --model opus` sets the model for the session it launches and saves nothing. - `ANTHROPIC_MODEL=opus` does the same for the session it is set for. Exported from a shell profile, it is present at every launch and outranks the saved key, which is a classic reason a `/model` choice seems not to stick. - The `model` key in a settings file is the persistent default; `/model` is simply the usual way that key gets written. - `ANTHROPIC_DEFAULT_MODEL` names a starting model used only when nothing else selects one. To run Opus in one terminal and Sonnet in another at the same time, launch each with its own `--model` rather than switching with `/model`, which would rewrite the shared default. ## The priority order When several sources name a model, Claude Code takes the first that applies: 1. `/model` during the session 2. `--model` at startup 3. `ANTHROPIC_MODEL` 4. the `model` setting 5. `ANTHROPIC_DEFAULT_MODEL` A `model` value in project or managed settings, or an organization default model your admin configured to override user choices, applies again at every launch; your saved choice is still stored, just outranked. How settings files layer against each other is its own topic. ## Checking what is active - The **session header** shows the model and, where it applies, the effort level next to it. - **`/status`** shows the current model along with your account information. - A configured **status line** can display it continuously. - When project or managed settings chose the startup model, the header names the settings file that set it. ## Surprises worth knowing - **Resume keeps its model.** `claude --resume`, `--continue` and the `/resume` picker restore the model the transcript was saved with, so another session's `/model` choice cannot change it. A `--model` flag or `ANTHROPIC_MODEL` on the new launch still wins. - **Subagents follow the switch.** Subagents set to inherit the main conversation's model resolve it when Claude starts them, so switching to Opus before Claude delegates makes that work run on Opus too; a subagent definition with its own model stays put. - **An unwritable settings file.** If `~/.claude/settings.json` is generated by another tool or linked read-only, the switch lasts for the session and the next launch reads the old value. - **Typos surface late.** A value given through `--model`, `ANTHROPIC_MODEL` or the `model` key is not checked up front; a mistyped one fails on the first request.

  • You resume yesterday's session with claude --resume. Which model does it run on?
    The model the transcript was saved with, not your current `model` setting, so another session's `/model` choice cannot silently change it. A `--model` flag or `ANTHROPIC_MODEL` on the new launch still takes precedence. If the restored model has been retired or is excluded by your organization, resolution falls through to the normal order, and on Bedrock, Agent Platform and Foundry the transcript model is not restored at all.
  • You want Opus in one terminal and Sonnet in another at the same time. How?
    Launch each session with its own `--model` flag. A typed `/model` or `Enter` in the picker writes your shared default in `~/.claude/settings.json`, so switching that way in one terminal changes what the next new session starts on. `--model` applies only to the session it launches and leaves the saved default alone.

  • /model only changes the current session and never writes any settings
  • claude --model opus becomes the default for every later session
  • You must restart Claude Code before a model switch takes effect
  • A resumed session always switches to whatever model is saved now
  • Claude Code needs a full model ID; aliases only work in the API