@alexeiled/claude-router 1.6.1 → 1.7.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.
@@ -24,7 +24,7 @@ In Claude Code:
24
24
  - **OpenAI**: an OpenAI API key. The prompt text goes to OpenAI.
25
25
  - **Ollama**: no credential. Run `ollama serve` and pull the model; the prompt text stays on this machine.
26
26
  3. To use another classifier, open the pane's **Classifier** tab and select its row. See [Choose the classifier](#choose-the-classifier).
27
- 4. Check the band above the prompt: `Routing on · ready`. On a model that no tier routes to, the session starts with routing off and the band says why; run `/router auto` to route.
27
+ 4. Check the band above the prompt: `Routing on · ready`. On a model that no tier routes to, and that no activity override uses with activity routing `on`, the session starts with routing off and the band says why; run `/router auto` to route.
28
28
 
29
29
  Keys are stored as sensitive plugin options. Do not paste them into a model conversation. The [configuration guide](configuration.md) covers optional settings and migrations.
30
30
 
@@ -42,19 +42,19 @@ Read the first line of the picture from left to right:
42
42
  - **Classifier support**: what the active classifier, such as Jev or Clef Flash, gave the switch against the bar the policy required.
43
43
  - **ctx** and **cache**: context use and cache reuse on the last reply. They turn yellow at 60% context and red at 80%.
44
44
 
45
- | Band shows | Meaning |
46
- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
47
- | `Routing on · ready` | Routing is on and ready for a new turn. |
48
- | `choosing for this turn…` | The classifier and local policy are running. The spinner says `Choosing model`. |
49
- | `⏵ next turn: high ✕` | A pin is set. **✕** cancels it. |
50
- | `⚠ Jev: no API key · keeping model` | The active classifier lacks a setting. **Set up** opens the secure plugin dialog. |
51
- | `⚠ Clef: no account ID · keeping model` | Clef has its API token but no Cloudflare account ID. **Set up** opens the dialog. |
52
- | `⚠ Jev timed out · keeping model` | The classifier failed: timed out, unreachable, rejected the key, or paused. |
53
- | `○ Routing off · every turn uses …` | Routing is off: Claude's model answers every turn. **Routing on** turns it back on. The footer also shows `routing off`. |
54
- | `✕ Routing unavailable` | Nothing routes: an old Claude Code or leftover v0.8 settings. **Fix** opens the pane. |
55
- | `○ Router · subagents keep their own model` | You are viewing a subagent's transcript, which Router does not route. |
45
+ | Band shows | Meaning |
46
+ | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
47
+ | `Routing on · ready` | Routing is on and ready for a new turn. |
48
+ | `choosing for this turn…` | The classifier and local policy are running. The spinner says `Choosing model`. |
49
+ | `⏵ next turn: high ✕` | A pin is set. **✕** cancels it. |
50
+ | `⚠ Jev: no API key · keeping model` | The active classifier lacks a setting. **Set up** opens the secure plugin dialog. |
51
+ | `⚠ Clef: no account ID · keeping model` | Clef has its API token but no Cloudflare account ID. **Set up** opens the dialog. |
52
+ | `⚠ Jev timed out · keeping model` | The classifier failed: timed out, unreachable, rejected the key, or paused. |
53
+ | `○ Routing off [ Turn on ] · every turn uses …` | Routing is off: Claude's model answers every turn. **Turn on** turns it back on. The footer also shows `routing off`. |
54
+ | `✕ Routing unavailable` | Nothing routes: an old Claude Code or leftover v0.8 settings. **Fix** opens the pane. |
55
+ | `○ Router · subagents keep their own model` | You are viewing a subagent's transcript, which Router does not route. |
56
56
 
