Advisors

Configure specialist models that agents can consult on hard problems

Overview

Advisors are configuration-as-code helpers that let the active agent hand off a specific tradeoff or decision to a stronger model. Each advisor is a single file: edit it to change the model, prompt, or per-call budget — no restart, no settings UI, no experiment toggles.

Advisors are opt-in by construction: the advisor tool only appears when at least one advisor file is loaded. If you don’t want them, you don’t need to do anything.

File Layout

Advisors mirror the Agent Skills loader pattern.

Scope	Path	Wins on name collision
Project	<workspace>/.mux/advisors/<name>/ADVISOR.md	✓ (project wins)
Global	~/.mux/advisors/<name>/ADVISOR.md

The directory name (<name>) is the canonical identity. Kebab-case, 1–64 characters, lowercase letters and digits only.

Example

/.mux/advisors/ml-fellow/ADVISOR.md:

---
description: Use for problems requiring deep mathematical reasoning in ML.
model: anthropic:claude-opus-4-5
thinking: high
max_uses_per_turn: 2
agents: [exec, plan]
---

You are reviewing a problem from an engineer building production ML systems.
Prioritize rigor over speed. State assumptions explicitly.

Frontmatter

Field	Required	Type	Default
description	yes	single-line	—
model	yes	provider:id	—
thinking	no	thinking level	model default
max_uses_per_turn	no	int | null	3 (null = unlimited)
max_output_tokens	no	int | null	unlimited
agents	no	string[]	available to all agents

The body (everything after the closing ---) is appended to the base advisor system prompt — use it to set a persona, voice, or focus area for that specific advisor.

How agents discover advisors

The advisor tool description includes the live catalog of configured advisors. The model selects one by name via the advisor_name parameter, so each tool call surfaces in the UI as advisor [ml-fellow] · done.

If the model invokes an advisor that has since been renamed or deleted, the tool returns an error result that lists the live catalog — the model can self-correct in the same turn.

Slash commands

The /advisor command surface is intentionally minimal:

Command	Effect
/advisor	List configured advisors plus any files that failed to parse.
/advisor init <name>	Scaffold .mux/advisors/<name>/ADVISOR.md from a working template.

The filesystem is the source of truth: there is no UI for editing advisors. Use your editor; changes take effect on the next stream send.

Per-agent gating

Use the agents: frontmatter field to restrict which agents see a given advisor. Omit it entirely (or pass an empty list) to make the advisor available to every agent that has the advisor tool in its policy.

agents: [exec, plan]

Per-agent gating composes with per-agent tool policies: if your agent’s policy disables the advisor tool entirely, no advisors are exposed regardless of their agents: field.

Budget knobs

Per-advisor caps run independently. Two advisors with max_uses_per_turn: 2 each can be invoked twice per turn, giving four total consultations. This lets a cheap “code-review” advisor and an expensive “ml-theorem” advisor coexist without either starving the other.

Set max_uses_per_turn: null to opt out of the cap for an advisor where the cost/quality tradeoff makes unlimited calls reasonable.

Migrating from the experiment

The experimental advisor in earlier nightlies used a single global model configured via Settings → Experiments → Advisor Tool, with per-agent enable toggles in the Tasks section. Both surfaces are gone.

To restore the previous behaviour with the new system:

1. Run /advisor init default from a workspace.
2. Edit <workspace>/.mux/advisors/default/ADVISOR.md to set model: to the model you used in Settings.
3. (Optional) Add agents: [exec, plan] if you only want exec/plan to see it.

Old cfg.advisorModelString, cfg.advisorThinkingLevel, cfg.advisorMaxUsesPerTurn, cfg.advisorMaxOutputTokens, and agentAiDefaults.<id>.advisorEnabled entries are silently ignored — they no longer affect anything.

Limitations

• The advisor sees the live transcript plus your question only — it has no tools. Surface the relevant context (file excerpts, errors, options) in the transcript before the call, or paste them into the question.
• Per-advisor max_uses_per_turn resets at the start of each stream turn, not per session.
• Advisor responses are billed under the advisor model bucket separately from the parent chat stream.