@alexeiled/claude-router 1.9.0 → 1.10.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 +22 -0
- package/README.md +3 -3
- package/docs/activity-routing.md +35 -34
- package/docs/architecture.md +5 -7
- package/docs/configuration.md +25 -23
- package/docs/evaluation.md +8 -9
- package/docs/native-router.md +15 -16
- package/docs/router-band.svg +3 -21
- package/docs/router-pane-classifier.svg +82 -63
- package/docs/router-pane-now.svg +95 -109
- package/docs/router-pane-policy.svg +70 -0
- package/docs/router-pane-routes.svg +103 -0
- package/docs/router-pane-usage.svg +100 -127
- package/docs/user-guide.md +63 -49
- package/hooks/native-router.mjs +20 -50
- package/lib/activity-stats.mjs +21 -70
- package/lib/band.mjs +3 -6
- package/lib/config.mjs +11 -8
- package/lib/cost.mjs +3 -3
- package/lib/display.mjs +14 -41
- package/lib/panel.mjs +651 -477
- package/lib/route.mjs +4 -53
- package/lib/subagents.mjs +12 -17
- package/lib/view.mjs +3 -3
- package/package.json +1 -1
- package/types/index.d.ts +10 -36
- package/docs/router-pane-routing.svg +0 -150
package/docs/user-guide.md
CHANGED
|
@@ -32,7 +32,7 @@ Keys are stored as sensitive plugin options. Do not paste them into a model conv
|
|
|
32
32
|
|
|
33
33
|
Router draws one line above the prompt. The line ends with a **Router** button that opens the pane. When the band is narrow, the less important parts drop first: classifier figures, then context and cache, then the activity, then the reason. The tier and model always stay, except behind a classifier warning: the warning and its **Set up** button come first, and the route gives way to them.
|
|
34
34
|
|
|
35
|
-