57
- The band's **Routing off** button turns routing off, and **Routing on** turns it back on. Hover over the band for a second row: pin a tier for the next turn, or show two rows. The two-row band adds a strip of recent replies colored by tier, the switch count, the switch tax, and the cache saving. Router remembers that choice across sessions. When Router changes the model between turns, a toast reads `Model changed: old → new · reason`. A pin does not raise one, and neither does a change of effort alone.
57
+ The band shows one routing control at a time. While routing is on, hover over the band for a second row: pin a tier for the next turn, **Turn off** routing, or show two rows. While routing is off, **Turn on** sits on the first line next to `Routing off` and stays at any width: a narrow band drops the explanation and the model first. On a narrow band the hover row drops `routing on`, then **2 rows**, then `pin next turn`, then the pins; it keeps **Turn off**, and **1 row** when the band shows two. The hover row needs a pointer: from the keyboard, run `/router off`, or open the pane and press `f`. The two-row band adds a strip of recent replies colored by tier, the number of route switches (a change of model or effort, a move inside a tier included), the switch tax, the cache saving and, from the tenth reply, the session against your model, such as `vs your model −22% (−$1.84, list prices)` or `vs your model +$2.48 (stronger models, list prices)`. It drops first when the row is short. Router remembers that choice across sessions. When Router changes the model between turns, a toast reads `Model changed: old → new · reason`. A pin does not raise one, and neither does a change of effort alone.
58
58
 
59
59
  The band steps aside while a survey needs the space.
60
60
 
@@ -72,14 +72,14 @@ The **Now** tab answers "what runs next turn, and why". The ladder lists the tie
72
72
 
73
73
  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.
74
74
 
75
- | Tab | What it shows |
76
- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
77
- | 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. |
78
- | 2 Routing | The model and effort for each tier, the baseline tier, the cache cost of each step up; the activity matrix and overrides; downgrade votes, payback horizon, and credits cap; the `router.json` path. |
79
- | 3 Classifier | The classifier rows with their credentials state, the active classifier's deadline and health, and the credentials each classifier needs. |
80
- | 4 Usage | Claude-reported cost, context and cache detail, input per reply, quota, activity counts for this session and across sessions, and configured-price estimates. |
75
+ | Tab | What it shows |
76
+ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
77
+ | 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. |
78
+ | 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. |
79
+ | 3 Classifier | The classifier rows with their credentials state, the active classifier's deadline and health, and the credentials each classifier needs. |
80
+ | 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. |
81
81
 
82
- **Routing on** and **Routing off** stay at the top of every tab. **?** shows what the estimates leave out.
82
+ 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).
83
83
 
84
84
  ### Save and undo changes
85
85
 
@@ -90,19 +90,38 @@ The two settings tabs follow one rule each, and the section captions say which:
90
90
 
91
91
  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.
92
92
 
93
+ ### Compare routing with your model
94
+
95
+ ![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)
96
+
97
+ **ROUTING VS YOUR MODEL** opens the Usage tab. Your model is the model and effort the session had before routing: the `--model` or `/model` choice and the session effort, shown in the heading. For every reply routing chose, it prices the tokens Claude reported on the model that served them, and the same tokens on your model, at the list prices in `router.json`.
98
+
99
+ | Line | What it is |
100
+ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
101
+ | Routed replies | What the routed replies cost on the models that served them. |
102
+ | Same tokens on your model | What the same input and output tokens cost on your model, with one cache that never switched. |
103
+ | Difference | Routed minus yours. Green with a percentage when routing cost less; amber with `+$` when it cost more, `×N` once it is twice yours or more. |
104
+ | cheaper models | The part from replies on models cheaper than yours. |
105
+ | stronger than yours | The part from replies on stronger models, with how many replies ran on them. |
106
+ | cache writes from switches | The part from rewriting the prompt cache after model switches. |
107
+
108
+ 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 session with its own model and effort, 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.
109
+
110
+ 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.
111
+
93
112
  ### Understand usage and estimates
94
113
 
95
114
  - **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.
96
115
  - **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.
97
116
  - **Cache** reuse is cache-read tokens divided by the last response's input counters.
98
117
  - **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 tax.
99
- - **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. 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.
118
+ - **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.
100
119
  - **Input per reply** scales the last 30 input sizes from the lowest to the highest reading. It is a scale comparison, not a forecast.
101
120
  - **Cache read benefit** is a configured-price estimate for cached reads before write costs. It is not a measured saving.
102
121
  - **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.
103
122
  - **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.
104
123
 
105
- There is no router-side spend or savings ledger. The pane does not include classifier charges. Claude's native `/cost` is the source for its reported API cost.
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.
106
125
 
107
126
  ## Route by activity
108
127
 
