The 'Haiku builds, Opus advises' setup for Claude Code
Claude Code's experimental advisor tool lets a fast Haiku session call on Opus at key moments. How to set it up with the --model and --advisor flags, which Haiku you actually get, what it costs, and when it fails silently.
Updated November 20, 2026: Expanded with setup steps, model-alias caveats, costs and alternatives.
Claude Code's advisor tool lets a fast main model pause at key moments and ask a stronger model for guidance. One common pairing in the docs is Haiku as the worker and Opus as the advisor: Haiku does the hands-on work, and Opus weighs in when a decision matters. The feature is experimental and may change.
How the advisor works
The advisor runs server-side as a tool. When Claude calls it, the advisor model receives the full conversation, including every tool call and result, and returns guidance that the main model applies before it carries on. You pick the advisor model; Claude decides when to call it.
According to the docs, Claude tends to consult before committing to an approach, when the same error keeps coming back, and before declaring a task finished. There is no setting that caps or forces calls, but you can ask in plain words, for example "consult the advisor before you continue". If a recommended step fails or the files contradict the advice, Claude is meant to surface the conflict rather than push ahead.
Set it up
There are three ways to turn it on. For a single session, combine the documented --model and --advisor launch flags:
claude --model haiku --advisor opusThe --advisor flag overrides your saved setting for that session and is not listed in claude --help. Launch exits with an error if the main model does not support the advisor, the requested model cannot act as one, or your organisation's allowlist excludes it. Mid-session, run /advisor for a picker or name the model; the choice is saved to advisorModel in your user settings:
/advisor opusFor a persistent default without opening a session, put it in your Claude Code settings file:
{
"advisorModel": "opus"
}Claude Code then shows a notice that the experimental Advisor Tool is on and may use more tokens. To stop, run /advisor off. Setting CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 removes the /advisor command and makes any saved advisorModel and the --advisor flag do nothing. Subagents may still use the advisor if their own model satisfies the pairing.
Check which Haiku you are getting
The haiku alias does not mean the same model everywhere. On the Anthropic API it resolves to Haiku 5.5, but on Claude Platform on AWS and Claude Models on Google Cloud (Anthropic managed) it resolves to Haiku 4.5, so pass claude --model claude-haiku-5-5 there. Haiku 5.5 in either role needs Claude Code v2.1.293 or later (run claude update). Haiku 4.5 can call an Opus advisor but cannot act as one. On all three platforms, the opus alias resolves to Opus 5.5.
The advisor must rank at or above the main model. A Haiku 5.5 main model accepts Fable, Opus 4.7 or later, Sonnet 5 or later, or another Haiku 5.5.
During a call the transcript shows an Advising line and the outcome. Reviewed means it read the conversation, and Ctrl+O shows readable guidance; Declined may carry a reason, also under Ctrl+O; Unavailable shows an error code. One silent case: if the API refuses a pairing, Claude Code resends without the advisor, with no error and no Advising lines; a new choice then takes effect after /clear or /compact.
Cost and caching
Every advisor call is billed at the advisor model's rates on top of the main model's usage: Opus prices on API billing, your usage limits on subscription plans. The docs say the Haiku plus Opus pairing costs more than Haiku alone but less than switching the main model to Sonnet or Opus. Advisor usage appears in /usage.
Caching is the hidden cost to watch. Turning the advisor on or off does not break the main model's prompt cache, and the guidance it returns is cached as part of the transcript on later turns. But the advisor's own read of the conversation is never cached: each call processes the whole transcript again, so the cost of a call grows with the length of the session.
Anthropic's April blog post introducing the advisor strategy gives a sense of the trade-off, measured with the models of that time (its API example pairs Sonnet 4.6 with Opus 4.6): on BrowseComp, Haiku with an Opus advisor scored 41.2%, against 19.7% for Haiku alone, and cost 85% less per task than Sonnet solo while scoring 29% lower. In that design the advisor only returns guidance; the executor makes the tool calls.
Limits
- Providers: the Anthropic API, Claude Platform on AWS and Claude Models on Google Cloud (Anthropic managed), the last two with Claude Code v2.1.300 or later. Not on Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry.
- Outside AWS and Google-managed Claude, the advisor depends on a feature flag fetched from Anthropic, so sessions that turn fetching off, for example with DISABLE_TELEMETRY, run without it.
- An organisation's availableModels allowlist can block the advisor model.
When to use it, and the alternatives
The docs pitch the advisor at long, multi-step work where the plan decides the outcome: big refactors, debugging a recurring failure, or work you want checked before it is called done. If every turn needs the strongest model, switch the main model with /model instead. Alternatives are opusplan (Opus in plan mode, Sonnet for execution) and subagents with their own model.
Our take
In our view, Haiku with an Opus advisor fits the case the docs describe: long, multi-step sessions where most turns are routine but a few decisions matter, and you want a second opinion before anything big. For short edits there is little to plan, so the advisor adds less. On AWS or Google-managed Claude, pin claude-haiku-5-5. We would also watch /usage in long sessions, since each advisor call re-reads the transcript, and ask for a consultation by name before risky steps rather than wait for Claude to pick the moment.
Source: Escalate hard decisions with the advisor tool (Claude Code Docs), Model configuration (Claude Code Docs), The advisor strategy (Claude blog)
This story first appeared in the claudefox daily briefing for November 6, 2026.