Claude Code Advisor: Sonnet + Opus Setup and Verification

Use Claude Code advisor to keep Sonnet handling routine coding while Opus reviews difficult decisions. Start with claude --model sonnet --advisor opus, then verify an actual Advising result before relying on the review. Calls are model-selected, consume extra tokens, and can disappear after a gateway rejects the tool.

As of 2026-11-06, the advisor feature remains experimental. The examples below assume an installed CLI, working authentication, and a normal request through Anthropic. Both subscription and API-billed accounts can use that route; gateway support needs separate checks.

When should you use advisor instead of another model?

Choose advisor for a refactor, recurring bug, or implementation with occasional difficult decisions. Sonnet continues the task while a second model reviews the conversation, including tool calls and results.

This is the division described in Anthropic’s advisor strategy. It does not guarantee Opus-quality results on every task or a fixed saving.

Your need	Choose	What changes
Occasional advice during execution	Advisor	Claude decides when to consult another model
Opus planning followed by Sonnet implementation	opusplan	Plan mode uses Opus, subject to model access; execution uses Sonnet
A separate research or review assignment	A subagent with a selected model	The selected model runs the delegated task
Stronger reasoning on subsequent main-session requests	/model	You change the main model

For a short task with little planning, start without advisor. If nearly every step needs Opus, switch the main session to Opus 5.5 instead.

The launch command does not create three Haiku workers for search, grep, and documentation. Use the documented subagent model configuration for that separate setup. The documented CLI option is --agents with JSON; do not substitute the circulating --subagents haiku command.

Enable advisor in one of three ways

Use the launch flag for your first trial because it leaves your saved advisor preference unchanged. Check the client version in Bash first:

claude --version

Use 2.1.284 or later for this Sonnet 5.5 and Opus 5.5 example. The model requirements set this minimum; it is not the advisor feature’s launch version. The documented CLI update command is claude update.

For one session: use —advisor

Run this in Bash from your project directory:

claude --model sonnet --advisor opus

On current direct Anthropic configurations, the aliases resolve to Sonnet 5.5 and Opus 5.5 as of 2026-11-06. Alias mappings can change or be overridden. To name the versions explicitly:

claude --model claude-sonnet-5-5 --advisor claude-opus-5-5

The flag overrides advisorModel for this session. Its absence from claude --help is expected, according to the advisor documentation.

During a session: use /advisor

Enter this inside Claude Code:

/advisor opus

Expect Advisor set to followed by the model name. Running /advisor alone opens the model picker.

In a local terminal session, the selection normally becomes your saved default. Remote-session persistence has separate rules in the settings reference.

For future sessions: set advisorModel

Merge this property into your user settings at ~/.claude/settings.json:

{
  "advisorModel": "opus"
}

Keep the file’s other settings. This selects the advisor; it does not select Sonnet as the main model.

After enabling the feature, look for:

Advisor Tool (experimental) is on and may use more tokens · /advisor

The notification confirms enablement. It does not prove that a consultation occurred.

Which model pairs work?

Choose an advisor that Claude Code ranks at least as high as the main model. These selected pairings come from the current pairing table, checked on 2026-11-06.

Main model	Advisor	Intended use
Sonnet 5.5	Opus 5.5	Routine implementation with stronger review
Haiku 5.5	Opus 5.5	A lighter main model with deeper consultation
Sonnet 5.5	Sonnet 5.5	A second review using the same model
Opus 5.5	Opus 5.5	A second Opus review
Opus 4.7 or Opus 4.8	Sonnet 5.5	A documented cross-family pairing

Haiku 5.5 as main model or advisor requires 2.1.293 or later. Sonnet 5.5 advising Opus 4.7 or Opus 4.8 requires 2.1.287 or later. Haiku 4.5 can request advice but cannot serve as the advisor.

These are accepted combinations, not guaranteed quality rankings for your repository. An organization’s availableModels allowlist can still block a selection. A disallowed or ineligible --advisor selection can stop an interactive launch with an error. A lower-ranked advisor or an unrecognized model ID can leave the main session running without advisor.

Subagents inherit the advisor configuration and check the pairing against their own models. Include their possible consultations when evaluating total usage.

How do you prove the advisor was called?

Use the tool transcript as evidence, then inspect usage. A startup banner or Claude’s claim that it consulted Opus is insufficient.

Try this read-only prompt in a repository you know:

Inspect this repository's authentication flow without changing files.
Propose one small refactor and identify its main regression risk.
Consult the advisor before presenting the plan.
Include the tests that would check the proposed change.

This is a suggested probe, not a guaranteed invocation. Claude chooses the timing. Planning, recurring errors, and completion checks are common occasions, not three fixed triggers.

There is no Claude Code advisor setting to force calls or cap their number. Instructions in a prompt or CLAUDE.md can request more consultations, but do not create an enforced review gate.