@@ -118,38 +137,40 @@ A tier says how hard the work is. The activity says what kind of work it is. The
118
137
  | `ops` | Executed commands: git, builds, test runs, CI, deploys |
119
138
  | `docs` | Prose for people: README, docs, comments, commit messages |
120
139
 
121
- A mixed turn such as "fix it and commit" takes the hardest part, here `code`. The router then picks the route by tier and activity. With activity routing on and the default overrides, a `low` coding turn runs on Sonnet 5.5 at `medium`, while a `low` git turn stays on Haiku 5.5 at `high`. [Configuration](configuration.md#activity-routing) has the full matrix and how to change it.
140
+ A mixed turn such as "fix it and commit" takes the hardest part, here `code`. The router then picks the route by tier and activity. With the default overrides, a `low` coding turn runs on Sonnet 5.5 at `high`, a `low` git turn stays on Haiku 5.5 at `high`, and a `medium` git turn moves from Opus 5.5 to Haiku 5.5 at `high`. [Activity routing](activity-routing.md) explains the default matrix, why each cell is there, and how to change it.
122
141
 
123
142
  The mode decides what happens with the label:
124
143
 
125
- | Mode | What the router does |
126
- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
127
- | `off` | Asks nothing new. The routes are the tier routes. |
128
- | `shadow` | The default. Shows the activity, records the stats, and works out what `on` would run. The tier route still runs; nothing changes. |
129
- | `on` | Applies the activity overrides. This is opt-in: run `/router activities on`. |
144
+ | Mode | What the router does |
145
+ | -------- | ---------------------------------------------------------------------------------------------------- |
146
+ | `on` | The default. Applies the activity overrides. |
147
+ | `shadow` | Shows the activity, records the stats, and works out what `on` would run. The base route still runs. |
148
+ | `off` | Does not ask the activity: the classifier is asked for the tier only. The base routes run. |
149
+
150
+ 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.
130
151
 
131
- In `shadow` you can see what `on` would do before you switch it on. The band marks the label `(shadow)` and dims it, and the **Now** tab says `low + code would use Sonnet 5.5 · medium (shadow; using Haiku 5.5 · high)`, or `same route` when both agree. In `on` the **Now** tab reads `low + code → Sonnet 5.5 · medium (override)` with the tier's base route next to it, or `(base)` when the cell has no override.
152
+ 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.
132
153
 
133
154
  How the router moves inside a tier:
134
155
 
135
156
  - It compares routes, not labels. If the new activity resolves to the route already running, nothing switches.
136
157
  - 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.
137
- - An activity applies only when the classifier gives it at least 60% probability (`policy.activityMass`). Below that, or on `uncertain`, the turn goes back to its tier's route, if the move passes the same checks. 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.
138
- - A pinned turn uses the pin's tier route and shows no activity.
139
- - 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 tier route always runs, as in 1.5.
158
+ - 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.
159
+ - A pinned turn uses the pin's base route and shows no activity.
160
+ - 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.
140
161
  - 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.
141
162
 
142
163
  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.
143
164
 
144
165
  ### Read the activity on the pane
145
166
 
146
- - **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%`. The **Route** line shows the route the cell resolves to. **Replies** has a letter row under the strip.
147
- - **Routing**: the **ACTIVITIES** matrix shows the effective routes per tier, with `·` where a cell uses the tier's route, and counts the distinct routes, because each is its own cache. **OVERRIDES** lists each override with a model, an effort, and **remove**, plus a selector to add one and the mode selector. 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 one that adds a cache.
148
- - **Usage**: **ACTIVITY · this session** lists turns, requests, and share per activity, the switches split by tier and by activity, 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.
167
+ - **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.
168
+ - **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, because the router counts each as its own cache. 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 (model, effort) pair, which adds a cache.
169
+ - **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.
149
170
 
150
- **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`), lateral switches taken and refused, and the **Shadow** line summed over all shadow turns. 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 after each turn. **Reset activity stats** clears the session counts and the counts kept across sessions.
171
+ **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 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.
151
172
 
152
- `/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%)`.
173
+ `/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`.
153
174
 
154
175
  ## Change routing
155
176
 
