Table of contents

You want a smart model to do the planning, and a faster, cheaper model to do the actual coding. Claude Code has a setting that does exactly that automatically: opusplan.

Short answer: opusplan is a model setting that runs Opus while you are in plan mode and Sonnet the rest of the time. You use it by typing /model opusplan or by putting it in model in settings.json. However, it does not appear in the /model list, so you won't find it unless you know the name. And because the model switches every time you enter or leave plan mode, keep in mind that each switch re-reads the whole conversation without the cache.

Based on the official documentation, the Claude Code CHANGELOG and GitHub issues as of September 15, 2026, this article covers how to set it up, how a session flows, why it isn't listed, what to watch for with pricing and caching, and how it differs from similar mechanisms (the advisor tool and subagents).

With opusplan, the model switches as you enter and leave plan mode

On the Anthropic API. What opus and sonnet point to depends on the provider

In plan mode

Opus 5

Explores the code and writes a plan without editing

Approve the plan →

Everything else (implementation)

Sonnet 5

Edits files and runs commands following the plan

Source: Claude Code documentation, Model configuration (opusplan model setting, where model aliases point)

1. What opusplan is: Opus only while in plan mode

opusplan is a model alias you can pass to /model, just like sonnet or opus. The official documentation describes it as a special mode that uses opus during plan mode, then switches to sonnet for execution.

The only thing that decides the switch is whether you are in plan mode. Plan mode is the state in which Claude reads files and runs commands to investigate, writes a plan, and doesn't edit your source until you approve it (for an overview of all permission modes, see What Are Claude Code Permission Modes? Ask, Accept Edits, Plan, Auto, Bypass).

StateModel under opusplanWhat it's suited for (per the docs)
In plan modeopus (Opus 5 on the Anthropic API)Complex reasoning and architecture decisions
Everything elsesonnet (Sonnet 5 on the Anthropic API)Code generation and implementation

Source: Claude Code documentation, Model configuration (as of September 15, 2026). Where the aliases point depends on the provider; on Amazon Bedrock and Google Cloud's Agent Platform, for example, sonnet is Sonnet 4.5

There is one more similar mechanism. A session running on Haiku automatically moves up to Sonnet, but only while in plan mode (introduced in v2.0.17 alongside Haiku 4.5; at launch, Amazon Bedrock and Google Vertex AI were not upgraded automatically). This one works without any setting.

2. How to set it

You specify it the same way as any other model. Here are the methods, listed from highest to lowest priority as given in the official documentation.

MethodHow to write itScope
Switch mid-conversation/model opusplanThe current session and new sessions from then on (saved to your user settings)
Specify at startupclaude --model opusplanThat session
Environment variableANTHROPIC_MODEL=opusplanSessions started in that environment
Settings file"model": "opusplan" in settings.jsonEvery new session

Typing /model opusplan doesn't just switch the current session: it writes model in your user settings, so it also becomes the default for new sessions. To try it for one session only, start Claude Code with claude --model opusplan.

{
  "model": "opusplan"
}

Three other settings are worth knowing.

  • Pin the model versions: the Opus that opusplan uses in plan mode is set by ANTHROPIC_DEFAULT_OPUS_MODEL, and the Sonnet it uses otherwise by ANTHROPIC_DEFAULT_SONNET_MODEL. On Amazon Bedrock and similar providers, put your provider's model IDs here
  • Use a 1M token context: on plans where Opus is automatically upgraded to 1M, such as Max, Team and Enterprise, the Opus side of opusplan gets 1M too. Otherwise, to get 1M for both phases, specify opusplan[1m]. Setting it with /model opusplan[1m] requires v2.1.265 or later; on earlier versions, use --model or the settings file
  • It doesn't work in the default-model environment variable: putting opusplan in ANTHROPIC_DEFAULT_MODEL, which sets the default for new sessions, is ignored. To make it your default, type /model opusplan or write it in model in settings.json

Source: Claude Code documentation, Model configuration (Setting your model, Environment variables, Extended context, opusplan model setting), Settings reference (model)

