> ## Documentation Index
> Fetch the complete documentation index at: https://mux-advisor-0dak.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/agents/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`:

```markdown theme={null}
---
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.

```yaml theme={null}
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.