Claude Lessons / Guides

The Claude Code Advisor Tool: A Stronger Model on Call

Claude Lessons team · Updated November 3, 2026

Most of a long coding task is routine — reading files, running tests, applying a decided change. A few moments are not: picking the approach, getting unstuck from an error that keeps coming back, deciding the work is actually finished. Those moments determine the outcome, and they are the only ones that really need your strongest model. The advisor tool is Claude Code's answer to that asymmetry: run a fast model as the main model, and let it consult a stronger one at the moments that matter. It is experimental, Anthropic-API-only, and almost nobody has written about it properly. This guide covers how to turn it on, which model pairings are actually accepted, what the Advising lines in your transcript mean, how the tokens bill — and the decision layer that matters most: advisor vs. opusplan vs. subagents vs. just switching models.

What the advisor tool actually is

The advisor tool lets Claude consult a second, typically stronger model at key moments during a task. The advisor receives the full conversation — every tool call and every result, not a summary — and returns guidance that Claude applies before continuing.

Three properties follow from that, and they're the ones that matter:

• It runs server-side. The advisor is a server tool executed on Anthropic's infrastructure, which is why it's available to subscription and API-billed accounts alike rather than being an API-key-only power feature.
• You choose the model; Claude chooses the moment. There is no setting to force, cap or schedule advisor calls. Claude decides, based on the task.
• It sees everything. Because the advisor reads the entire transcript, its guidance is grounded in what actually happened — which is also why each call costs the advisor model a full transcript read.

The 60-second version

Pick a fast main model and a strong advisor:

/model sonnet
/advisor opus

Claude Code confirms with Advisor set to followed by the model name, saves it to advisorModel in your user settings, and shows a notification: Advisor Tool (experimental) is on and may use more tokens · /advisor.

Now work normally. When Claude consults, your transcript shows an Advising line with the advisor model's name while the call is in flight, then reports the result. Press Ctrl+O to read the guidance. To stop:

/advisor off

That's the whole loop. Everything below is about choosing the right pairing, reading the signals, and knowing when a different feature is the better answer.

When it earns its tokens — and when it doesn't

The advisor fits long, multi-step tasks where most turns are routine but plan quality determines the outcome. That sentence is the whole selection criterion. Concretely, it fits:

• Large refactors, where the approach chosen in turn three decides turns four to forty.
• Debugging sessions where an error keeps recurring — the classic case where a model loops on its own hypothesis and a fresh, stronger read breaks the cycle.
• Work you want independently checked before Claude declares it done. Premature "finished" is one of the more expensive agent failure modes, and this is a structural defence against it.

It adds little value in two situations:

• Short tasks. There's little to plan, so there are no decision points to escalate.
• Work where every turn needs the strongest model. If the routine turns aren't routine, you don't want an advisor — you want to switch the main model.

