@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.
@@ -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
- ![Seven band states: routed to high, two rows with the hover row, a pending pin, a missing classifier key, routing off, an activity move with activity routing on, and an activity label in shadow](router-band.svg)
35
+ ![Six band states: routed to high, two rows with the hover row, a pending pin, a missing classifier key, routing off, and an activity move with activity routing on](router-band.svg)
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 four tabs. Select a tab or press its digit while the pane has focus.
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
- ![The Now tab: the route, the activity and its alternatives, the reason, classifier support per tier with pin buttons, recent replies by tier and activity, and context, cache and cost](router-pane-now.svg)
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 **Now** tab answers "what runs next turn, and why". The ladder lists the tiers from strongest to cheapest with the route each one uses. The bar is the support the classifier gave that tier on the last turn. The line under the ladder compares the support for a switch with the bar the policy required and shows the estimated switch cost. **pin** forces that tier for the next turn only. The **Activity** and **Route** lines under the route are covered in [Route by activity](#route-by-activity).
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
- ![The Routing tab: model and effort per tier, the baseline tier, how each step up is priced, the activity matrix and overrides, the policy controls, and the unsaved router.json changes with Save and Discard](router-pane-routing.svg)
78
+ ![The Now tab: what runs next turn with its tier, model and activity, the reason with the classifier support it weighed and the switch cost, classifier support per tier with pin buttons, the last replies as a strip with the switch count and the replies per tier and per activity, and context, cache and cost](router-pane-now.svg)
73
79
 
74
- The **Routing** tab edits the routes, the activity overrides, and the policy. In the picture, `medium` was changed to Sonnet 5.5 at `xhigh`: the tier shows **●**, the tab reads **Routing ●**, the switch-cost lines now price `medium → high` as a model change, and the status bar lists the `router.json` lines that **Save** will write. The same picture shows the activity matrix and overrides, with a `code` override at `high` added. [Edit routes and policy](#edit-routes-and-policy) explains the controls.
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 two settings tabs follow one rule each, and the section captions say which:
84
+ The settings tabs follow one of two rules, and the section captions say which:
88
85
 
89
- - **Routing**: edit as a set, then save. Changes stay a draft until **Save** (`s`). **Discard** (`d`) drops them. The draft stays when you change tab or close the pane: the tab reads **Routing ●**, and every tab shows the `router.json` lines that **Save** will write, with **Save** and **Discard**. A new session drops the draft.
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
- ![The Usage tab: routing vs your model, this session and since the last reset, with the difference split into its three parts, bars and replies by tier, then Claude's readings, activity counts with their estimated cost and route, the counts across sessions, and estimates](router-pane-usage.svg)
93
+ ![The Usage tab: the answer first, routing saved $1.84 (22%) against Opus 5.5 at xhigh; routing vs your model this session and since the last reset, with the difference split into its three parts, bars and replies by tier; plan quota; this session by activity; and Claude's readings on one line with details](router-pane-usage.svg)
97
94
 
98
- **ROUTING VS YOUR MODEL** opens the Usage tab. 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.
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. In activity-routing `shadow`, one more line estimates what `on` would change in this session. 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.
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 it compares the support for a switch with the bar the policy required, and shows the estimated switch cost.
119
- - **Replies** 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 count beside the strip is the number of switches between those replies: a change of model or effort, so a move from Sonnet to Haiku inside `low` counts too. When activity routing is on or in shadow, a row of letters under the strip names each reply's activity: `c` code, `d` debug, `e` explore, `p` plan, `r` review, `o` ops, `w` docs.
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 or back to `shadow`, run `/router activities off` or `/router activities shadow`, or set **Activity routing** at the top of the Routing tab's **ACTIVITIES** and press **Save**. Routing itself stays on: only the activity overrides stop. Upgrading from 1.6, where `shadow` was the default, a `router.json` without `activityRouting` now runs `on`. Choosing `shadow` in 1.6 removed the key, because `shadow` was the default then: if you chose `shadow` in 1.6, run `/router activities shadow` again after upgrading.
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
- In `shadow` you can see what `on` would do without it running. The band marks the label `(shadow)` and dims it, and the **Now** tab says `low + code would use Sonnet 5.5 · high (shadow; using Haiku 5.5 · high)`, or `same route` when both agree. In `on` the **Now** tab reads `low + code → Sonnet 5.5 · high (override)` with the tier's base route next to it, or `(base)` when the cell has no override.
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 `shadow` and `off` the base route always runs.
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` and `shadow` it does not.
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 and the two next-best answers, such as `code 84% debug 8% · plan 5%`. In `on`, **Why** names the cell when the activity moved the route or the route is an override, such as `code 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. The **Route** line shows the route the cell resolves to. **Replies** has a letter row under the strip.
169
- - **Routing**: **ACTIVITIES** starts with the **Activity routing** selector (`off`, `shadow`, `on`) and what the mode does. The matrix under it shows the effective routes per tier, with `·` where a cell uses the base route, and counts the distinct routes and the caches they use. Routes are abbreviated, such as `S·high` for Sonnet · high, and activities with the same cells share a row. **OVERRIDES** says whether the overrides are in use, then lists each override with a model, an effort, and **remove**, plus a selector to add one. **Activity threshold** under **POLICY** is the least probability at which an activity applies. Edits join the routing draft: **Save** and **Discard** apply as for routes. Yellow notes flag an override with no effect (`same as base`), one stronger than the tier above, and the only cell or tier on its cache, which adds one.
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 `shadow` or `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)). In `shadow` the **Shadow** line counts how many turns `on` would have routed differently, such as `on would route 5 of 20 turns differently · est. −$0.300 … −$0.120 at list prices`. The estimate sums, over those turns, what the next request on the route `on` would use would cost against the route that ran, as a low and a high scenario at the configured list prices in `router.json`. Minus means cheaper. It covers only turns after a measured reply, and adds `for 3` when only three of the turns have one. It is not a measured saving.
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 `shadow` or `off` ends the watch, a pin in between does not, and an escalation the credits cap held counts), **Latency**, the active classifier's p95 wait as a bucket bound such as `Jev p95 ≤ 350 ms · 20 turns` (not recorded with activity routing `off`), and the **Shadow** line summed over all shadow turns. Each of these lines appears only when it has data. 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** clears the activity counts and routing vs your model, for this session and across sessions.
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\|shadow\|on>` | Set the [activity routing](#route-by-activity) mode. Saved to `router.json` at once; **Undo** reverts it. |
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
- On the **Routing** tab, pick a model and an effort for any tier. The model list comes from the aliases in `router.json` `models`, limited by the `availableModels` setting. `session` keeps the effort Claude Code sends. A model without effort levels, such as a custom one with `"efforts": []`, shows `none`.
192
+ ![The Routes tab: the activity routing mode, then one grid of tiers by activities with the tiers' own models on top, built-in overrides marked °, unsaved edits ●; the editor of the selected cell, coding at high, with Use tier model; the prompt caches in use; and the unsaved router.json changes with Save and Discard](router-pane-routes.svg)
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
- Changed tiers and overrides show **●**. **Reset routes to defaults** (`r`) loads the built-in routes into the draft; **Save** then removes your route overrides from `router.json`.
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
- **Switch cost** reads the draft from the bottom tier up and shows how the policy prices each step. A model change is priced as a cold cache write. An effort change on the same model is also priced as a new messages cache; whether the API actually keeps the cache across an effort change is not measured. Two identical tiers make that step change nothing.
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
- Under **Policy** on the same tab, pick the values. One **Save** writes them with any route changes:
213
+ ![The Policy tab: each control inside its sentence, the start tier, going down, going up, the activity threshold and the credits cap, with the default beside a changed value, the router.json file and the subagent routing mode, and the unsaved change with Save and Discard](router-pane-policy.svg)
205
214
 
206
- - **Votes to go down:** 1, 2, or 3 consecutive votes before a cheaper tier. A new or reset history needs one.
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
- **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.
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
- ![The Classifier tab: classifier rows with the active one marked and each one's last activity probe, a missing Jev API key with Set up, the deadline, health, the receiving host, the credentials each classifier needs, and Undo after a switch](router-pane-classifier.svg)
237
+ ![The Classifier tab: one row per classifier with where the prompt goes, its activity probe, its p95 wait and its status, a missing Jev API key with Set up; the active classifier's deadline against its wait, the host that receives the prompt, health and credentials; the agreement with tools across sessions; and Undo after a switch](router-pane-classifier.svg)
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, followed by its service 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. Under a row, a dim line gives the classifier's last checked-in [activity probe](evaluation.md#activity-probe-set), such as `activity probe 70/70 · p95 299 ms · Oct 10`; it is omitted when you configured a model other than the probed 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
- - **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**.
232
- - **Health** shows recent failures or a pause. **Sends** names the service that receives prompt text.
233
- - **Credentials** lists what each classifier needs, such as `Jev: API key · Clef, Clef Flash: API token, account ID · OpenAI: API key · Ollama: no key needed`. **Edit** opens Claude Code's secure plugin configuration, where you enter them.
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 `shadow` or `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.
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`, or `/router activities shadow` to keep seeing what they would do. 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.
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
 
@@ -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, wouldDiffer: null, wouldUsd: 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. `shadow` spawns as Claude Code
950
- // would at once and records the decision once it is in, so it never delays an agent's start. Routing off or
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
- const mode = cfg.subagentRouting;
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 deciding = pass ? null : decideSpawn($, router, cfg, e, definition, next.signal).catch(() => null);
961
- const decided = mode === 'on' ? await deciding : null;
962
- const routed = Boolean(decided?.model);
963
- const result = await next(routed ? { ...e, model: decided.model } : e);
964
- if (!result.agentId) return result;
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. In `on` core's model is an estimate (coreModelOf); otherwise it is
979
- // the model the agent started on.
980
- async function noteSpawn($, router, { cfg, mode, e, pass, decision, routed, result, definition }) {
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
- // Read after the last await, so no reply lands in the pending entry after its replay.
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?.pending) agent.usages.push(response.usage);
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
- addActivity: (activity, tier) => editCell(activity, tier, 'add'),
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) if (!agent.pending) router.agents.set(id, flushedAgent(agent));
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|shadow|on]',
1327
+ argumentHint: '[auto|off|pin <tier>|activities off|on]',
1358
1328
  immediate: true,
1359
1329
  });
1360
1330
  const model = await $.session.model();