claude code · 7 min read · 2026-07-10

The Claude Code /model command, completely explained

Claude Code gives you at least four different ways to pick a model, and they interact in ways that regularly confuse people: switches that don't stick, defaults that override your choice, and one switch that quietly costs real money. Here's the full map.

All the ways to set a model

1. /model (inside a session)

/model            # interactive picker
/model opus       # switch directly by alias
/model sonnet
/model haiku
/model default    # back to your configured default

This switches the current session on the spot. Your conversation history is preserved; the next reply comes from the new model. Aliases (opus, sonnet, haiku) map to the current recommended version of each tier, so you rarely need full model IDs. You can also pass an exact model ID when you need to pin a specific version.

2. --model (at launch)

claude --model opus
claude --model sonnet -p "fix the failing tests"

Sets the model for that one invocation. This is the right tool for scripted or headless runs (-p) and for launching dedicated per-model sessions, which matters later in this guide.

3. Environment variable

export ANTHROPIC_MODEL="claude-opus-4-8"

Sets the default for every session started from that shell. Useful in CI, dotfiles, and per-project .env setups.

4. settings.json

// ~/.claude/settings.json (user) or .claude/settings.json (project)
{
  "model": "opus"
}

The persistent default. Project settings override user settings, so a repo can pin its own model for everyone who works in it.

What persists and what resets

This table resolves the most common confusion: people run /model haiku, come back the next day, and find themselves on Sonnet again. /model was never a preference; it's a session-local switch. If you want it permanent, put it in settings.json.

Special modes worth knowing

• Hybrid plan/execute: the opusplan setting uses an Opus-tier model while you're in plan mode, then drops to Sonnet for execution. Big-picture reasoning from the expensive model, keystrokes from the cheap one.
• Fast mode: /fast toggles fast mode on supported Opus models (4.8 and 4.7). Same model, much higher output speed, premium pricing. Note that toggling speed also invalidates the prompt cache, like a model switch does.
• Effort: on current models, Claude Code runs high reasoning effort by default. If a session feels like it's overthinking chores, that's a signal the task belongs on a smaller model, not that you need to fight the setting.

The pitfall: /model mid-session is not free

The switch itself is instant, but prompt caches are model-scoped. After a switch, the new model has no cache of your session, so your entire accumulated context is re-processed at full input price plus a cache-write premium. On a long session that's a slow turn and, for API users, real money; for subscription users it burns rate limits. The full breakdown with cost math is here: why switching models mid-session breaks your prompt cache.

The upgrade: stop switching, start shifting

If you find yourself typing /model several times a day, the pattern you actually want is parallel per-model sessions: Opus in one terminal, Haiku in another, each launched once with --model, each keeping its own context and warm cache. Model Shift wraps that pattern in a gear lever: map models to gears, throw the lever, and land in that model's own live tmux tab. No cache rebuilds, no wondering which terminal is which.

Further reading: Haiku vs Sonnet vs Opus: which model for which coding task · Why mid-session switches break the cache