@@ -161,10 +182,11 @@ The band's activity label appears only when the activity applies, so a weak or `
161
182
  | `/router pin <micro\|low\|medium\|high>` | Pin the next turn and its tool continuations. Routing on must already be enabled. |
162
183
  | `/router activities <off\|shadow\|on>` | Set the [activity routing](#route-by-activity) mode. Saved to `router.json` at once; **Undo** reverts it. |
163
184
  | `/model <name>` | Select a model and turn routing off. Use `/router auto` to turn it back on. |
164
- | **Routing on** / **Routing off** | The same as `/router auto` and `/router off`. |
185
+ | **Turn on** / **Turn off** on the band | The same as `/router auto` and `/router off`. |
186
+ | **on** / **off** on the pane (`o` / `f`) | The same as `/router auto` and `/router off`. |
165
187
  | **pin** on the Now tab | Pin that tier for the next turn. Routing on must already be enabled. |
166
188
 
167
- A pin does not change the next turn after the pinned turn finishes. A fresh session on a model that one of the tiers routes to starts with routing on. A fresh session on any other model starts with routing off. `/clear` starts the new session with routing on. Resuming a saved session restores its saved routing on or off.
189
+ A pin does not change the next turn after the pinned turn finishes. A fresh session on a model that a tier routes to, or with activity routing `on` a model an activity override uses (Sonnet 5.5 on the defaults), starts with routing on. A fresh session on any other model starts with routing off. `/clear` starts the new session with routing on. Resuming a saved session restores its saved routing on or off.
168
190
 
169
191
  ## Edit routes and policy
170
192
 
@@ -183,6 +205,7 @@ Under **Policy** on the same tab, pick the values. One **Save** writes them with
183
205
  - **Votes to go down:** 1, 2, or 3 consecutive votes before a cheaper tier. A new or reset history needs one.
184
206
  - **Payback horizon:** 1, 3, 5, or 10 later turns used by the downgrade estimate.
185
207
  - **Credits cap:** $0.50, $1, $2, or $5 for an estimated cold cache write on a `credits` model.
208
+ - **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).
186
209
 
187
210
  **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.
188
211
 
@@ -198,9 +221,9 @@ Router asks one classifier per turn. Five are built in:
198
221
  | OpenAI | OpenAI, `gpt-6-luna` | OpenAI API key | 3,000 ms |
199
222
  | Ollama | Local Ollama, `qwen3.5:9b` | None | 5,000 ms |
200
223
 
201
- ![The Classifier tab: classifier rows with the active one marked, 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)
224
+ ![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)
202
225
 
203
- 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.
226
+ 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.
204
227
 
205
228
  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.
206
229
 
@@ -237,24 +260,25 @@ Keep the plugin enabled: in v1 it is the Mod. The Jev key option keeps its saved
237
260
 
238
261
  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`.
239
262
 
240
- To stop routing for a session, run `/router 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.
263
+ 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.
241
264
 
242
265
  ## Troubleshooting
243
266
 