Watch for Advising with the advisor’s model name. Interpret the result:

Result	What it establishes	Next action
Reviewed	The advisor reviewed the conversation	Press Ctrl+O when readable guidance was returned; examine the resulting plan
Declined	The call occurred, but advice was declined	Read any available reason and reconsider the request
Unavailable	The call failed	Inspect Advisor unavailable (<error_code>) and diagnose that failure
No Advising entry	No observed consultation	Request one explicitly, then check activation and routing if none appears

Run /usage after the probe. Advisor usage contributes to the session totals, but a rising total alone does not identify a successful review. Keep the transcript result alongside it.

What does an advisor consultation cost?

Budget for another model reading the conversation. Advisor tokens add to the main model’s usage.

For API billing, advisor input and output use the advisor model’s rates. For the Sonnet/Opus workflow on a subscription, advisor activity consumes plan usage; it is not a separate unlimited review allowance.

As of 2026-11-06, standard Anthropic Opus 5.5 pricing is $4 per million input tokens and $20 per million output tokens.

Here is a hypothetical advisor-only estimate. Assume direct Anthropic API billing, standard global rates, 50,000 uncached input tokens, and 2,000 billed output tokens. Billed output includes thinking.

Advisor token cost
= (50,000 × $4 + 2,000 × $20) / 1,000,000
= $0.24

This is not a flat fee per consultation. It excludes main-model work and does not calculate subscription allowance consumption. A larger transcript or longer advisor output raises the estimate.

For Claude Code, the advisor documentation says each consultation rereads the full transcript without reusing an advisor cache. Toggling /advisor preserves the main model’s prompt cache, and returned advice can enter that cache on later turns.

Keep that statement specific to Claude Code. The raw Messages API now documents a separate advisor caching option. It is not a configuration step in this CLI workflow.

Compare total cost on the same completed task before adopting the pairing. Use the same acceptance checks and count retries and failed attempts. For context-heavy sessions, measure MCP context overhead before attributing every increase to advisor.

The dollar figure in /usage is an estimate. Check the provider’s billing record for charges.

Fix gateway 400 errors and silent fallback

Match the fix to the failure. Missing activation, a rejected model pairing, and an unsupported server tool have different recovery paths.

No startup notification or advisor activity

Check your environment and the env section of settings before changing models. CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 disables the feature outright.

Also check DISABLE_TELEMETRY and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC. They can disable the feature-flag mechanism advisor requires. Review their documented effects, including first-session and gateway-credential conditions.

If these are intentional organization settings, use an approved configuration or a different review workflow. If an optional local setting caused the problem, remove it from its source and relaunch. Repeat the transcript probe; changing an environment variable alone does not prove success.

The session works, but the model pairing was rejected

Check both resolved model IDs and availableModels. A saved advisor can remain inactive when the main model is incompatible.

If the API rejects an attached pairing, Claude Code retries without advisor and the conversation can continue without an error. Select an accepted advisor, then use /clear, /compact, or a new session before checking again.

Preserve any task context you need before clearing the conversation. This recovery applies to pairing rejection, not every gateway rejection.

You see Input tag ‘advisor_20260301’

A 400 or 422 naming Input tag 'advisor_20260301' indicates that the gateway or upstream rejected the advisor tool type.

From 2.1.280, Claude Code recognizes this rejection and retries once without the advisor entry and its beta value. The code-writing session may recover while advisor remains absent.

The gateway compatibility guide specifies the current lifetime: requests to that base URL omit advisor until Claude Code exits. The /advisor command is unavailable during that state. After fixing the route, fully exit and relaunch Claude Code; /clear alone is not the documented reset.

For an older client, upgrade first. For a current client still showing the error, ask the gateway operator to check the tool definition:

• The tools entry with type advisor_20260301 reaches a supporting Anthropic upstream.
• The paired anthropic-beta value, advisor-tool-2026-03-01, travels with it.
• Upstream error bodies preserve the wording Claude Code uses to recognize rejection.

If removing both the tool and its header makes ordinary requests work, that demonstrates fallback. It does not establish advisor compatibility.

BetterToken lists claude-sonnet-5-5 and claude-opus-5-5 as of 2026-11-06. Its Claude Code setup uses https://bettertoken.ai as ANTHROPIC_BASE_URL, without /v1. Model availability does not confirm advisor support: obtain route-specific confirmation and verify an actual consultation.

If ordinary Messages requests also fail, first isolate the connection with the minimal Claude API request guide. Then repeat the advisor-specific probe.

Turn advisor off

Use the session command when you want to stop consultations:

/advisor off

For a full disable, set this in Bash before launching:

export CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1
claude

With that variable set, /advisor is unavailable and advisorModel is ignored. Claude Code accepts --advisor, but it has no effect.