|
|
36
36
|
|
|
37
37
|
Read the first line of the picture from left to right:
|
|
38
38
|
|
|
@@ -63,39 +63,36 @@ Tool continuations do not trigger another classification. A subagent gets at mos
|
|
|
63
63
|
|
|
64
64
|
## Open the router pane
|
|
65
65
|
|
|
66
|
-
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
|
|
66
|
+
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.
|
|
67
67
|
|
|
68
|
-
|
|
68
|
+
| Tab | What it answers |
|
|
69
|
+
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
70
|
+
| 1 Now | What runs next turn, and why: tier, model, activity, the reason with the support it weighed; classifier support per tier with **pin**; the last 30 replies. |
|
|
71
|
+
| 2 Routes | Which model runs: one grid of tiers by activities, the activity routing mode, and an editor for the selected cell. |
|
|
72
|
+
| 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. |
|
|
73
|
+
| 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. |
|
|
74
|
+
| 5 Usage | What routing cost: routing vs your model, plan quota, this session by activity, and Claude's readings with the estimates behind **details**. |
|
|
69
75
|
|
|
70
|
-
The
|
|
76
|
+
The top line of every tab, `ROUTING [ ◉ 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. **?** shows what the estimates leave out. When routing is unavailable, the top line reads `ROUTING unavailable Claude’s model is kept` with the reason under it, and offers no on or off: see [Troubleshooting](#troubleshooting).
|
|
71
77
|
|
|
72
|
-

|
|
73
79
|
|
|
74
|
-
The **
|
|
75
|
-
|
|
76
|
-
| Tab | What it shows |
|
|
77
|
-
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
78
|
-
| 1 Now | The current tier, model, activity, and reason; the classifier's support for each tier with a **pin** button; the last 30 replies by tier and activity; context and cache. |
|
|
79
|
-
| 2 Routing | The model and effort for each tier, the baseline tier, the cache cost of each step up; the activity routing mode, matrix, and overrides; the policy controls; the `router.json` path. |
|
|
80
|
-
| 3 Classifier | The classifier rows with their credentials state, the active classifier's deadline and health, and the credentials each classifier needs. |
|
|
81
|
-
| 4 Usage | Routing vs your model; Claude-reported cost, context and cache detail, input per reply, quota, activity counts for this session and across sessions, and configured-price estimates. |
|
|
82
|
-
|
|
83
|
-
The top line of every tab, `ROUTING [ ◉ on ] [ ○ off ]`, shows the routing mode and switches it. Press `o` or `f` while the pane has focus. **?** shows what the estimates leave out. When routing is unavailable, the top line reads `ROUTING unavailable Claude’s model is kept` with the reason under it, and offers no on or off: see [Troubleshooting](#troubleshooting).
|
|
80
|
+
The **Now** tab answers "what runs next turn, and why". **Next turn** names the tier, the model and effort, and, when an activity override runs, the tier's own model beside it. **Activity** names the classifier's activity as a verb, such as `coding 84%`, with the two next answers and the threshold at which an activity applies. **Why** gives the reason; under it, `Jev gave stronger tiers 88% (needs 82%) · switch ≈ $0.48` compares the classifier's support for the switch with the bar the policy set, and gives the estimated switch cost. The ladder lists the tiers from strongest to cheapest with the route each one uses and the support the classifier gave it on the last turn. **pin** forces that tier for the next turn only.
|
|
84
81
|
|
|
85
82
|
### Save and undo changes
|
|
86
83
|
|
|
87
|
-
The
|
|
84
|
+
The settings tabs follow one of two rules, and the section captions say which:
|
|
88
85
|
|
|
89
|
-
- **
|
|
86
|
+
- **Routes** and **Policy**: one draft for both, edited as a set, then saved. Changes stay a draft until **Save** (`s`). **Discard** (`d`) drops them. The draft stays when you change tab or close the pane: the tab whose settings changed reads **Routes ●** or **Policy ●**. Those two tabs list the `router.json` lines that **Save** will write; the other tabs show the count with **Save** and **Discard**. A new session drops the draft.
|
|
90
87
|
- **Classifier**: a row or a deadline is written to `router.json` when you select it.
|
|
91
88
|
|
|
92
89
|
Every write applies from the next turn and can be undone. **Undo** (`u`) puts back the settings the last write changed, from any tab, and leaves any other edit to `router.json` alone. A new session clears it. Green notices confirm a write or an undo; a red one names why nothing was written.
|
|
93
90
|
|
|
94
91
|
### Compare routing with your model
|
|
95
92
|
|
|
96
|
-

|
|
97
94
|
|
|
98
|
-
**ROUTING VS YOUR MODEL**
|
|
95
|
+
The Usage tab opens with the answer, such as `Routing saved $1.84 (22%) this session vs Opus 5.5 · xhigh`, or `Routing cost $2.48 (×5.0) more this session than Haiku 5.5 · high`, once the session has 10 routed replies. **ROUTING VS YOUR MODEL** follows with the figures behind it. Your model is the model `/model` (or `--model`) selects now, at the session effort, shown in the heading. For every reply routing chose, it prices the reported tokens on the model that served them. It also prices the same tokens on each model in `router.json`, at its list prices. After a `/model` change, the session column shows the whole session against the new model. The line `vs other models: Sonnet 5.5 extra $2.28 · Haiku 5.5 extra $6.19` shows the session against the others, each from its tenth routed reply.
|
|
99
96
|
|
|
100
97
|
| Line | What it is |
|
|
101
98
|
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -106,7 +103,7 @@ Every write applies from the next turn and can be undone. **Undo** (`u`) puts ba
|
|
|
106
103
|
| stronger than yours | The part from replies on stronger models, with how many replies ran on them. |
|
|
107
104
|
| cache writes from switches | The part from rewriting the prompt cache after model switches. |
|
|
108
105
|
|
|
109
|
-
The three parts add up to the difference. Two bars compare the costs, the routed one colored by the tier that spent it, and a line gives the share of replies per tier.
|
|
106
|
+
The three parts add up to the difference. Two bars compare the costs, the routed one colored by the tier that spent it, and a line gives the share of replies per tier. The columns are this session and every session since the last reset; the saved column compares each reply with the model `/model` selected when it ran, so it can add up several models. A column reads `too early` until it has 10 routed replies. With routing off or unavailable and no routed reply this session, the section says every reply used your model. In a narrow pane the bars go first, then the saved column.
|
|
110
107
|
|
|
111
108
|
These are estimates, not a bill. They hold the tokens and the output length the same, although another model may write more or less, and they do not measure answer quality. On a Claude plan the dollars stand for quota. Your model's cache reads the previous prompt inside the cache lifetime Claude Code uses, one hour on a Claude plan, and never less than the API actually read. A route that changes only the effort, such as Opus at `xhigh` to Opus at `medium`, costs no less per token: it shows only its cache writes. [Evaluation](evaluation.md#routing-vs-your-model) explains the method.
|
|
112
109
|
|
|
@@ -115,13 +112,15 @@ These are estimates, not a bill. They hold the tokens and the output length the
|
|
|
115
112
|
- **Cost** comes from Claude Code's native usage API. If the account is on a plan, a configured list-price estimate is not the subscription cash charge.
|
|
116
113
|
- **Context** compares the larger available context reading with the routed model's configured window. The router reserves 20% of that window. Values can be unknown when Claude does not provide the needed estimate.
|
|
117
114
|
- **Cache** reuse is cache-read tokens divided by the last response's input counters.
|
|
118
|
-
- **Classifier support**, such as **Jev support**, is the probability the classifier gave each tier on the last classified turn. The line under
|
|
119
|
-
- **
|
|
120
|
-
- **Input per reply** scales the last 30 input sizes from the lowest to the highest reading. It is a scale comparison, not a forecast.
|
|
115
|
+
- **Classifier support**, such as **Jev support**, is the probability the classifier gave each tier on the last classified turn. The line under **Why** compares the support for a switch with the bar the policy required, and shows the estimated switch cost.
|
|
116
|
+
- **Last replies** on the Now tab colors each of the last 30 main-conversation replies by the tier that served it. A dot marks a reply the router did not choose, such as one with routing off. The heading counts the model switches between those replies: a change of model or effort, so a move from Sonnet to Haiku inside `low` counts too, although its color stays. Under the strip, the replies per tier, `■ low 12 ■ medium 2 ■ high 6`, double as the color key, and the replies per activity follow, such as `coding 12 · exploring 4 · running 2`.
|
|
117
|
+
- **Input per reply**, under **details** on the Usage tab, scales the last 30 input sizes from the lowest to the highest reading. It is a scale comparison, not a forecast.
|
|
121
118
|
- **Cache hits saved** is a configured-price estimate for cached reads before write costs. It is not a measured saving.
|
|
122
119
|
- **Next-turn difference** compares the candidate with the current model under five-minute and one-hour cache-write scenarios. A negative number means the candidate is estimated to cost less for that request.
|
|
123
120
|
- **Payback** estimates later turns to recover an initial difference under assumed future cache reads and the last observed output size. It does not guarantee savings.
|
|
124
121
|
|
|
122
|
+
Under routing vs your model, **PLAN QUOTA** shows the five-hour and seven-day use that Claude Code reports, and **BY ACTIVITY** shows this session by activity (see [Read the activity on the pane](#read-the-activity-on-the-pane)). **SUBAGENTS · across sessions** shows each routed agent type, what routing cost against the model Claude Code would have used, and the spawns that passed through (see [Subagent routing](configuration.md#subagent-routing)). **CLAUDE READINGS** puts cost, context and cache on one line; **details** adds the context and cache counters, the output of the last reply, the input per reply, and the estimates below.
|
|
123
|
+
|
|
125
124
|
The router keeps no bill. Routing vs your model is an estimate at configured list prices. The pane does not include classifier charges. Claude's native `/cost` is the source for its reported API cost.
|
|
126
125
|
|
|
127
126
|
## Route by activity
|
|
@@ -145,12 +144,11 @@ The mode decides what happens with the label:
|
|
|
145
144
|
| Mode | What the router does |
|
|
146
145
|
| -------- | ---------------------------------------------------------------------------------------------------- |
|
|
147
146
|
| `on` | The default. Applies the activity overrides. |
|
|
148
|
-
| `shadow` | Shows the activity, records the stats, and works out what `on` would run. The base route still runs. |
|
|
149
147
|
| `off` | Does not ask the activity: the classifier is asked for the tier only. The base routes run. |
|
|
150
148
|
|
|
151
|
-
To turn activity routing off
|
|
149
|
+
To turn activity routing off, run `/router activities off`, or set **Activity routing** at the top of the Routes tab and press **Save**. Routing itself stays on: only the activity overrides stop. Upgrading from 1.6, which asked the activity but ran the base routes, run `/router activities off` to keep 1.6's routes. A `router.json` that still sets `"shadow"`, for activity or subagent routing, is read as not setting it, so the default, `on`, runs.
|
|
152
150
|
|
|
153
|
-
|
|
151
|
+
When an override runs, the **Next turn** line adds the tier's own model: `override · low runs Haiku 5.5 · high`.
|
|
154
152
|
|
|
155
153
|
How the router moves inside a tier:
|
|
156
154
|
|
|
@@ -158,18 +156,18 @@ How the router moves inside a tier:
|
|
|
158
156
|
- A move to a stronger route needs the classifier's support, as an upgrade between tiers does. A move to a cheaper one must pay back its cache write within the payback horizon. One vote is enough for either, because the activity is a fact about this turn.
|
|
159
157
|
- An activity applies only when the classifier gives it at least 60% probability (`policy.activityMass`). Below that, or on `uncertain`, a new task goes back to its base route if the move passes the same checks; a continuation of the running task keeps its activity, or moves to the classifier's activity when that route is stronger. Tool continuations inside a turn keep the turn's route. When the classifier sees a new prompt as a continuation of the task, the activity may only move to a stronger route: `explore` can become `code`, but not the other way. Ollama does not answer the continuation question, so this rule does not apply to it.
|
|
160
158
|
- A pinned turn uses the pin's base route and shows no activity.
|
|
161
|
-
- When the classifier gives no answer at all (a timeout, a failure, a pause, or a missing key), the running route stays. When it answers the tier but gives no usable activity, only the running activity stays: the tier answer still applies, so the turn can change tier and keeps its activity there. In `
|
|
162
|
-
- A fresh session starts with routing on when the session model is a tier's route. With activity routing `on`, a model that only an activity override uses also counts: Sonnet 5.5 on the defaults. In `off`
|
|
159
|
+
- When the classifier gives no answer at all (a timeout, a failure, a pause, or a missing key), the running route stays. When it answers the tier but gives no usable activity, only the running activity stays: the tier answer still applies, so the turn can change tier and keeps its activity there. In `off` the base route always runs.
|
|
160
|
+
- A fresh session starts with routing on when the session model is a tier's route. With activity routing `on`, a model that only an activity override uses also counts: Sonnet 5.5 on the defaults. In `off` it does not.
|
|
163
161
|
|
|
164
162
|
The band's activity label appears only when the activity applies, so a weak or `uncertain` answer shows none. The two-row band and the **Replies** strip show the activities of recent replies.
|
|
165
163
|
|
|
166
164
|
### Read the activity on the pane
|
|
167
165
|
|
|
168
|
-
- **Now**: the **Activity** line names the classifier's choice with its share
|
|
169
|
-
- **
|
|
170
|
-
- **Usage**: **ACTIVITY · this session** lists turns, requests, and share per activity, then `est. cost`, the list price of that activity's replies (the same per-reply estimate as Routing vs your model, but only for turns recorded with activity routing `
|
|
166
|
+
- **Now**: the **Activity** line names the classifier's choice as a verb with its share, the two next-best answers, and the threshold at which an activity applies, such as `coding 84% debugging 8% · planning 5% applies at 60%+`. An `uncertain` answer is shown dim: it applies no activity. In `on`, **Why** names the cell when the activity moved the route or the route is an override, such as `coding at low runs on Sonnet 5.5 · high`, or `low runs on its base route, Haiku 5.5 · high` for a move without an activity; a refused move, a hold, or a tier change keeps its reason. **Last replies** counts the replies per activity under the strip.
|
|
167
|
+
- **Routes**: see [Edit routes and policy](#edit-routes-and-policy). Each activity is a row of the grid, and a cell shows the model the activity runs at that tier.
|
|
168
|
+
- **Usage**: **BY ACTIVITY · this session** lists turns, requests, and share per activity, then `est. cost`, the list price of that activity's replies (the same per-reply estimate as Routing vs your model, but only for turns recorded with activity routing `on`, so the rows need not add up to its routed total; `—` when a reply had no price), and `mostly on`, the route most of its replies used, such as `Sonnet 5.5 · high`. A narrow pane drops `mostly on`, then `est. cost`. Below the table are the switches split by tier and by activity, with `· 2 refused` when activity moves were refused in `on` (not worth the cache write, a hold after an escalation, or the credits cap), and **Agreement**, how often the tools a turn used fit the classifier's activity (see [Evaluation](evaluation.md#tool-agreement)).
|
|
171
169
|
|
|
172
|
-
**ACROSS SESSIONS · since the last reset** shows the counts kept across sessions: the turns labelled from their tools, **Agreement** over them, **Code/ops/explore**, the same agreement over the turns the classifier answered `code`, `ops` or `explore` (omitted when there are none), the two most frequent mismatches as `predicted → observed count` (`code → read 3`), **Activity moves**, the moves to another route inside a tier, taken and refused for any reason, **Escalations**, such as `after a cheaper activity move: 1 in 12 moves`, the tool-error escalations that followed a move to a cheaper route in `on` while the turns stayed on it in `on` (turning routing off, a turn with routing off, or a turn in `
|
|
170
|
+
On the **Classifier** tab, **ACROSS SESSIONS · since the last reset** shows the counts kept across sessions, once there are any: the turns labelled from their tools, **Agreement** over them, **Code/ops/explore**, the same agreement over the turns the classifier answered `code`, `ops` or `explore` (omitted when there are none), the two most frequent mismatches as `predicted → observed count` (`code → read 3`), **Activity moves**, the moves to another route inside a tier, taken and refused for any reason, **Escalations**, such as `after a cheaper activity move: 1 in 12 moves`, the tool-error escalations that followed a move to a cheaper route in `on` while the turns stayed on it in `on` (turning routing off, a turn with routing off, or a turn in `off` ends the watch, a pin in between does not, and an escalation the credits cap held counts). Each of these lines appears only when it has data. The active classifier's p95 wait across sessions shows on its **Deadline** line instead (not recorded with activity routing `off`). This agreement compares the classifier's raw answer, so it can differ from the session's. The pane reads these counts when the session starts and when it opens, and adds this session's turns as they finish; another session's new latency and escalation readings show the next time the pane opens. **Reset stats** on the Usage tab clears the activity counts and routing vs your model, for this session and across sessions.
|
|
173
171
|
|
|
174
172
|
`/router` without a UI surface adds an `Activity: ops (81%)` line, the resolved route, and `Agreement across sessions: 19 of 22 turns (86%) · code/ops/explore 9 of 10 (90%)`. It also prints the session against your model, such as `vs your model (Opus 5.5 · xhigh): −$1.84 (−22%) this session, 64 replies, est. at list prices`.
|
|
175
173
|
|
|
@@ -181,7 +179,7 @@ The band's activity label appears only when the activity applies, so a weak or `
|
|
|
181
179
|
| `/router auto` | Resume automatic routing. |
|
|
182
180
|
| `/router off` | Turn routing off and keep Claude's selected model. |
|
|
183
181
|
| `/router pin <micro\|low\|medium\|high>` | Pin the next turn and its tool continuations. Routing on must already be enabled. |
|
|
184
|
-
| `/router activities <off\|
|
|
182
|
+
| `/router activities <off\|on>` | Set the [activity routing](#route-by-activity) mode. Saved to `router.json` at once; **Undo** reverts it. |
|
|
185
183
|
| `/model <name>` | Select a model and turn routing off. Use `/router auto` to turn it back on. |
|
|
186
184
|
| **Turn on** / **Turn off** on the band | The same as `/router auto` and `/router off`. |
|
|
187
185
|
| **on** / **off** on the pane (`o` / `f`) | The same as `/router auto` and `/router off`. |
|
|
@@ -191,24 +189,38 @@ A pin does not change the next turn after the pinned turn finishes. A fresh sess
|
|
|
191
189
|
|
|
192
190
|
## Edit routes and policy
|
|
193
191
|
|
|
194
|
-
|
|
192
|
+

|
|
193
|
+
|
|
194
|
+
The **Routes** tab is one grid. Columns are tiers, from `micro` to `high`. The **every turn** row holds each tier's own model and effort. Each activity below it is a row: a cell shows the model the activity runs at that tier, or `·` when it runs the tier's model. Cells read as `models key·effort`, such as `sonnet·high`; a narrow pane shortens the effort (`opus·xh`). `°` marks a built-in default override and **●** an unsaved edit. In the picture, `medium` was changed to Sonnet 5.5 at `xhigh` and `coding` at `high` to Opus 5.5 at `max`.
|
|
195
|
+
|
|
196
|
+
Select a cell, with the pointer or Tab and Enter, to edit it under the grid:
|
|
195
197
|
|
|
196
|
-
|
|
198
|
+
- **A tier cell** (every turn) has a model and an effort, with the model's list prices and window.
|
|
199
|
+
- **An activity cell** has a model and an effort, and says what the cell is: `built-in default`, `your override`, `runs the tier’s model`, or `same as the tier’s model: no effect`. **Use tier model** drops the override, so the cell runs the tier's model; for a built-in default, Save writes the tier's route for that cell, because the built-in one would come back otherwise. **Restore default** puts a changed or dropped built-in override back. A yellow note flags a cell stronger than the tier above, and a cell that is the only one on its cache.
|
|
197
200
|
|
|
198
|
-
|
|
201
|
+
The model list comes from the aliases in `router.json` `models`, limited by the `availableModels` setting. `inherit` keeps the effort Claude Code sends. A model without effort levels, such as a custom one with `"efforts": []`, shows `none`.
|
|
202
|
+
|
|
203
|
+
**Activity routing** at the top sets `off` or `on`, and says what the mode does. A yellow line says when the overrides do not run: activity routing `off`, or routing off or unavailable.
|
|
204
|
+
|
|
205
|
+
Under the grid, `3 prompt caches in use` counts the caches the grid can run on. Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 keep one cache per model across efforts with an API key or a Claude subscription; on Amazon Bedrock, Google Cloud, Microsoft Foundry or a custom `ANTHROPIC_BASE_URL`, each (model, effort) pair has its own. Moving to a model without a warm cache writes the whole conversation into a new cache, which is the switch cost on the Now tab. More caches mean more of those writes. A yellow line flags two neighbouring tiers that run the same model and effort, since that step changes nothing.
|
|
206
|
+
|
|
207
|
+
**Reset routes to defaults** (`r`) loads the built-in tier routes and start tier into the draft; **Save** then removes your route overrides from `router.json`. Activity edits and the mode stay in the draft.
|
|
199
208
|
|
|
200
209
|
A new model ID needs an entry in `router.json` `models` with its price, context window, and effort levels. See [Configuration](configuration.md).
|
|
201
210
|
|
|
202
211
|
### Tune future decisions
|
|
203
212
|
|
|
204
|
-
|
|
213
|
+

|
|
205
214
|
|
|
206
|
-
|
|
207
|
-
- **Payback horizon:** 1, 3, 5, or 10 later turns used by the downgrade estimate.
|
|
208
|
-
- **Credits cap:** $0.50, $1, $2, or $5 for an estimated cold cache write on a `credits` model.
|
|
209
|
-
- **Activity threshold:** 50%, 60%, 70%, or 80%, the least probability at which the classifier's activity applies. Below it a new task goes back to the base route, and a continuation keeps its activity, or moves to a stronger route the classifier names. See [Activity routing](activity-routing.md#change-a-cell).
|
|
215
|
+
The **Policy** tab writes each control inside the sentence it completes, and names the default beside a value that differs from it. One **Save** writes them with any route changes:
|
|
210
216
|
|
|
211
|
-
|
|
217
|
+
- **Start** at a tier: the tier a session starts from when its model is no tier's model (`baselineTier`).
|
|
218
|
+
- **Going down** after 1, 2, or 3 agreeing turns in a row, and only if a cache write pays back within 1, 3, 5, or 10 later turns. A new or reset history needs one vote.
|
|
219
|
+
- **Going up** needs the classifier's support at 75%, raised up to 90% as the switch costs more. Read-only here; see [Configuration](configuration.md).
|
|
220
|
+
- **Activities** apply at 50%, 60%, 70%, or 80% certainty or more. Below it a new task runs its tier's model, and a continuation keeps its activity, or moves to a stronger route the classifier names. See [Activity routing](activity-routing.md#change-a-cell).
|
|
221
|
+
- **Credits** caps one cold cache write on a `credits` model at $0.50, $1, $2, or $5. With no `credits` model in `router.json`, the tab says the cap has no effect.
|
|
222
|
+
|
|
223
|
+
**Reset policy to defaults** loads the built-in values; **Save** then removes your policy overrides. The current turn keeps the settings it started with. A save preserves unrelated `router.json` keys and refuses to write through a symlink. When validation fails, the pane names the setting and leaves the file unchanged. The tab ends with the `router.json` path, a **copy** button, and the [subagent routing](configuration.md#subagent-routing) mode, which is set in `router.json`.
|
|
212
224
|
|
|
213
225
|
## Choose the classifier
|
|
214
226
|
|
|
@@ -222,17 +234,19 @@ Router asks one classifier per turn. Five are built in:
|
|
|
222
234
|
| OpenAI | OpenAI, `gpt-6-luna` | OpenAI API key | 3,000 ms |
|
|
223
235
|
| Ollama | Local Ollama, `qwen3.5:9b` | None | 5,000 ms |
|
|
224
236
|
|
|
225
|
-

|
|
226
238
|
|
|
227
|
-
You can save credentials for all of them; only the active one is asked. The **Classifier** tab has one row per classifier: `◉` marks the active one
|
|
239
|
+
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.
|
|
228
240
|
|
|
229
241
|
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.
|
|
230
242
|
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
- **
|
|
243
|
+
Under the rows, a block for the active classifier:
|
|
244
|
+
|
|
245
|
+
- **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.
|
|
246
|
+
- **Sends** names the service that receives prompt text. **Health** shows a pause, recent failures, and the last wait.
|
|
247
|
+
- **Credentials**: **Edit** opens Claude Code's secure plugin configuration, where you enter them.
|
|
234
248
|
|
|
235
|
-
With
|
|
249
|
+
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 or Clef Flash 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.
|
|
236
250
|
|
|
237
251
|
The routing policy thresholds were tuned against Jev's probabilities. Clef's, OpenAI's, and Ollama's probabilities have not been compared with Jev's, so the same prompt can switch tiers at a different point. Watch **Classifier support** for a few sessions before you rely on a new classifier.
|
|
238
252
|
|
|
@@ -261,7 +275,7 @@ Keep the plugin enabled: in v1 it is the Mod. The Jev key option keeps its saved
|
|
|
261
275
|
|
|
262
276
|
Claude Code updates a marketplace install at startup when auto-update is on for the marketplace. To update now, run `claude plugin marketplace update alexei-led-claude-router`, then `claude plugin update router@alexei-led-claude-router`, and restart. For a local checkout, update the files and restart Claude Code with the same `--plugin-dir`.
|
|
263
277
|
|
|
264
|
-
To stop routing for a session, run `/router off`. To keep tier routing but stop the activity overrides, run `/router activities off
|
|
278
|
+
To stop routing for a session, run `/router off`. To keep tier routing but stop the activity overrides, run `/router activities off`. To stop loading the Mod, run `claude plugin disable router@alexei-led-claude-router`, or restart without `--plugin-dir` for a checkout. The Mod keeps no session ledger and starts no process.
|
|
265
279
|
|
|
266
280
|
## Troubleshooting
|
|
267
281
|
|
package/hooks/native-router.mjs
CHANGED
|
@@ -651,7 +651,6 @@ async function decideTurn($, router, e, signal, step) {
|
|
|
651
651
|
estimate: selected.decision.estimate ?? null,
|
|
652
652
|
activityChoice: activity.predicted,
|
|
653
653
|
activityProbabilities: result.advice?.activity?.probabilities ?? null,
|
|
654
|
-
wouldRoute: selected.decision.wouldRoute ?? null,
|
|
655
654
|
}
|
|
656
655
|
: {}),
|
|
657
656
|
});
|
|
@@ -813,9 +812,6 @@ async function recordActivity($, router, turn) {
|
|
|
813
812
|
tierSwitches: turn.switched === 'tier' ? 1 : 0,
|
|
814
813
|
activitySwitches: turn.switched === 'activity' ? 1 : 0,
|
|
815
814
|
lateral: turn.lateral,
|
|
816
|
-
wouldDiffer: turn.wouldDiffer,
|
|
817
|
-
wouldUsd: turn.wouldUsd,
|
|
818
|
-
shadow: turn.mode === 'shadow',
|
|
819
815
|
}),
|
|
820
816
|
});
|
|
821
817
|
const resets = router.statsResets;
|
|
@@ -831,8 +827,6 @@ async function recordActivity($, router, turn) {
|
|
|
831
827
|
observed,
|
|
832
828
|
runEnded: ended,
|
|
833
829
|
lateral: turn.lateral,
|
|
834
|
-
wouldDiffer: turn.wouldDiffer,
|
|
835
|
-
wouldUsd: turn.wouldUsd,
|
|
836
830
|
});
|
|
837
831
|
const measured = recordMetrics(own.record, {
|
|
838
832
|
classifier: turn.classifier,
|
|
@@ -858,7 +852,7 @@ async function recordActivity($, router, turn) {
|
|
|
858
852
|
async function flushRun($, run) {
|
|
859
853
|
try {
|
|
860
854
|
const store = readStore(await $.store.get(STORE_KEY));
|
|
861
|
-
const ended = { predicted: null, observed: null, runEnded: run, lateral: null
|
|
855
|
+
const ended = { predicted: null, observed: null, runEnded: run, lateral: null };
|
|
862
856
|
await $.store.set(STORE_KEY, recordStore(store, ended));
|
|
863
857
|
} catch {}
|
|
864
858
|
}
|
|
@@ -946,41 +940,28 @@ async function decideSpawn($, router, cfg, e, definition, signal) {
|
|
|
946
940
|
}
|
|
947
941
|
|
|
948
942
|
// One model per subagent, chosen before its cache exists. `on` waits for the decision and sends its model, which
|
|
949
|
-
// Claude Code uses in place of the Agent call's `model` and the agent's frontmatter.
|
|
950
|
-
//
|
|
951
|
-
// unavailable keeps every model Claude Code chooses, and records nothing.
|
|
943
|
+
// Claude Code uses in place of the Agent call's `model` and the agent's frontmatter. Routing off or unavailable keeps
|
|
944
|
+
// every model Claude Code chooses, and records nothing.
|
|
952
945
|
async function spawnAgent($, router, e, next) {
|
|
953
946
|
const cfg = router.config;
|
|
954
|
-
|
|
955
|
-
if (mode === 'off') return next(e);
|
|
947
|
+
if (cfg.subagentRouting === 'off') return next(e);
|
|
956
948
|
const view = router.view ?? (await readView($, router));
|
|
957
949
|
if (view.phase === 'unavailable' || (await modeOf($, router, view.mode)) === 'manual') return next(e);
|
|
958
950
|
const definition = await agentDefinition($, router, e);
|
|
959
951
|
const pass = passReason(cfg, e, definition);
|
|
960
|
-
const
|
|
961
|
-
const
|
|
962
|
-
const
|
|
963
|
-
|
|
964
|
-
|
|
965
|
-
// In shadow the agent may reply, and even finish, before the decision lands: a pending entry keeps its replies.
|
|
966
|
-
if (mode !== 'on' && deciding !== null)
|
|
967
|
-
router.agents.set(result.agentId, { pending: true, usages: [], finished: false });
|
|
968
|
-
try {
|
|
969
|
-
const decision = mode === 'on' ? decided : await deciding;
|
|
970
|
-
if (pass || decision) await noteSpawn($, router, { cfg, mode, e, pass, decision, routed, result, definition });
|
|
971
|
-
else router.agents.delete(result.agentId);
|
|
972
|
-
} catch {
|
|
973
|
-
if (router.agents.get(result.agentId)?.pending) router.agents.delete(result.agentId);
|
|
974
|
-
}
|
|
952
|
+
const decision = pass ? null : await decideSpawn($, router, cfg, e, definition, next.signal).catch(() => null);
|
|
953
|
+
const routed = Boolean(decision?.model);
|
|
954
|
+
const result = await next(routed ? { ...e, model: decision.model } : e);
|
|
955
|
+
if (result.agentId && (pass || decision))
|
|
956
|
+
await noteSpawn($, router, { cfg, e, pass, decision, routed, result, definition }).catch(() => {});
|
|
975
957
|
return result;
|
|
976
958
|
}
|
|
977
959
|
|
|
978
|
-
// The spawn's record, kept until the session ends.
|
|
979
|
-
// the model the agent started on.
|
|
980
|
-
async function noteSpawn($, router, { cfg,
|
|
960
|
+
// The spawn's record, kept until the session ends. When routed, core's model is an estimate (coreModelOf); otherwise it
|
|
961
|
+
// is the model the agent started on.
|
|
962
|
+
async function noteSpawn($, router, { cfg, e, pass, decision, routed, result, definition }) {
|
|
981
963
|
const parentKey = `${e.parentAgentId ?? 'main'} ${e.subagentType}`;
|
|
982
964
|
const finishedAt = router.finished.get(parentKey);
|
|
983
|
-
const ttl = await subagentTtlOf($).catch(() => null);
|
|
984
965
|
const coreModel = routed
|
|
985
966
|
? coreModelOf(cfg, e, {
|
|
986
967
|
envModel: await $.env.get('CLAUDE_CODE_SUBAGENT_MODEL'),
|
|
@@ -990,7 +971,6 @@ async function noteSpawn($, router, { cfg, mode, e, pass, decision, routed, resu
|
|
|
990
971
|
: result.model;
|
|
991
972
|
const record = spawnRecord({
|
|
992
973
|
sessionId: await $.session.id(),
|
|
993
|
-
mode,
|
|
994
974
|
spawn: e,
|
|
995
975
|
pass,
|
|
996
976
|
choice: decision?.choice ?? null,
|
|
@@ -999,14 +979,7 @@ async function noteSpawn($, router, { cfg, mode, e, pass, decision, routed, resu
|
|
|
999
979
|
failed: decision?.failed,
|
|
1000
980
|
respawn: Number.isFinite(finishedAt) && Date.now() - finishedAt < RESPAWN_WINDOW_MS,
|
|
1001
981
|
});
|
|
1002
|
-
|
|
1003
|
-
const pending = router.agents.get(result.agentId);
|
|
1004
|
-
const replies = pending?.pending ? pending.usages : [];
|
|
1005
|
-
router.agents.set(
|
|
1006
|
-
result.agentId,
|
|
1007
|
-
replies.reduce((agent, usage) => addAgentReply(cfg, agent, usage, ttl), { ...record, parentKey }),
|
|
1008
|
-
);
|
|
1009
|
-
if (pending?.finished) await finishAgent($, router, result.agentId);
|
|
982
|
+
router.agents.set(result.agentId, { ...record, parentKey });
|
|
1010
983
|
}
|
|
1011
984
|
|
|
1012
985
|
// A subagent's prompt-cache lifetime, by Claude Code's rule for requests outside the main conversation.
|
|
@@ -1028,8 +1001,7 @@ async function* stepAgent($, router, e, next) {
|
|
|
1028
1001
|
try {
|
|
1029
1002
|
const ttl = await subagentTtlOf($);
|
|
1030
1003
|
const agent = router.agents.get(e.agentId);
|
|
1031
|
-
if (agent
|
|
1032
|
-
else if (agent) router.agents.set(e.agentId, addAgentReply(router.config, agent, response.usage, ttl));
|
|
1004
|
+
if (agent) router.agents.set(e.agentId, addAgentReply(router.config, agent, response.usage, ttl));
|
|
1033
1005
|
} catch {}
|
|
1034
1006
|
}
|
|
1035
1007
|
return response;
|
|
@@ -1039,11 +1011,6 @@ async function* stepAgent($, router, e, next) {
|
|
|
1039
1011
|
async function finishAgent($, router, agentId) {
|
|
1040
1012
|
const agent = router.agents.get(agentId);
|
|
1041
1013
|
if (!agent) return;
|
|
1042
|
-
// A pending agent is flushed when its decision lands (noteSpawn).
|
|
1043
|
-
if (agent.pending) {
|
|
1044
|
-
agent.finished = true;
|
|
1045
|
-
return;
|
|
1046
|
-
}
|
|
1047
1014
|
router.finished.set(agent.parentKey, Date.now());
|
|
1048
1015
|
router.agents.set(agentId, flushedAgent(agent));
|
|
1049
1016
|
await flushSubagents($, router, [agent]);
|
|
@@ -1206,8 +1173,11 @@ function paneActions($, router, view) {
|
|
|
1206
1173
|
}),
|
|
1207
1174
|
activityModel: (activity, tier, alias) => editCell(activity, tier, 'model', alias),
|
|
1208
1175
|
activityEffort: (activity, tier, effort) => editCell(activity, tier, 'effort', effort),
|
|
1209
|
-
|
|
1176
|
+
// Restore puts the built-in default back; Use tier model drops the cell, a built-in one saved as the tier's route.
|
|
1177
|
+
restoreActivity: (activity, tier) => editCell(activity, tier, 'add'),
|
|
1210
1178
|
removeActivity: (activity, tier) => editCell(activity, tier, 'remove'),
|
|
1179
|
+
selectCell: (cell) => updateView($, router, { routeCell: cell, notice: null }),
|
|
1180
|
+
usageDetail: () => updateView($, router, { usageDetail: !(router.view ?? view).usageDetail }),
|
|
1211
1181
|
// `/router activities <mode>`: the mode alone, saved at once like a classifier press, with Undo.
|
|
1212
1182
|
activityRouting: (mode) => {
|
|
1213
1183
|
const from = router.config.activityRouting;
|
|
@@ -1222,7 +1192,7 @@ function paneActions($, router, view) {
|
|
|
1222
1192
|
router.run = null;
|
|
1223
1193
|
router.afterDown = null;
|
|
1224
1194
|
router.turnSavings.clear();
|
|
1225
|
-
for (const [id, agent] of router.agents)
|
|
1195
|
+
for (const [id, agent] of router.agents) router.agents.set(id, flushedAgent(agent));
|
|
1226
1196
|
const clear = (key, value) =>
|
|
1227
1197
|
$.store
|
|
1228
1198
|
.set(key, value)
|
|
@@ -1354,7 +1324,7 @@ export function register(on, options) {
|
|
|
1354
1324
|
await $.command.register({
|
|
1355
1325
|
name: 'router',
|
|
1356
1326
|
description: 'Open the Router pane, or switch routing: auto, off, pin <tier>, activities <mode>.',
|
|
1357
|
-
argumentHint: '[auto|off|pin <tier>|activities off|
|
|
1327
|
+
argumentHint: '[auto|off|pin <tier>|activities off|on]',
|
|
1358
1328
|
immediate: true,
|
|
1359
1329
|
});
|
|
1360
1330
|
const model = await $.session.model();
|