@alexeiled/claude-router 1.24.0 → 1.25.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +74 -0
- package/README.md +55 -7
- package/docs/architecture.md +30 -4
- package/docs/configuration.md +23 -14
- package/docs/evaluation.md +3 -3
- package/docs/native-router.md +12 -4
- package/docs/router-band.svg +140 -142
- package/docs/router-pane-classifier.svg +48 -31
- package/docs/router-pane-now.svg +162 -120
- package/docs/router-pane-policy.svg +79 -47
- package/docs/router-pane-routes.svg +8 -8
- package/docs/router-pane-usage-whatif.svg +14 -14
- package/docs/router-pane-usage.svg +20 -20
- package/docs/routing-modes.md +10 -8
- package/docs/user-guide.md +151 -22
- package/hooks/native-router.mjs +415 -88
- package/lib/activity-stats.mjs +23 -4
- package/lib/activity.mjs +7 -5
- package/lib/auto-engine.mjs +13 -6
- package/lib/auto-route.mjs +10 -4
- package/lib/band.mjs +35 -440
- package/lib/classifier-client.mjs +12 -8
- package/lib/config-file.mjs +7 -2
- package/lib/config.mjs +24 -9
- package/lib/cost.mjs +5 -1
- package/lib/costs.mjs +4 -2
- package/lib/decisions.mjs +13 -9
- package/lib/display.mjs +71 -20
- package/lib/facts.mjs +3 -0
- package/lib/failover.mjs +55 -0
- package/lib/modes.mjs +8 -4
- package/lib/panel.mjs +75 -2167
- package/lib/policy.mjs +7 -6
- package/lib/replay-trace.mjs +5 -2
- package/lib/replay.mjs +7 -1
- package/lib/route-line.mjs +46 -0
- package/lib/route.mjs +51 -32
- package/lib/savings.mjs +14 -3
- package/lib/subagents.mjs +41 -11
- package/lib/subcommands.mjs +60 -0
- package/lib/ui/fallback.mjs +22 -0
- package/lib/ui/graphical/band.mjs +256 -0
- package/lib/ui/graphical/charts.mjs +163 -0
- package/lib/ui/graphical/classifier.mjs +153 -0
- package/lib/ui/graphical/frame.mjs +231 -0
- package/lib/ui/graphical/kit.mjs +156 -0
- package/lib/ui/graphical/meter.mjs +25 -0
- package/lib/ui/graphical/now.mjs +357 -0
- package/lib/ui/graphical/policy.mjs +56 -0
- package/lib/ui/graphical/routes.mjs +264 -0
- package/lib/ui/graphical/squares.mjs +29 -0
- package/lib/ui/graphical/usage.mjs +376 -0
- package/lib/ui/model/band.mjs +441 -0
- package/lib/ui/model/classifier.mjs +308 -0
- package/lib/ui/model/draft.mjs +62 -0
- package/lib/ui/model/format.mjs +41 -0
- package/lib/ui/model/frame.mjs +359 -0
- package/lib/ui/model/now.mjs +421 -0
- package/lib/ui/model/policy.mjs +194 -0
- package/lib/ui/model/routes.mjs +392 -0
- package/lib/ui/model/usage-agents.mjs +311 -0
- package/lib/ui/model/usage-breakdown.mjs +237 -0
- package/lib/ui/model/usage-shared.mjs +58 -0
- package/lib/ui/model/usage.mjs +330 -0
- package/lib/ui/terminal/band.mjs +253 -0
- package/lib/ui/terminal/classifier.mjs +150 -0
- package/lib/ui/terminal/frame.mjs +169 -0
- package/lib/ui/terminal/kit.mjs +162 -0
- package/lib/ui/terminal/now.mjs +293 -0
- package/lib/ui/terminal/policy.mjs +55 -0
- package/lib/ui/terminal/routes.mjs +167 -0
- package/lib/ui/terminal/usage.mjs +363 -0
- package/lib/ui/terminal/wrap.mjs +37 -0
- package/lib/ui/tokens.mjs +106 -0
- package/lib/usage.mjs +5 -5
- package/lib/view.mjs +5 -2
- package/package.json +4 -2
- package/types/index.d.ts +17 -0
package/docs/user-guide.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
## Start a session
|
|
4
4
|
|
|
5
|
-
Install the plugin from its marketplace, or load a checkout with `--plugin-dir /path/to/claude-router`:
|
|
5
|
+
The router needs Claude Code 2.1.321 or newer. Install the plugin from its marketplace, or load a checkout with `--plugin-dir /path/to/claude-router`:
|
|
6
6
|
|
|
7
7
|
```sh
|
|
8
8
|
claude plugin marketplace add alexei-led/claude-router
|
|
@@ -27,18 +27,60 @@ In Claude Code:
|
|
|
27
27
|
- **OpenAI**: an OpenAI API key. The prompt text goes to OpenAI.
|
|
28
28
|
- **Ollama**: no credential. Run `ollama serve` and pull the model; the prompt text stays on this machine.
|
|
29
29
|
3. To use another classifier, open the pane's **Classifier** tab and select its row. See [Choose the classifier](#choose-the-classifier).
|
|
30
|
-
4. Check the band above the prompt: `Routing on · ready`.
|
|
30
|
+
4. Check the band above the prompt: `Routing on · ready`. With `table` or `shadow`, a model not used by any tier or enabled activity override starts with routing off; the band says why. With `auto`, any model in the selected profile's catalog can start with routing on. `/router auto` turns routing on for the current engine if it is off. In `table`, classifier votes and cache economics gate tier changes; in `auto`, the capability target, routed demand and move gates govern changes. See [routing engine settings](configuration.md#routing-engine).
|
|
31
31
|
|
|
32
|
-
Keys are stored as sensitive plugin options. Do not paste them into a model conversation. The [configuration guide](configuration.md) covers settings and migrations.
|
|
32
|
+
The desktop app, VS Code and mobile cannot open the `/plugin configure` dialog, so their **Set up** and **Credentials → Edit** show a card with a line to run in a terminal: it asks for the key without showing it or keeping it in your shell history and saves it with `claude plugin configure <id> --values-stdin`; **Copy command** copies it, then run `/reload-plugins`. Keys are stored as sensitive plugin options. Do not paste them into a model conversation. The [configuration guide](configuration.md) covers settings and migrations.
|
|
33
|
+
|
|
34
|
+
<picture>
|
|
35
|
+
<source media="(prefers-color-scheme: dark)" srcset="images/desktop-key-card-dark.png">
|
|
36
|
+
<img src="images/desktop-key-card-light.png" alt="The Set up card: a command to run in a terminal that saves the classifier key without showing it, with Copy command and Done buttons." width="560">
|
|
37
|
+
</picture>
|
|
33
38
|
|
|
34
39
|
In this guide, `router.json` means the selected router file. For example, with `CLAUDE_ROUTER_PROVIDER=zai`, edits go to `zai-router.json`.
|
|
35
40
|
The pane shows its provider and file path.
|
|
36
41
|
|
|
37
42
|
## Read the status band
|
|
38
43
|
|
|
39
|
-
|
|
44
|
+
### In the desktop app, VS Code and mobile
|
|
45
|
+
|
|
46
|
+
<picture>
|
|
47
|
+
<source media="(prefers-color-scheme: dark)" srcset="images/desktop-band-routed-dark.png">
|
|
48
|
+
<img src="images/desktop-band-routed-light.png" alt="The desktop band in one row: a tier meter, Opus 5.5 xhigh, the code activity and the reason "clearly stronger" on the left; context and cache readings, the Pin to a tier dropdown and the Router button on the right.">
|
|
49
|
+
</picture>
|
|
50
|
+
|
|
51
|
+
*Rendered from the real component tree with a browser's layout and approximate theme colours; not a screenshot of the Claude app.*
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
The band above the prompt is drawn natively as one fixed row. Nothing appears on hover: every control is on the row itself. Colours come from the app's theme, so the band reads in light and dark.
|
|
56
|
+
|
|
57
|
+
- **Left**: a small tier meter icon, then the route (the model and effort for this turn), the activity, the reason, the classifier's support and the switch cost, in the words of the [terminal band](#in-the-terminal). When the window narrows, the left side gives way first.
|
|
58
|
+
- **Right**: the context and cache readings, a **Pin to a tier** dropdown and the **Router** button, which opens the pane. The dropdown lists one entry per tier, not every model; for a model no tier routes to, such as Sonnet on the default routes, turn routing off and use `/model`. With `table` or `shadow` each entry names the route that tier runs, whatever the routing mode; with `auto` it names the tier (`Low tier`), because Auto picks the cheapest capable model when the turn runs. A pin forces that tier for the next turn only. On mobile a pending pin also keeps its own `⏵ next` text and **✕** beside the dropdown, since an app may not draw the dropdown.
|
|
59
|
+
- **One control per state**: **Turn on** when routing is off, **Set up** when the active classifier lacks credentials, **Fix** when routing is unavailable. While routing is on, turn it off from the pane's header (**On** / **Off**) or with `/router off`.
|
|
60
|
+
- **Session row**: the second row (plan windows and the session's cost against no routing) is no longer a band button. Turn it on with **Show session row in band** on the pane's Now tab; Router remembers the choice across sessions.
|
|
61
|
+
|
|
62
|
+
While subagents run, a row of buttons under the band lists them, one per agent with the model, type and task (`agents 2 ▸ ■ Haiku 5.5 Explore · retry usages ●`). Press one to open that agent's transcript in the main view. The row lists three agents and then `+N`, and keeps the first agent and the count when the window narrows. It shows only while an agent runs, and never a teammate. In an agent's transcript the band has a **Back** button (`◂ main` in the terminal, **← Main** on these surfaces) that returns to the main conversation. The agent's model and who picked it are described under the terminal band.
|
|
63
|
+
|
|
64
|
+
<picture>
|
|
65
|
+
<source media="(prefers-color-scheme: dark)" srcset="images/desktop-band-agents-dark.png">
|
|
66
|
+
<img src="images/desktop-band-agents-light.png" alt="The desktop band with a second row listing two running subagents as buttons, one moved to Haiku 5.5 and one on Sonnet 5.5.">
|
|
67
|
+
</picture>
|
|
68
|
+
|
|
69
|
+
<picture>
|
|
70
|
+
<source media="(prefers-color-scheme: dark)" srcset="images/desktop-band-setup-dark.png">
|
|
71
|
+
<img src="images/desktop-band-setup-light.png" alt="The desktop band with a missing classifier key: a warning "Jev: no API key", the model kept, and a Set up button beside Router.">
|
|
72
|
+
</picture>
|
|
73
|
+
|
|
74
|
+
<picture>
|
|
75
|
+
<source media="(prefers-color-scheme: dark)" srcset="images/desktop-band-off-dark.png">
|
|
76
|
+
<img src="images/desktop-band-off-light.png" alt="The desktop band with routing off: Sonnet 5.5, "routing off", and a Turn on button beside Router.">
|
|
77
|
+
</picture>
|
|
78
|
+
|
|
79
|
+
### In the terminal
|
|
40
80
|
|
|
41
|
-
|
|
81
|
+
The terminal band is one line above the prompt. Its text, secondary text, accents, success, warning and error colours are your Claude Code theme's own, so a light theme reads as well as a dark one; tiers, models and activities keep their own colours. The line ends with a **Router** button that opens the pane, drawn as `[ Router ]` when the band has room for the brackets without dropping a reading or a hover control, and as a plain `Router` otherwise. When the band is narrow, the less important parts drop first: classifier figures and the switch cost, then context and cache, then the activity, then the reason. The meter and the model always stay, except behind a classifier warning: the warning and its **Set up** button come first, and the route gives way to them.
|
|
82
|
+
|
|
83
|
+

|
|
42
84
|
|
|
43
85
|
Read the first line from left to right:
|
|
44
86
|
|
|
@@ -64,9 +106,9 @@ Read the first line from left to right:
|
|
|
64
106
|
|
|
65
107
|
**Turn on** and **Fix** sit next to the model and stay at any width.
|
|
66
108
|
|
|
67
|
-
|
|
109
|
+
#### The hover controls and two rows
|
|
68
110
|
|
|
69
|
-
While routing is on, hover over the band
|
|
111
|
+
While routing is on, hover over the band and its controls appear on the same row, in the room it has free, over its readings or after **Router**, and in both when one stretch is too small: a pin per tier, low to high, each named by what it runs (`▂▄ Haiku·high`); **Turn off**; and **2 rows** or **1 row**. Nothing moves: the meter and model, any **Set up**, **Details** or ✕ on the band, and **Router** stay where they are. A pin forces that tier for the next turn only. On a narrow band the pins lose their model names first. With one row, **2 rows** goes next, then the pins, and **Turn off** stays longest. With two rows, the pins go, then **Turn off**, and **1 row** stays longest. A band with no room for even one control shows none on hover; the pane's Now tab always has **band: 1 row** or **band: 2 rows** on its SESSION line, which does the same as the band's button. The hover controls need a pointer: from the keyboard, run `/router off`, or open the pane and press `f`; the SESSION line's toggle also takes a press.
|
|
70
112
|
|
|
71
113
|
**2 rows** adds the session under the route, in the same numbers as the pane's SESSION block. On a Claude plan it leads with the plan windows Claude Code reports:
|
|
72
114
|
|
|
@@ -85,36 +127,94 @@ When the row is short, the reset time, the counts and the words drop first; the
|
|
|
85
127
|
|
|
86
128
|
The band steps aside while a survey needs the space.
|
|
87
129
|
|
|
88
|
-
Inside a turn the router checks the route again as the work changes; see [Changes during a task](#changes-during-a-task). A subagent gets at most one model, when it starts, and keeps it for every step: For the Anthropic profile, these are Haiku for exploration, Opus for clearly hard tasks, and Sonnet for the rest. Other profiles have [their own defaults](providers.md#activity-overrides). An agent that pins a model in its definition keeps it, unless it sets `modelRouting: auto`. The Usage tab's **SUBAGENTS** section shows what each agent type ran on and cost, and the Now tab adds this session's agents to its total. See [Subagent routing](configuration.md#subagent-routing).
|
|
130
|
+
Inside a turn the router checks the route again as the work changes; see [Changes during a task](#changes-during-a-task). A subagent gets at most one model, when it starts, and keeps it for every step: For the Anthropic profile, these are Haiku for exploration, Opus for clearly hard tasks, and Sonnet for the rest. Other profiles have [their own defaults](providers.md#activity-overrides). An agent that pins a model in its definition keeps it, unless it sets `modelRouting: auto`. An agent started by a workflow script is routed like any other, unless it sets its own model or you set `workflow-subagent` to `null` under `subagents.types`, as in [Subagent routing](configuration.md#subagent-routing). A resumed agent keeps the model of its first start. The Usage tab's **SUBAGENTS** section shows what each agent type ran on and cost, and the Now tab adds this session's agents to its total. See [Subagent routing](configuration.md#subagent-routing).
|
|
89
131
|
|
|
90
132
|
In a subagent's transcript the band names the model the agent runs on and who picked it. `agent ■ Haiku 5.5 ↓ from Opus 5.5 (Claude Code’s pick)` means the router chose a cheaper model than Claude Code would have; `↑` means a higher declared strength rank. When ranks are unknown, a model change has no strength direction. A hollow `□` means the agent ran on Claude Code's pick, because the router agreed or did not route it, and says why: `agent □ Opus 5.5 = Claude Code’s pick: the workflow sets it`. A narrow band drops the comparison first. The band falls back to `agent · model chosen at spawn` when the router has no record of the agent, such as after a plugin reload, and to `agent · keeps its own model (subagent routing off)`.
|
|
91
133
|
|
|
92
134
|
## Open the router pane
|
|
93
135
|
|
|
94
|
-
Run `/router` or select **Router** above the prompt. Without a UI surface, as in `claude -p`, `/router` prints a short status instead. The pane has five tabs. Select a tab or press its digit while the pane has focus.
|
|
136
|
+
Run `/router` or select **Router** above the prompt. Without a UI surface, as in `claude -p`, `/router` prints a short status instead. The pane has five tabs. Select a tab or press its digit (1 to 5) while the pane has focus.
|
|
137
|
+
|
|
138
|
+
### The pane in the desktop app, VS Code and mobile
|
|
139
|
+
|
|
140
|
+
The pane is drawn natively. From the top it has:
|
|
141
|
+
|
|
142
|
+
- a **header**: `Router`, the classifier's status, and an **On** / **Off** switch for routing;
|
|
143
|
+
- the **tabs**: Now, Routes, Policy, Classifier and Usage, without digits in their labels (the hotkeys 1 to 5 still work);
|
|
144
|
+
- one **warnings** slot under the tabs, shown on every tab: an ignored project config, a native fallback, or missing classifier credentials;
|
|
145
|
+
- the tab's content, then the **save bar** last.
|
|
146
|
+
|
|
147
|
+
What each tab shows:
|
|
148
|
+
|
|
149
|
+
- **Now**: cards for Next turn (the route, the reason, a pin button per tier, named by route or, with `auto`, by tier), Plan usage (on a Claude plan), Context, This session and, once the session has any, Recent decisions. The Next turn and This session cards carry the same facts as the terminal blocks below. The tab also holds the **Show session row in band** setting.
|
|
150
|
+
|
|
151
|
+
<picture>
|
|
152
|
+
<source media="(prefers-color-scheme: dark)" srcset="images/desktop-pane-now-dark.png">
|
|
153
|
+
<img src="images/desktop-pane-now-light.png" alt="The Now tab of the pane: the next turn route with a pin button per tier, plan usage bars, context and cache, and this session's cost against no routing with a strip of replies by tier." width="560">
|
|
154
|
+
</picture>
|
|
155
|
+
|
|
156
|
+
- **Routes**: a grid of tiers by activities, with an edit card under it for the selected cell.
|
|
157
|
+
|
|
158
|
+
<picture>
|
|
159
|
+
<source media="(prefers-color-scheme: dark)" srcset="images/desktop-pane-routes-dark.png">
|
|
160
|
+
<img src="images/desktop-pane-routes-light.png" alt="The Routes tab: a grid of tiers by activities with the models they run, an editor card for code at High, and an Unsaved changes table with Discard and Save." width="560">
|
|
161
|
+
</picture>
|
|
162
|
+
|
|
163
|
+
- **Policy**: form cards for Routing mode, Switching down, Switching up, Activities and Credits, and a Settings file card with the `router.json` path.
|
|
164
|
+
|
|
165
|
+
<picture>
|
|
166
|
+
<source media="(prefers-color-scheme: dark)" srcset="images/desktop-pane-policy-dark.png">
|
|
167
|
+
<img src="images/desktop-pane-policy-light.png" alt="The Policy tab: cards for routing mode, switching down and up, activities and credits, each with a dropdown and one line of help, and the settings file path." width="560">
|
|
168
|
+
</picture>
|
|
169
|
+
|
|
170
|
+
- **Classifier**: a full card for the active classifier (deadline, wait, health, credentials) and compact rows for the others under **Other classifiers**, then **Across sessions**.
|
|
171
|
+
|
|
172
|
+
<picture>
|
|
173
|
+
<source media="(prefers-color-scheme: dark)" srcset="images/desktop-pane-classifier-dark.png">
|
|
174
|
+
<img src="images/desktop-pane-classifier-light.png" alt="The Classifier tab: a card for the active classifier with its host, deadline and health, a row per other classifier with Set up and Use buttons, and the agreement counts across sessions." width="560">
|
|
175
|
+
</picture>
|
|
176
|
+
|
|
177
|
+
- **Usage**: period buttons, then Summary, Trend, Breakdown, Worth a look, Subagents, About these numbers and **Delete history**.
|
|
178
|
+
|
|
179
|
+
<picture>
|
|
180
|
+
<source media="(prefers-color-scheme: dark)" srcset="images/desktop-pane-usage-dark.png">
|
|
181
|
+
<img src="images/desktop-pane-usage-light.png" alt="The Usage tab: period buttons, a summary of cost against no routing, a breakdown by activity, a worth-a-look note, and a subagents table." width="560">
|
|
182
|
+
</picture>
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
Unsaved Routes and Policy changes sit in an **Unsaved changes** card at the bottom, a table of each setting before and after with **Discard** and **Save**; the last save and **Undo** follow it. **?** opens an **About the router** card. When the classifier needs attention, the header says so and the warning under the tabs says what to do. Saving, undoing and the numbers behind each card follow the terminal descriptions below.
|
|
186
|
+
|
|
187
|
+
At a phone's width the same trees narrow: the band shortens its route to fit and the cards truncate their notes.
|
|
188
|
+
|
|
189
|
+
<img src="images/mobile-band-and-now-dark.png" alt="The band and the Now tab at a phone width of 390 pixels: the band shortens its route to fit, and the cards stack with shorter text." width="300">
|
|
190
|
+
|
|
191
|
+
### The pane in the terminal
|
|
192
|
+
|
|
95
193
|
|
|
96
194
|
| Tab | What it answers |
|
|
97
195
|
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
98
|
-
| 1 Now | What runs next turn, and why, with a **pin**
|
|
196
|
+
| 1 Now | What runs next turn, and why, with a **pin** dropdown; the plan windows; this session's cost against no routing; context and cache. |
|
|
99
197
|
| 2 Routes | Which model runs: one grid of tiers by activities, the activity routing mode, and an editor for the selected cell. |
|
|
100
198
|
| 3 Policy | How readily the router changes models: the start tier, going down, going up, the activity threshold, the credits cap; the `router.json` path. |
|
|
101
199
|
| 4 Classifier | Which classifier to ask: one row per classifier to compare, the active one's deadline, wait, health and credentials, and the counts kept across sessions. |
|
|
102
200
|
| 5 Usage | What routing cost against no routing this session, today, over 7 or 30 days, this month or in all: by activity, model or tier, and what is worth a look. |
|
|
103
201
|
|
|
104
|
-
|
|
202
|
+
Under the tab row, one slot shows the warnings on every tab: a project config that was ignored, a native fallback, and missing classifier credentials. They no longer sit inside the Now tab's NEXT TURN block.
|
|
203
|
+
|
|
204
|
+
The top line of every tab, `ROUTER [ ◉ on ] [ ○ off ] Jev ready · 347 ms`, shows the routing mode, switches it, and says whether the classifier is ready. Press `o` or `f` while the pane has focus. The tabs under it carry their digits, `[ 1 Now ] [ 2 Routes ] …`, and **?** shows what the numbers mean above the tab. In a pane too narrow for them, the tabs drop the digits (the keys still work), and then **?** moves to the end of the top line. While the warnings under the tabs name missing classifier credentials, the top line says `see below` instead of repeating them. When routing is unavailable, the top line reads `ROUTER unavailable Claude’s model is kept` with the reason under it, and offers no on or off: see [Troubleshooting](#troubleshooting).
|
|
105
205
|
|
|
106
|
-

|
|
107
207
|
|
|
108
|
-
The **Now** tab has four blocks, each with its name in capitals.
|
|
208
|
+
The **Now** tab has four blocks, each with its name in capitals. From 72 columns wide each block sits in a single-line box with its name as the first line; a narrower pane draws them as plain lines. The Policy controls and the active classifier on the Classifier tab are boxed the same way.
|
|
109
209
|
|
|
110
|
-
**NEXT TURN** answers "what runs next turn, and why". The first line is the tier meter, the model and effort, and the classifier's activity with its share, such as `code 84% debug 8%`. When an activity override runs, a line under it names the tier's own route. **why** gives the reason in the band's words and, beside it, the classifier's support against the bar the policy set and the switch cost: `↑ clearly stronger Jev 88% ≥ 82% · switch ≈ $0.48`. **pin**
|
|
210
|
+
**NEXT TURN** answers "what runs next turn, and why". The first line is the tier meter, the model and effort, and the classifier's activity with its share, such as `code 84% debug 8%`. When an activity override runs, a line under it names the tier's own route. **why** gives the reason in the band's words and, beside it, the classifier's support against the bar the policy set and the switch cost: `↑ clearly stronger Jev 88% ≥ 82% · switch ≈ $0.48`. **pin next turn to a tier** names the model that runs now, and one dropdown under it pins: **Pin to a tier**, then one entry per tier, low to high, each named by what it runs, such as `▂▄ Haiku·high 3%`, with the support the classifier gave it on the last turn; `▶` marks the tier that runs now. Picking a tier forces it for the next turn only, and the dropdown shows the pending pin until it applies; pick **No pin** to drop it. A line under the dropdown points to `/model`, with routing off, for models no tier routes to. With routing off, the block names Claude's model, `routing off · /model choice`, and the pins say they need routing on; nothing from an earlier routed turn stays.
|
|
111
211
|
|
|
112
212
|
**PLAN** appears on a Claude plan: Claude Code's 5-hour and 7-day windows as gauges, with when each resets. They turn yellow at 75% and red at 90%.
|
|
113
213
|
|
|
114
214
|
**SESSION** sums this session, the main thread and its subagents: `since 14:18 · 86 replies · 6 agents · 9 switches`, and `● 1 running` while a subagent is in the middle of a turn (an agent that waits on its own background command is not counted until it resumes). The counts include the replies of the turn still running.
|
|
115
215
|
|
|
116
216
|
```text
|
|
117
|
-
SESSION since 14:18 · 86 replies · 6 agents · 9 switches ● 1 running
|
|
217
|
+
SESSION since 14:18 · 86 replies · 6 agents · 9 switches ● 1 running [ band: 2 rows ]
|
|
118
218
|
≈$8.97 API estimate · plan quota, not a charge [ Usage ]
|
|
119
219
|
−$4.09 (−31%) vs unrouted ≈$13.06
|
|
120
220
|
main ≈$6.45 ████████████████ −$4.17 vs Opus 5.5 · xhigh
|
|
@@ -310,7 +410,22 @@ On the running task:
|
|
|
310
410
|
|
|
311
411
|
These thresholds are starting values. They are not tuned on data yet.
|
|
312
412
|
|
|
313
|
-
On Claude Code 2.1.322 an effort that the router changed inside a turn was not sent in the 6 cases found, while a changed model was, so the band and the decision record can name an effort that did not run. See [What we do not know yet](activity-routing.md#what-we-do-not-know-yet).
|
|
413
|
+
On Claude Code 2.1.322 an effort that the router changed inside a turn was not sent in the 6 cases found, while a changed model was, so the band and the decision record can name an effort that did not run. Claude Code sends an effort change on a tool-result step only when `CLAUDE_CODE_MODEL_CAPABILITIES=per_turn_effort` is set in its environment; the router does not set it. See [What we do not know yet](activity-routing.md#what-we-do-not-know-yet).
|
|
414
|
+
|
|
415
|
+
### When a model fails
|
|
416
|
+
|
|
417
|
+
When a turn ends on an API error that is the model's fault, the router holds that model out of routing for a while, so the next turns run another model. A toast says so once, such as `Opus 5.5 held out of routing: overloaded, 5 min`.
|
|
418
|
+
|
|
419
|
+
| Error Claude Code reports | Held out for |
|
|
420
|
+
| ------------------------- | ------------ |
|
|
421
|
+
| `rate_limit` | 5 minutes |
|
|
422
|
+
| `overloaded` | 5 minutes |
|
|
423
|
+
| `server_error` | 2 minutes |
|
|
424
|
+
| `model_not_found` | 1 hour |
|
|
425
|
+
|
|
426
|
+
A billing error, a rejected key or request, a cut-off answer and an unknown error hold nothing: another model would not help. Claude Code reports no retry-after, so the times are fixed.
|
|
427
|
+
|
|
428
|
+
While a model is held out, a turn whose route runs it, a pinned turn too, runs the nearest tier's route on another model at the turn's activity; of two tiers as near, the stronger. The switch toast, the band and the route line show `! held out`. The turn's own tool calls do not move it onto a held model either. When the hold ends, the next turn returns to the route it held out without waiting for votes or a checkpoint. A route that is not its tier's configured route, kept from before a routing mode change or a route edit, or your own model when no tier routes to it, is the exception: when the tier's configured route runs another model, that route takes over at once and stays after the hold. The failed request is not sent again: Claude Code reports the error after the turn has ended. A subagent's failure holds nothing. A compaction keeps the holds; a new session starts without them. With `"routingEngine": "auto"` no model is held and no toast shows: that engine does not route around holds.
|
|
314
429
|
|
|
315
430
|
### Read the activity on the pane
|
|
316
431
|
|
|
@@ -328,20 +443,32 @@ On the **Classifier** tab, **ACROSS SESSIONS · since the last reset** shows the
|
|
|
328
443
|
| Command or action | Result |
|
|
329
444
|
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
|
330
445
|
| `/router` | Open the pane. |
|
|
331
|
-
| `/router auto` |
|
|
446
|
+
| `/router auto` | Turn routing on for this session using the engine selected in the profile. It does not change the engine. |
|
|
332
447
|
| `/router off` | Turn routing off and keep Claude's selected model. |
|
|
333
448
|
| `/router pin <micro\|low\|medium\|high>` | Pin the next turn and its tool continuations. Routing on must already be enabled. |
|
|
334
449
|
| `/router activities <off\|on>` | Set the [activity routing](#route-by-activity) mode. Saved to `router.json` at once; **Undo** reverts it. |
|
|
335
450
|
| `/router mode <cost\|balanced\|quality>` | Set this session's [routing mode](routing-modes.md) from the next turn. A resume keeps it. |
|
|
336
451
|
| `/router mode default` | Clear the session's mode: the project's or the profile's applies again. |
|
|
337
452
|
| `/router decisions [n]` | Print this session's last `n` routing decisions, 20 by default. See [Routing decisions](#routing-decisions). |
|
|
338
|
-
| `/
|
|
453
|
+
| `/router line <off\|moves\|all>` | Choose when a turn leaves a [route line](#the-route-line) in the transcript. `moves` is the default. Kept across sessions. |
|
|
454
|
+
| `/model <name>` | Select a model and turn routing off. Use `/router auto` to turn it back on. The model picker and a model set from the SDK, an IDE or Remote Control do the same. |
|
|
339
455
|
| **Turn on** / **Turn off** on the band | The same as `/router auto` and `/router off`. |
|
|
340
456
|
| **on** / **off** on the pane (`o` / `f`) | The same as `/router auto` and `/router off`. |
|
|
341
457
|
| **pin** on the Now tab | Pin that tier for the next turn. Routing on must already be enabled. |
|
|
342
458
|
|
|
459
|
+
Type `/router` and a space, then a letter, and the prompt offers the words that start with it (`auto`, `off`, `pin <tier>`, `mode <mode>`, `activities <off|on>`, `line <off|moves|all>`, `decisions [n]`, `trace export`). After `pin `, `mode `, `activities ` or `line ` it offers the values; `pin` names the model each tier runs. The rows come after Claude Code's own. They are drawn by the surface's prompt box, so a surface that does not raise the typeahead shows none.
|
|
460
|
+
|
|
343
461
|
With `table` or `shadow`, a routing mode moves each tier's route one step toward cost or quality; pins and `micro` turns are not moved. With opt-in `auto`, the mode changes the demand margin instead, and a tier pin uses exact demand without a margin. The band and the Now tab show the mode and where it comes from, such as `cost (session)`. When the mode kept the cell's model and changed only its effort, as `cost` does for Opus at `high`, the band adds `effort only`: the cost estimates price the same tokens on both routes, so that change shows no difference there, though real output length can differ. A change applies from the next turn, and the route in use moves only through the usual checks, so on a running task a cheaper route can wait a few requests and for a checkpoint. **Mode** on the Policy tab sets the profile's mode. See [Routing modes](routing-modes.md).
|
|
344
462
|
|
|
463
|
+
### The route line
|
|
464
|
+
|
|
465
|
+
After a routed turn, Router can add one dim row at the end of the transcript that says which model and effort ran and why, in the band's words: `▂▄▆█ Sonnet 5.5 · high ↓ cheaper fits code`. A narrow window drops the classifier's support, then the activity, then the reason; the route stays.
|
|
466
|
+
|
|
467
|
+
- `/router line moves` (the default) adds the row only when the turn ran another model or effort than the last routed turn, and on a session's first routed turn.
|
|
468
|
+
- `/router line all` adds it after every routed turn, and `/router line off` never.
|
|
469
|
+
|
|
470
|
+
No row is added for an interrupted turn, a subagent's turn, or a turn while routing is off. The row is for you: the model never reads it, `claude --resume` does not bring earlier rows back, and a compaction ends the rows above it. The setting has no control in the pane; it is kept in the plugin's store across sessions, not in `router.json`.
|
|
471
|
+
|
|
345
472
|
### Routing decisions
|
|
346
473
|
|
|
347
474
|
Each routed turn adds rows to the session's decision record in `$.store` (`decisions:v1:<session id>`): one when the turn starts, one per classifier review or tool-based move inside it, and one when it ends. A row holds the prompt's origin (`composer`, `task-notification`, …, or `unknown`), the classifier's tier and activity with their shares, whether it counted as the running task, the tier, activity, route and reason chosen, and at the end the turn's tool bucket and how many replies were priced. It holds no prompt, tool or file text. The route is the one chosen, which is not always the one sent; see [Changes during a task](#changes-during-a-task). `/router decisions [n]` prints them. For a tier move or an activity move up, taken or held, the row also holds the probability mass the policy compared and the bar it compared it with, printed after the reason: `(upgrade-pending 52% vs bar 79%)`. A held move can show a mass above its bar: it then waits for a second vote or for a checkpoint. On `downgrade-pending` the mass is the support for the classifier's own choice; a tier between it and the running one can be closer to its bar. A `jump`, a move on the turn's own tool calls and a context or availability override show neither number. Each session keeps its newest 60 rows; records of the 20 most recent other sessions stay, for at most 30 days. **Delete history** deletes them all.
|
|
@@ -405,7 +532,7 @@ The three Clef models take the same request and the same Cloudflare credentials,
|
|
|
405
532
|
|
|
406
533
|

|
|
407
534
|
|
|
408
|
-
You can save credentials for all of them; only the active one is asked. The **Classifier** tab has one row per classifier, as columns to compare: `◉` marks the active one; then where the prompt goes (`this machine` for Ollama); its last checked-in [activity probe](evaluation.md#activity-probe-set), the test prompts with a known activity it answered right, such as `70/70`, and their p95 wait; and whether its credentials are complete. A row that lacks one names it, such as `○ no API token`, and has its own **Set up** button. The probe columns read `—` when you configured a model other than the probed one.
|
|
535
|
+
You can save credentials for all of them; only the active one is asked. The **Classifier** tab has one row per classifier, as columns to compare: `◉` marks the active one; then where the prompt goes (`this machine` for Ollama); its last checked-in [activity probe](evaluation.md#activity-probe-set), the test prompts with a known activity it answered right, such as `70/70`, and their p95 wait; and whether its credentials are complete. A row that lacks one names it, such as `○ no API token`, and has its own **Set up** button. In a pane too narrow for the widest row, about 80 columns, each classifier takes two lines instead: its name, status and **Set up**, then where the prompt goes and its probe result, such as `api.cloudflare.com · 69/70 · p95 883 ms`. The probe columns read `—` when you configured a model other than the probed one.
|
|
409
536
|
|
|
410
537
|
Select a row to switch. The choice is written to `router.json` at once and applies from the next turn. **Undo** in the status bar returns to the previous classifier. A turn that is already being classified finishes with the classifier it started with. The new classifier starts with a clean failure count.
|
|
411
538
|
|
|
@@ -413,7 +540,7 @@ Under the rows, a block for the active classifier:
|
|
|
413
540
|
|
|
414
541
|
- **Deadline:** 500, 1,000, 1,500, 3,000, or 5,000 ms for the active classifier's total advice attempt, including any retry. Each classifier keeps its own deadline, saved at once, with **Undo**. Beside it is the classifier's p95 wait: across sessions, such as `p95 ≤ 400 ms over 15 turns`, or from its probe before any turn. It turns yellow when the wait is slower than the deadline. Past the deadline the turn keeps its model.
|
|
415
542
|
- **Sends** names the service that receives prompt text. **Health** shows a pause, recent failures, and the last wait.
|
|
416
|
-
- **Credentials**: **Edit** opens Claude Code's secure plugin configuration, where you enter them.
|
|
543
|
+
- **Credentials**: **Edit** opens Claude Code's secure plugin configuration, where you enter them. On the desktop app, VS Code and mobile it shows the card with the command to run in a terminal instead.
|
|
417
544
|
|
|
418
545
|
With activity routing `on`, the activity question goes in the same request as the tier question (Ollama makes a second call), with the same text and nothing more. **Sends** names the service that receives the prompt and recent dialogue. With Clef, Clef Flash or Clef Omni that is Cloudflare, not typesafe.ai; with OpenAI it is OpenAI; with Ollama it stays on this machine. Give the Cloudflare token Workers AI permissions only.
|
|
419
546
|
|
|
@@ -455,7 +582,7 @@ To stop routing for a session, run `/router off`. To keep tier routing but stop
|
|
|
455
582
|
| Status says `no API key` or `no API token` | The active classifier's plugin option is unset or unavailable to this process. | Select **Set up** in the pane, or run `/plugin configure router`. Save the option and start a new turn. |
|
|
456
583
|
| Status says `no account ID` | Clef, Clef Flash or Clef Omni is active without the Cloudflare account ID. | Run `/plugin configure router` and save the Cloudflare account ID. |
|
|
457
584
|
| Route stays on the current model | The classifier timed out, failed, is paused, or network policy refused it. | Read the status band and the pane header. Network policy refusal is not bypassed. |
|
|
458
|
-
| `/model` changed but routing stopped | Choosing a model turns routing off.
|
|
585
|
+
| `/model` changed but routing stopped | Choosing a model (`/model`, the model picker, or the SDK, an IDE or Remote Control) turns routing off. | Run `/router auto` to turn routing back on. |
|
|
459
586
|
| Selected provider file is missing | The provider name selects a file that does not exist. | Create that file in the active Claude Code profile directory. Use `{}` only for built-in profiles. See [Providers](providers.md). |
|
|
460
587
|
| A custom profile containing `{}` fails | No built-in model catalog exists for that provider name. | Define all four routes and their model entries. See the [custom profile example](providers.md#add-another-provider). |
|
|
461
588
|
| Router reports invalid configuration | The selected file is invalid, or project/local settings redirect the profile. | Inspect the file shown in the pane. Remove project/local `HOME`, `CLAUDE_CONFIG_DIR`, or `CLAUDE_ROUTER_PROVIDER` overrides. |
|
|
@@ -465,8 +592,10 @@ To stop routing for a session, run `/router off`. To keep tier routing but stop
|
|
|
465
592
|
| `⚠ Ollama timed out` | The model is loading after an idle period, or the machine is slow. | Wait for one more turn. If it recurs, raise `classifiers.ollama.timeoutMs` in `router.json`. |
|
|
466
593
|
| `⚠ Ollama request failed` | The tag in `model` is not pulled, or Ollama rejected a request setting. | Run `ollama pull <model>` for the tag in `model`, or choose another model. |
|
|
467
594
|
| Band reads `v0.8 gateway settings remain` | The `jev-router[1m]` model or the `127.0.0.1:43170` base URL is still set. | Run `/router`: it lists the keys. Remove them as in the [migration checklist](configuration.md#convert-a-v08-configuration) and restart. |
|
|
468
|
-
| Router controls are unavailable | Claude Code is older than 2.1.
|
|
595
|
+
| Router controls are unavailable | Claude Code is older than 2.1.321. | Update Claude Code. |
|
|
469
596
|
| Pane reads `ROUTER unavailable` | Old gateway settings, an old Claude Code, or an invalid `router.json`. The line under it names which. | Fix the cause it names and restart. Until then every turn keeps Claude's model, and `/router auto`, `off`, `pin`, and `activities` reply with the reason and change nothing. |
|
|
470
597
|
| Context reads as unknown | The router lacks a reliable local estimate or current-history measurement. | Keep using the current model, or start a new history with a supported context estimate. |
|
|
471
598
|
|
|
599
|
+
When a session starts with the router unavailable, a toast says why (`Routing off: requires Claude Code 2.1.321 or newer. Claude’s model is kept.`). A desktop, VS Code or mobile surface that attaches later gets it once as well. It shows once a day for each cause (old Claude Code, v0.8 gateway settings, a `router.json` that does not load) and never under `claude -p`. The band and the pane keep saying it.
|
|
600
|
+
|
|
472
601
|
For the internal event flow and network deadline behavior, see [Architecture](architecture.md). For what the test traces do and do not show, see [Evaluation](evaluation.md).
|