Advisor tool

The advisor tool gives Claude a second opinion on demand. Your session runs on one model, and at moments that matter (choosing an approach, going round in circles on the same error, deciding a task is finished) Claude can call a second, usually stronger model. The advisor reads the entire conversation, every tool call and result included, and sends back guidance that Claude weighs before carrying on.

You pick the advisor model. Claude decides when to call it. The call runs server-side on Anthropic's infrastructure as a server tool, so it works on both subscription and API-billed accounts.

Note: The advisor tool is experimental and needs the Anthropic API. It does not work on Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform or Microsoft Foundry.

Where it earns its keep

The advisor pays off on long jobs where most turns are mechanical but a handful of decisions shape the result. Good examples from my own work:

• A multi-day migration from one ORM to another, where Sonnet does the file-by-file edits and Opus weighs in on the schema strategy.
• A flaky integration test that keeps failing in slightly different ways.
• A feature I want independently checked before Claude tells me it is done.

It adds little on short tasks with nothing to plan, or on work where every single turn needs the strongest model. In that case just switch your main model.

Turning it on

Three ways to set the advisor, each enabling it for any session whose main model supports an advisor:

Once active, you see the notification Advisor Tool (experimental) is on and may use more tokens · /advisor.

The /advisor command

Run /advisor on its own to pick from a list, or name the model:

/advisor fable

Claude Code replies Advisor set to and the model name, and writes your choice to advisorModel in user settings. (A few cases are session-only; the settings reference lists them.)

Since v2.1.260 the command also works where there is no terminal picker: -p mode, the Agent SDK, the Desktop app and Remote Control. There, /advisor with no argument prints the current advisor and accepted aliases, /advisor <model> sets one, and /advisor off clears it.

Some edge cases:

• An advisor your organisation's availableModels list excludes is never invoked. Pick an allowed one.
• An advisor your current main model cannot use is still saved, and starts working once you /model to a compatible main model.
• If the API has already refused the advisor in this conversation, it stays off until /clear or /compact, even if you change models.

The advisorModel setting

{
  "model": "sonnet",
  "advisorModel": "opus"
}

This is my default for client repositories: Sonnet doing the typing, Opus on call.

The --advisor flag

claude --model haiku --advisor sonnet

The flag overrides advisorModel for that session. It is deliberately not listed in claude --help. Launch fails with an error when:

• the main model does not support an advisor;
• the requested model cannot act as an advisor (Haiku 4.5, for example);
• availableModels excludes it;
• you asked for Fable and still owe the usage-credits consent.

For a background session, any of those just starts the session without an advisor. If the advisor is valid but ranks below the main model, the session still starts, with a launch warning that the model cannot advise the main model (no warning in background sessions).

Which advisor models are allowed

Claude Code ranks models for the advisor role, and the advisor must rank at or above the main model. From the lowest-ranked main model upwards:

Version notes: Fable 5.1 needs v2.1.257; Sonnet 5.5 advising Opus 4.7 or 4.8 needs v2.1.287; Haiku 5.5 in either role needs v2.1.293. Fable also needs Fable access.

You can name the advisor by alias (fable, opus, sonnet), which tracks Claude Code's built-in default for that family, or by full ID such as claude-opus-5-5 or claude-haiku-5-5. Haiku 4.5 can call an advisor but cannot be one.

Subagents inherit the configured advisor and run the same ranking check against their own model.

How a bad pairing is handled

• Advisor ranks below the main model: Claude Code does not attach it to main-model requests and tells you so in the /advisor output and a notification. A subagent on a lower model may still use it.
• API refuses a pairing Claude Code allowed: the request is resent without the advisor. You see no error, just no advisor calls. A new choice made with /advisor then takes effect after /clear, /compact or in a new session.
• Unrecognised main or advisor model: no advisor is attached.

Fable as the advisor and usage credits

Where Fable bills to usage credits, a Fable advisor does too, and Claude Code will not apply it until you have given the one-time consent described in model configuration. Before that:

• /advisor fable and the picker refuse to save it and point you to /model fable.
• claude --advisor fable exits at launch with the same pointer (background sessions start without it).
• A Fable advisorModel already in settings is skipped, with a notification in interactive sessions.

To give consent, run /model fable, choose to continue on Fable (which also saves Fable as your main model), then set the advisor.

Pairings worth trying

When Claude calls it

Timing is the model's call, not a rule. In practice Claude reaches for the advisor before committing to a plan, after the same failure repeats, and before declaring victory.

You can ask directly, for example "check your migration plan with the advisor before touching the database". There is no setting to force or cap calls; steer frequency through your instructions or CLAUDE.md.

What the transcript shows

While a call is running you see an Advising line with the advisor's name. When it finishes, the line becomes one of:

Claude usually follows the advice, but not blindly. If a suggested step fails when tried, or the code on disk contradicts the advisor, Claude raises the conflict instead of pressing on.

Cost and caching

Each call has the advisor read the whole conversation, so it costs tokens at the advisor model's rates on top of your main model's usage:

• API billing: advisor input and output at the advisor model's prices.
• Subscriptions: counts toward your plan's usage limits, except a Fable advisor on plans where Fable bills to usage credits.

Because calls happen at decision points rather than every turn, a fast main model plus a strong advisor usually costs less than running the strong model all session. Advisor tokens show in /usage totals.

Toggling the advisor mid-session does not break your main model's prompt cache, unlike a model switch, and the guidance it returns is cached as part of the transcript. The advisor's own read of the conversation is never cached: each call processes the full transcript from scratch. On a very long session that adds up, which is another reason not to ask for a consultation every turn.

Requirements

• Anthropic API. Not available on Bedrock, Claude Platform on AWS, Agent Platform or Foundry. Through an LLM gateway it works only if the gateway passes the request through unchanged.
• 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. The advisor is switched on by a flag Claude Code fetches from Anthropic, so anything that turns fetching off, such as DISABLE_TELEMETRY, keeps it off. See environment variables.

Turning it off

For the session and your saved default:

/advisor off

Or choose No advisor in the picker. To remove the feature entirely, set CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1: /advisor disappears, advisorModel is ignored, and --advisor is accepted but does nothing.

Advisor versus the alternatives

Related

• Model configuration
• Subagents
• Manage costs
• Prompt caching