A useful way to decide: look at your last three bad sessions. If they went wrong at the start (wrong plan) or at the end (declared done, wasn't), an advisor helps. If they went wrong in the middle on ordinary mechanical work, a stronger main model helps and the advisor won't.

Advisor vs. opusplan vs. subagents vs. switching models

The advisor is one of four ways to get a stronger model involved in a task. They differ on two axes: when the stronger model runs, and who starts it.

Translated into a decision you can actually make:

• Your plans are bad → opusplan. It puts the strong model exactly where the plan is formed, and costs nothing for the rest of the task. Note it runs only when your organization's availableModels allowlist permits it.
• Your plans are fine but execution drifts, loops, or stops early → advisor. This is the gap the other three don't cover, because it's the only one where the stronger model is invoked reactively, based on what's happening.
• One bounded piece of the work is hard → a subagent with model set. The strong model owns that subtask end-to-end and returns a summary, which also keeps its noise out of your main context window.
• Everything is hard → /model. Don't pay for an advisor on top of a main model that is already struggling at every turn.

Two things to note about composition. First, these aren't exclusive — opusplan plus an advisor is a perfectly reasonable configuration, with the strong model on the plan and on call afterwards. Second, subagents inherit the configured advisor and apply the same pairing check against their own model, so a delegated subtask on a smaller model can still escalate. That's a genuinely useful interaction and almost nowhere documented.

Worth distinguishing from both: if what you want is a separate session to review the work rather than an in-conversation consultation, that's cross-session messaging or an agent team, not the advisor. The advisor never leaves your conversation.

Three ways to set an advisor

1. The /advisor command

Run it with no arguments to open a picker listing the available advisor models — the picker shows your current choice, the models that can advise, and a No advisor entry. Or pass the model directly:

/advisor opus

The command confirms with Advisor set to and the model name, and saves your selection to advisorModel in your user settings so it persists across sessions. Picks made from a Remote Control client, or in a session attached to a remote worker, apply to that session only and don't change the stored key.

It works where there's no picker. Since v2.1.260, /advisor also works in non-interactive -p mode, in the Agent SDK, in the desktop app, and over Remote Control. On those surfaces: /advisor with no argument prints the current advisor and the aliases it accepts, /advisor <model> sets it, and /advisor off turns it off.

2. The advisorModel setting

To configure a default without opening a session, set it in your settings file:

{
  "advisorModel": "opus"
}

The value is one of the aliases "fable", "opus" or "sonnet", which resolve to Claude Code's current built-in default version for that family and advance with new Claude Code releases — or a full model ID such as "claude-opus-5-5" or "claude-haiku-5-5". The key is unset by default, so the advisor is off, and unsetting it turns the advisor off again.

You don't usually need to edit this by hand; /advisor writes it to ~/.claude/settings.json for you. Use the file when you want the setting checked in, or shared across a team's config.

3. The --advisor flag

To set an advisor for a single session without touching your saved setting:

claude --advisor opus

The flag takes precedence over advisorModel for that session. Note that Claude Code does not list --advisor in claude --help, which is a large part of why so few people know the feature exists.

Claude Code exits with an error at launch if:

• the session's main model doesn't support the advisor;
• the requested model can't act as an advisor at all — Haiku 4.5 is the example;
• your organization's availableModels allowlist excludes the requested model;
• you requested Fable and your account still needs the usage-credits consent.

With one exception: in a background session, Claude Code starts the session without the advisor instead of exiting. And if the model you pass can advise but simply ranks below your main model, the session starts either way — your main model just runs without an advisor.

The pairing rules: which advisor your main model accepts

This is the part everyone gets wrong. Claude Code ranks models by capability for the advisor role, and the advisor must rank at or above your session's main model. You cannot have a strong model consult a weaker one. Rows run from the lowest-ranked main model to the highest.

Version floors attached to specific cells:

• Fable 5.1 requires Claude Code v2.1.257 or later, and Fable models require Fable access.
• Sonnet 5.5 as the advisor for an Opus 4.7 or Opus 4.8 main model requires Claude Code v2.1.287 or later.
• Haiku 5.5, as main model or as advisor, requires Claude Code v2.1.293 or later.

Three non-obvious consequences. First, Haiku 4.5 can call the advisor but can't act as one — it's the only model in the table that appears on the left and never on the right. Second, a Fable main model only ever accepts a Fable advisor; Claude Code doesn't apply an Opus or Sonnet advisor to it. Third, the aliases opus, sonnet and fable resolve to whatever Claude Code currently treats as the default for that family, and that resolution moves with releases — so an alias pairing that works today can start or stop being accepted after an upgrade. Pin a full model ID if you need it stable.

Claude Code validates the pairing before sending a request, and the API validates it again:

• Advisor ranks below the main model: Claude Code doesn't attach it to the main model's requests, and says so in the /advisor output and a notification. Subagents whose own model satisfies the pairing may still use it.
• The API refuses a pairing Claude Code attached: that request is resent without the advisor. The conversation continues, you see no error, and you get no advisor calls — a quiet failure worth knowing about. Picking a different advisor then takes effect after /clear or /compact, and in new sessions.
• Either model is unrecognized by Claude Code: the advisor isn't attached.

Fable as the advisor, and the usage-credits consent

On some plans Fable usage bills to usage credits, and Fable as the advisor bills the same way. If your account requires the one-time consent for that, Claude Code won't apply Fable as the advisor until you've accepted it. Before you have:

• /advisor fable, or picking Fable in the picker, saves nothing and points you to /model fable instead.
• claude --advisor fable exits at launch with the same pointer — except in a background session, which starts without the advisor.
• With Fable already saved as your advisorModel, requests go out without the advisor, and an interactive session whose main model supports the advisor shows a notification pointing to /model fable.

To accept it: run /model fable and choose to continue on Fable. Claude Code records the consent and saves Fable as your selected model. Then select Fable as the advisor. Until consent exists, a Fable advisor bills nothing — because the selection is never applied.

Pairings worth choosing on purpose

Any accepted pairing works. These six balance cost against capability in meaningfully different ways.

The same-model pairings are worth a second look, because they're counter-intuitive and genuinely useful. An Opus-advises-Opus or Sonnet-advises-Sonnet setup isn't buying you more capability — it's buying you independence. The advisor reads the transcript fresh, without the main model's accumulated commitment to its own approach. That's the mechanism that breaks error loops, and it doesn't require a bigger model to work.

What you see during a session

When Claude calls the advisor, the transcript shows an Advising line with the advisor model name while the call is in progress. When the result returns, the line reports one of three outcomes:

Claude doesn't follow guidance blindly. It generally applies the advisor's recommendation, but adapts when its own evidence contradicts a specific claim — if a recommended step fails when tried, or the file contents contradict the advice, Claude surfaces the conflict rather than following it unconditionally. That's the right behaviour, and it means an Advising line is not a guarantee the advice was taken. Read the guidance when the result matters.

You can ask for a consultation. Claude decides when to call the advisor — it tends to consult before committing to an approach, when an error keeps recurring, and before declaring a task done — but the timing is model-driven rather than rule-based. You can request one in your prompt the way you'd request any tool:

consult the advisor before you continue

There is no setting to cap or force advisor calls. If you want more or fewer consultations during a task, say so in your instructions — or put the standing preference in CLAUDE.md, which is the durable version of the same nudge.

Cost, caching, and what it does to your bill

Each advisor call has the advisor model read the conversation, so it consumes tokens at the advisor model's rates in addition to your main model's usage. How that bills depends on how you pay:

• API billing: you pay the advisor model's input and output rates for advisor tokens.
• Subscription plans: advisor usage counts toward your plan's usage limits — except that a Fable advisor bills to usage credits on plans where Fable usage does.

The economics work because Claude calls the advisor at decision points rather than on every turn. Pairing a faster main model with a stronger advisor typically costs less than running the stronger model throughout. Advisor usage shows up in the session totals from /usage, so you can see what it's actually costing rather than guessing — the same discipline covered in the token usage guide.

The caching detail that matters

Enabling or disabling the advisor mid-session does not invalidate your main model's prompt cache. That's a deliberate and unusual property: switching models does break the cache, but toggling /advisor keeps the cached prefix intact, and the advisor's returned guidance is cached as part of the transcript on later turns. So experimenting with /advisor on and off mid-session is cheap in a way that experimenting with /model is not.

The flip side: the advisor's own read of the conversation is not cached. Each advisor call processes the full transcript anew, with no reuse between calls. That is the real cost driver — in a long session, late advisor calls are substantially more expensive than early ones, because the transcript they read has grown. If your sessions run long and your advisor is expensive, that asymmetry is worth knowing about, and it's another argument for keeping the context window tidy.

Requirements, and the quiet ways it stays off

The advisor needs all three of these:

• The Anthropic API. The advisor is a server-executed tool. It is not available on Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform or Microsoft Foundry. Through an LLM gateway configured with ANTHROPIC_BASE_URL, availability depends on whether the gateway forwards the request intact to the Anthropic API — if the gateway or its upstream doesn't recognize the advisor tool, Claude Code's automatic retry and error-forwarding behaviour governs what happens next.
• A supported main model: Fable, Opus 4.6 or later, Sonnet 4.6 or later, Haiku 4.5, or Haiku 5.5.
• Feature-flag fetching. Claude Code turns the advisor on through a feature flag it fetches from Anthropic. In a session where a variable that disables flag fetching is set — such as DISABLE_TELEMETRY — the advisor stays off, silently.

That last one deserves emphasis, because it catches privacy-conscious and enterprise-configured setups. If your organization sets DISABLE_TELEMETRY as a matter of policy, the advisor will never fire no matter how you configure it, and nothing will tell you why.

Troubleshooting: why your advisor isn't activating

Work this list top to bottom; it's roughly ordered by how often each one is the cause.

1. The advisor ranks below your main model. The commonest cause by far. Claude Code keeps the selection but doesn't attach it, and tells you — the message reads like Advisor set to Opus 4.8 / Note: Opus 4.8 is less capable than the current main model (Sonnet 5.5), so the advisor will not activate. Choose a more capable advisor, or switch to a smaller main model. In an interactive session the notification reads Advisor will not activate on the main model (advisor is less capable); subagents may still use it and may use more tokens · /advisor. Launching with --advisor in non-interactive mode writes the same warning to stderr and starts anyway; an interactive session writes it only to the debug log, which is why you can miss it entirely.
2. Your organization's availableModels allowlist excludes the model. Claude Code won't invoke it. Pick an allowed model with /advisor.
3. The API refused the pairing. Claude Code resent the request without the advisor, so there's no error to see — just no advisor calls. A new pick takes effect after /clear or /compact.
4. Fable needs the usage-credits consent. Run /model fable first, accept, then set the advisor.
5. Feature-flag fetching is off (e.g. DISABLE_TELEMETRY is set). Nothing will make the advisor work in that session.
6. You're not on the Anthropic API. Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform and Foundry don't have it.
7. CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 is set somewhere in your environment. It removes the /advisor command entirely and overrides any configured advisorModel.
8. Claude just didn't need it. On a short or straightforward task, zero advisor calls is the correct behaviour, not a bug. Add consult the advisor before you continue to a prompt to confirm the wiring works.

Turning it off

Two levels, depending on what you want.

Stop using it:

/advisor off

Or choose No advisor in the /advisor picker. Unsetting advisorModel has the same effect.

Disable the tool entirely: set CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1. The /advisor command becomes unavailable, any configured advisorModel is ignored, and the --advisor flag is accepted but has no effect. That's the lever for an organization that wants the feature gone rather than merely unselected.

Common mistakes

• Pairing a weaker advisor with a stronger main model. It silently does nothing to your main model. The advisor must rank at or above the main model, always.
• Assuming an alias pairing is stable. opus, sonnet and fable resolve to moving targets. If a pairing must hold across upgrades, pin a full model ID.
• Expecting it to work on Bedrock or Foundry. It's a server tool on the Anthropic API. The advisorModel key has no effect where the advisor isn't available.
• Setting DISABLE_TELEMETRY and then debugging the advisor for an hour. Flag fetching off means advisor off. Check this early.
• Using an advisor when you should switch models. If every turn is hard, an advisor is the expensive way to paper over a main model that's too small.
• Treating an Advising line as proof the advice was followed. Claude surfaces conflicts rather than obeying guidance that its own evidence contradicts. Read the guidance on anything that matters.
• Forgetting that subagents inherit it. If your token usage jumps after enabling an advisor, remember that delegated subtasks can escalate too.
• Running long sessions with an expensive advisor. Advisor reads aren't cached, so each call costs a full transcript. Compact more often, or use a cheaper advisor.

FAQ

What is the advisor tool in Claude Code?

The advisor tool lets Claude consult a second, typically stronger model at key moments during a task — before committing to an approach, when an error keeps recurring, and before declaring work done. The advisor receives the full conversation, including every tool call and result, and returns guidance that Claude applies before continuing. It runs server-side on Anthropic's infrastructure as a server tool, so it is available to both subscription and API-billed accounts. You choose which model advises; Claude decides when to call it. The feature is experimental and its behavior, pricing and availability may change.

How do I turn on the advisor in Claude Code?

There are three ways. Run /advisor with no argument to open a picker, or /advisor opus to set it directly — your pick is saved to advisorModel in your user settings and persists across sessions. Set "advisorModel": "opus" in a settings file to configure a default without opening a session. Or launch with claude --advisor opus to set it for one session without changing the saved setting. After the session starts you'll see a notification reading Advisor Tool (experimental) is on and may use more tokens.

Which advisor models can I pair with my main model?

The advisor must rank at or above your main model on Claude Code's capability ranking. Haiku 4.5 and Sonnet 4.6 accept Fable, Opus, Sonnet or Haiku 5.5. Opus 4.6 accepts Fable, Opus, Sonnet 5 or later, or Haiku 5.5. Sonnet 5 and Haiku 5.5 accept Fable, Opus 4.7 or later, Sonnet 5 or later, or Haiku 5.5. Opus 4.7 and Opus 4.8 accept Fable, Opus 4.7 or later, or Sonnet 5.5. Sonnet 5.5 accepts Fable, Opus 5 or later, or Sonnet 5.5. Opus 5 and Opus 5.5 accept Fable, or Opus 5 or later. Fable 5 accepts Fable 5.1 or Fable 5, and Fable 5.1 accepts only Fable 5.1. Haiku 4.5 can call the advisor but cannot act as one.

Does the advisor tool work on Bedrock, Vertex or Foundry?

No. The advisor is a server-executed tool that requires the Anthropic API. It is not available on Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform or Microsoft Foundry. Through an LLM gateway configured with ANTHROPIC_BASE_URL, availability depends on whether the gateway forwards the request intact to the Anthropic API. It also needs feature-flag fetching, so in a session where a variable such as DISABLE_TELEMETRY turns flag fetching off, the advisor stays off.

How much does the advisor tool cost?

Each advisor call has the advisor model read the whole conversation, so it consumes tokens at the advisor model's rates on top of your main model's usage. On API billing you pay the advisor model's input and output rates. On subscription plans advisor usage counts toward your plan's limits, except that a Fable advisor bills to usage credits on plans where Fable usage does. Because Claude calls the advisor at decision points rather than every turn, pairing a faster main model with a stronger advisor typically costs less than running the stronger model throughout. Advisor usage appears in the session totals shown by /usage.

Why isn't my advisor activating?

The most common cause is a pairing that ranks below your main model. Claude Code keeps the selection but doesn't attach the advisor, and tells you so — the /advisor output reads something like "Opus 4.8 is less capable than the current main model (Sonnet 5.5), so the advisor will not activate". Other causes: your organization's availableModels allowlist excludes the model, the API refused the pairing and the request was resent without the advisor, a Fable advisor still needs the one-time usage-credits consent, feature-flag fetching is off, or CLAUDE_CODE_DISABLE_ADVISOR_TOOL is set. Note that subagents whose own model satisfies the pairing may still use the advisor even when your main model can't.

Does turning the advisor on or off break my prompt cache?

No. Enabling or disabling the advisor mid-session does not invalidate your main model's prompt cache. Unlike switching models, toggling /advisor keeps the cached prefix intact, and the advisor's returned guidance is cached as part of the transcript on later turns. The advisor model's own read of the conversation is not cached, though — each advisor call processes the full transcript anew, with no reuse between calls.

Advisor tool or opusplan — which should I use?

They differ in when the stronger model runs and who starts it. opusplan runs the stronger model during plan mode and switches to Sonnet for execution, and you start it by entering plan mode — so it helps with the up-front plan and nothing after. The advisor runs at decision points throughout the task, and Claude calls it when it needs guidance — so it also helps when an error keeps recurring mid-task or when work should be checked before being declared done. If your failures are bad initial plans, use opusplan. If your failures are mid-task drift and premature completion, use the advisor. They are not mutually exclusive.