Can you pick it from the UI?

  • It does not appear in the /model list in the terminal. Opening /model without an argument lists Opus, Sonnet, Haiku and others, but not opusplan. A GitHub request to add it to the list (#26556) is still open as of September 15, 2026. 🟡 The official documentation doesn't say whether it appears in the list; this is based on user reports. The same issue also reports that adding the row yourself with the modelPicker setting introduced in v2.1.243 doesn't work in append mode, because it is treated as a duplicate of the Sonnet row
  • 🟡 The official documentation doesn't say whether opusplan appears in the model picker of the VS Code extension or the desktop app. Both run on top of Claude Code, which uses settings.json, but how they handle it in the UI is unconfirmed, so check the displayed model before relying on it

3. How a session flows

Setting opusplan alone leaves you on Sonnet. It only becomes Opus when you enter plan mode yourself.

  1. Enter plan mode: in the terminal, cycle to it with Shift+Tab, or prefix your prompt with /plan. To start in it, use claude --permission-mode plan. In the desktop app, pick it from the permission mode selector (the mode selector)
  2. Opus writes the plan: it reads files and runs commands to investigate, then puts together a plan without editing anything. You can also press Ctrl+G to open the plan in your editor and change it directly
  3. Approve the plan: choose from "Yes, and use auto mode", "Yes, manually approve edits" or "No, keep planning" (when auto mode is unavailable, the first option reads "Yes, auto-accept edits"). Approving exits plan mode, and from here Sonnet does the implementation
  4. If you want to plan again: go back to plan mode with Shift+Tab, or prefix your next prompt with /plan. While you are there, it is Opus again

If you set showClearContextOnPlanAccept to true, an option labeled "Yes, clear context and …" (the rest names the permission mode) is added at the top of the approval choices. It discards things like the contents of files read while planning and starts implementation with only the plan (the default is false). As section 5 explains, with opusplan this also matters for cost.

Source: Claude Code documentation, Choose a permission mode (Analyze before you edit with plan mode, Review and approve a plan), Settings reference (showClearContextOnPlanAccept), Desktop (choosing a permission mode)

Don't ask the model which model it is running on. In a GitHub discussion in September 2025, an Anthropic staff member wrote that instead of asking the model what it is, you should check what the application shows. Ways to check are collected in FAQ Q3.

4. Why it isn't listed in /model

opusplan is not a new feature. It isn't listed because it was removed from the UI at one point. Tracing the CHANGELOG and GitHub issues gives the following.

WhenWhat happened
v1.0.77Added to /model as "Opus Plan Mode": Opus only in plan mode, Sonnet otherwise
v1.0.88ANTHROPIC_DEFAULT_OPUS_MODEL and ANTHROPIC_DEFAULT_SONNET_MODEL make it possible to choose the versions opusplan uses
v2.0.0 (September 2025)Removed from the model selector (not in the CHANGELOG; known from the issue). A user opens issue #8358 asking why it was removed
September 29, 2025An Anthropic staff member explains in the issue that they had found Sonnet 4.5 to be generally better than Opus 4.1 and intentionally removed it from the selector, and that the opusplan setting itself still works
v2.0.17Haiku 4.5 sessions automatically use Sonnet in plan mode
February 18, 2026The reporter confirms it works with /model opusplan and closes #8358. The same day, #26556 is opened asking for it to be shown in the list (unresolved as of September 15, 2026)
February–March 2026Bug report #27237 says opusplan picks Sonnet 4.5 instead of Sonnet 4.6. It was closed automatically without a response from Anthropic
v2.1.172Fixed plan-mode Opus not getting 1M context on plans entitled to 1M
v2.1.265Fixed /model opusplan[1m] being rejected with "Model not found"

Source: Claude Code CHANGELOG, GitHub issue #8358, #26556, #27237 (all checked on September 15, 2026)

🟡 Anthropic hasn't given a fresh explanation of why it isn't listed today. The September 2025 explanation compared Sonnet 4.5 and Opus 4.1 as they were then. Whether the same judgment still holds for the Opus 5 and Sonnet 5 pairing is unknown. On the other hand, the official documentation still has an opusplan section, and the CHANGELOG lists fixes made in 2026, so it remains usable as a setting.

There are also reports, like issue #27237, that the versions chosen weren't what users expected. That report's model ID, however, is in Google Cloud's format, and the current official documentation still maps sonnet to Sonnet 4.5 on Google Cloud, so it may have been working as designed (my own reading). If this concerns you, pin the versions with the two environment variables above and check which model actually ran.

5. Pricing and caching: every switch means a full re-read

Most people use opusplan to keep usage or cost down. Handing implementation to Sonnet lowers the price per token.

ModelInputOutput5-minute cache write1-hour cache writeCache read
Claude Opus 5$5$25$6.25$10$0.50
Claude Sonnet 5$2$10$2.50$4$0.20

Source: Claude Platform Docs, Pricing (per million tokens, as of September 15, 2026)

However, there is one cost that is easy to overlook. Prompt caches are separate for each model, and the official documentation says that with opusplan, each plan-mode toggle is a model switch and starts a fresh cache. In other words, Sonnet's first response right after you leave plan mode, and Opus's first response right after you go back, both read the entire conversation so far without the cache.

To get a sense of the size, I estimated the cost of a switch made once the conversation has grown to 100,000 tokens. On a subscription, within your plan, the main conversation's cache lasts 1 hour, so writes are counted at the 1-hour rate. Note that with an API key or a cloud provider you can also give the main conversation a 1-hour cache by setting promptCacheTtl to 1h (v2.1.242 and later), and conversely, on a subscription the cache drops to 5 minutes while you are paying with usage credits beyond your plan.

SwitchAmount rewrittenAPI key (5-minute cache)Subscription (1-hour cache)
Leaving plan mode (to Sonnet 5)100,000 tokensAbout $0.25Equivalent to about $0.40
Returning to plan mode (to Opus 5)100,000 tokensAbout $0.63Equivalent to about $1.00

Source: my own estimate from the official rates (100,000 tokens × rate). 🟡 It has not been published that subscription limits decrease in proportion to these amounts. Cache lifetimes are from Claude Code documentation, How Claude Code uses prompt caching

If you kept reading the same 100,000 tokens on Opus, each cache read would cost about $0.05. If you go in and out of plan mode many times while the implementation exchanges are still short, the switch writes can end up costing more. There are three ways to keep costs down.

  • Plan early in the conversation: switching while the context is still small keeps the amount rewritten small
  • Clear the context when you approve: enable showClearContextOnPlanAccept and choose the clear-context option, and Sonnet starts with only the plan, so it re-reads less
  • Don't bounce between planning and implementation: every return to plan mode triggers a re-read on the Opus side as well

A note on subscription limits too. The session limit and the weekly limit are shared across all models, and there are separate per-model-family limits, such as an Opus limit and a Sonnet limit. Because opusplan uses Opus while in plan mode, once you've hit the Opus limit you can't use Opus in plan mode. The pricing page lists Opus as available even on the Pro plan, but according to the official documentation, using Opus with 1M context on Pro requires usage credits.

Source: Claude Code documentation, How Claude Code uses prompt caching (Switching models, Changing permission mode, Which TTL each request gets), Error reference (limits shared across all models and per-model-family limits), Model configuration (Extended context), Claude pricing page (models by plan)

6. How it differs from the advisor tool and subagents

opusplan isn't the only way to combine a strong model with a fast one. The official documentation compares the options by when the stronger model runs.

MethodWhen the stronger model runsHow it starts
Advisor toolAt decision points during the workClaude calls it when needed
opusplanDuring plan mode, when allowed by availableModels (Sonnet for execution)You enter plan mode
Subagent with a specified modelFor the whole delegated taskClaude delegates, or you invoke it
Switching with /modelFrom the next request onwardYou switch

Source: Claude Code documentation, Escalate hard decisions with the advisor tool (Compare with related features)

The advisor tool keeps the main session on a fast model while Claude consults a stronger model partway through the work. Unlike opusplan, turning it on or off doesn't break the main session's cache. However, each consultation has the advisor read the whole conversation, and that read isn't cached. As of September 15, 2026, it is experimental and only available on the Anthropic API (not on Amazon Bedrock and similar providers).

Subagents run only the delegated work on a different model. Setup and measurements are covered in How to Run Claude Code Subagents on a Different Model.

Source: Claude Code documentation, Escalate hard decisions with the advisor tool (Cost, Impact on prompt caching, Requirements)

7. When it fits and when it doesn't

Based on the mechanics above, here is what to weigh (this is my own summary derived from how it works, not an official recommendation).

Good fit

A "plan, approve, then implement for a long stretch" workflow

Work where you already use plan mode and, once the plan is settled, the implementation exchanges go on for a long time. There are few switches, and the lower implementation rate pays off.

Usable with some care

Work where you plan after the context has grown large

Each switch re-reads more. Combined with the setting that clears context on approval, you can keep the re-read on the Sonnet side down.

Poor fit

Work that bounces between planning and implementation

Going back to plan mode for every small fix adds more re-reads. Work where the implementation itself needs a strong model is also a poor match for opusplan, which executes on Sonnet.

When in doubt, the reliable approach is to do the same kind of task once with opusplan and once with your usual model, and compare the /usage numbers and the results. How to look at usage in detail per session is covered in Claude Code Usage by Session.

FAQ

Q1. I opened /model but can't find opusplan.
It isn't shown in the list, by design (as of September 15, 2026). Specify it by typing the name: /model opusplan. Typing it this way also saves it as the default for new sessions. To use it for one session only, start with claude --model opusplan.

Q2. I set opusplan, but it stays on Sonnet the whole time.
That's expected. opusplan only uses Opus while in plan mode, and it doesn't enter plan mode on its own. Cycle to it with Shift+Tab, or prefix your prompt with /plan.

Q3. Is there a way to check which model is running right now?
Check what the app shows rather than asking the model. /status shows the current model, and the status line passes the current model to your script, so you can configure it to display the model name. After the fact, message.model on each response in the conversation logs (the JSONL files in ~/.claude/projects) records the model that actually responded.

Q4. Does it work on Amazon Bedrock or Google Cloud?
Yes. Put your provider's model IDs in ANTHROPIC_DEFAULT_OPUS_MODEL and ANTHROPIC_DEFAULT_SONNET_MODEL to specify the versions opusplan uses. If your organization's managed settings (availableModels) exclude the newest Opus, on the Anthropic API and Claude Platform on AWS it plans with the newest permitted Opus, and stays on Sonnet even in plan mode only if every Opus is excluded. On Bedrock, Google Cloud, Microsoft Foundry and similar providers, if the model is excluded, planning stays on the session's original model even in plan mode (both behaviors apply from v2.1.205).

Q5. What is opusplan[1m]?
It uses a 1 million token context for both the plan-mode Opus and the execution-time Sonnet. On plans where Opus is automatically upgraded to 1M, such as Max, Team and Enterprise, the Opus side gets 1M even without it. On the Anthropic API, Sonnet 5 always runs with 1M anyway. /model accepts this form from v2.1.265 onward.

Sources