244
- | Symptom | Cause | Fix |
245
- | ------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
246
- | Status says `no API key` or `no API token` | The active classifier's plugin option is unset or unavailable to this process. | Select **Set up** in the pane, or run `/plugin configure router`. Save the option and start a new turn. |
247
- | Status says `no account ID` | Clef or Clef Flash is active without the Cloudflare account ID. | Run `/plugin configure router` and save the Cloudflare account ID. |
248
- | Route stays on the current model | The classifier timed out, failed, is paused, or network policy refused it. | Read the status band and the pane header. Network policy refusal is not bypassed. |
249
- | `/model` changed but routing stopped | Choosing a model turns routing off. | Run `/router auto` to turn routing back on. |
250
- | Router reports invalid configuration | `router.json` is invalid, or project/local settings redirect the router profile. | Inspect `router.json`, remove project/local `HOME` or `CLAUDE_CONFIG_DIR` overrides, or run the [migration command](configuration.md#convert-an-older-routerjson). |
251
- | Router says old settings need migration | `router.json` still contains v0.8 gateway keys or the 1.1 `jev` section. | Run the [migration command](configuration.md#convert-an-older-routerjson). |
252
- | `⚠ OpenAI rejected the key · keeping model` | The OpenAI key is wrong, revoked, or lacks access to `gpt-6-luna`. | Run `/plugin configure router` and save a valid OpenAI API key. |
253
- | `⚠ Ollama unreachable · keeping model` | No Ollama server listens on `127.0.0.1:11434`. | Run `ollama serve`, then start a new turn. |
254
- | `⚠ Ollama timed out · keeping model` | The model is loading after an idle period, or the machine is slow. | Wait for one more turn. If it recurs, raise `classifiers.ollama.timeoutMs` in `router.json`. |
255
- | `⚠ Ollama request failed · keeping model` | The tag in `model` is not pulled, or Ollama rejected a request setting. | Run `ollama pull <model>` for the tag in `model`, or choose another model. |
256
- | Band reads `v0.8 gateway settings remain` | The `jev-router[1m]` model or the `127.0.0.1:43170` base URL is still set. | Run `/router`: it lists the keys. Remove them as in the [migration checklist](configuration.md#convert-a-v08-configuration) and restart. |
257
- | Router controls are unavailable | Claude Code is older than 2.1.289. | Update Claude Code. |
258
- | Context reads as unknown | The router lacks a reliable local estimate or current-history measurement. | Keep using the current model, or start a new history with a supported context estimate. |
267
+ | Symptom | Cause | Fix |
268
+ | ------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
269
+ | Status says `no API key` or `no API token` | The active classifier's plugin option is unset or unavailable to this process. | Select **Set up** in the pane, or run `/plugin configure router`. Save the option and start a new turn. |
270
+ | Status says `no account ID` | Clef or Clef Flash is active without the Cloudflare account ID. | Run `/plugin configure router` and save the Cloudflare account ID. |
271
+ | Route stays on the current model | The classifier timed out, failed, is paused, or network policy refused it. | Read the status band and the pane header. Network policy refusal is not bypassed. |
272
+ | `/model` changed but routing stopped | Choosing a model turns routing off. | Run `/router auto` to turn routing back on. |
273
+ | Router reports invalid configuration | `router.json` is invalid, or project/local settings redirect the router profile. | Inspect `router.json`, remove project/local `HOME` or `CLAUDE_CONFIG_DIR` overrides, or run the [migration command](configuration.md#convert-an-older-routerjson). |
274
+ | Router says old settings need migration | `router.json` still contains v0.8 gateway keys or the 1.1 `jev` section. | Run the [migration command](configuration.md#convert-an-older-routerjson). |
275
+ | `⚠ OpenAI rejected the key · keeping model` | The OpenAI key is wrong, revoked, or lacks access to `gpt-6-luna`. | Run `/plugin configure router` and save a valid OpenAI API key. |
276
+ | `⚠ Ollama unreachable · keeping model` | No Ollama server listens on `127.0.0.1:11434`. | Run `ollama serve`, then start a new turn. |
277
+ | `⚠ Ollama timed out · keeping model` | The model is loading after an idle period, or the machine is slow. | Wait for one more turn. If it recurs, raise `classifiers.ollama.timeoutMs` in `router.json`. |
278
+ | `⚠ Ollama request failed · keeping model` | The tag in `model` is not pulled, or Ollama rejected a request setting. | Run `ollama pull <model>` for the tag in `model`, or choose another model. |
279
+ | Band reads `v0.8 gateway settings remain` | The `jev-router[1m]` model or the `127.0.0.1:43170` base URL is still set. | Run `/router`: it lists the keys. Remove them as in the [migration checklist](configuration.md#convert-a-v08-configuration) and restart. |
280
+ | Router controls are unavailable | Claude Code is older than 2.1.289. | Update Claude Code. |
281
+ | Pane reads `ROUTING unavailable` | Old gateway settings, an old Claude Code, or an invalid `router.json`. The line under it names which. | Fix the cause it names and restart. Until then every turn keeps Claude's model, and `/router auto`, `off`, `pin`, and `activities` reply with the reason and change nothing. |
282
+ | Context reads as unknown | The router lacks a reliable local estimate or current-history measurement. | Keep using the current model, or start a new history with a supported context estimate. |
259
283
 
260
284
  For the internal event flow and network deadline behavior, see [Architecture](architecture.md). For what the test traces do and do not show, see [Evaluation](evaluation.md).