@alexeiled/claude-router 1.20.1 → 1.21.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +27 -0
- package/README.md +3 -3
- package/docs/activity-routing.md +1 -1
- package/docs/architecture.md +5 -3
- package/docs/configuration.md +9 -8
- package/docs/evaluation.md +4 -4
- package/docs/native-router.md +11 -11
- package/docs/providers.md +3 -3
- package/docs/router-band.svg +158 -137
- package/docs/router-pane-classifier.svg +21 -23
- package/docs/router-pane-now.svg +138 -173
- package/docs/router-pane-policy.svg +21 -23
- package/docs/router-pane-routes.svg +32 -34
- package/docs/router-pane-usage-whatif.svg +139 -157
- package/docs/router-pane-usage.svg +165 -165
- package/docs/user-guide.md +129 -70
- package/hooks/native-router.mjs +9 -5
- package/lib/band.mjs +254 -172
- package/lib/config.mjs +24 -15
- package/lib/cost.mjs +26 -10
- package/lib/costs.mjs +156 -0
- package/lib/display.mjs +102 -93
- package/lib/panel.mjs +486 -445
- package/lib/policy.mjs +1 -1
- package/lib/prices.mjs +113 -0
- package/lib/providers.mjs +9 -21
- package/lib/route.mjs +1 -1
- package/lib/savings.mjs +14 -8
- package/lib/subagents.mjs +3 -3
- package/package.json +2 -1
package/docs/user-guide.md
CHANGED
|
@@ -36,38 +36,58 @@ The pane shows its provider and file path.
|
|
|
36
36
|
|
|
37
37
|
## Read the status band
|
|
38
38
|
|
|
39
|
-
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
|
|
39
|
+
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 and the switch cost, then context and cache, then the activity, then the reason. The meter and the model always stay, except behind a classifier warning: the warning and its **Set up** button come first, and the route gives way to them.
|
|
40
40
|
|
|
41
|
-

|
|
42
42
|
|
|
43
|
-
Read the first line
|
|
43
|
+
Read the first line from left to right:
|
|
44
44
|
|
|
45
|
-
- **Tier meter** `▂▄▆█`: one bar per tier, lit up to the current tier in its color, like signal strength.
|
|
46
|
-
- **
|
|
47
|
-
- **
|
|
45
|
+
- **Tier meter** `▂▄▆█`: one bar per tier, lit up to the current tier in its color, like signal strength. The same bars name the tiers everywhere: `▂` micro, `▂▄` low, `▂▄▆` medium, `▂▄▆█` high.
|
|
46
|
+
- **Model**: the model and effort that run this turn, such as `Opus 5.5 · xhigh`. **fallback** after it means Claude Code answered with another model.
|
|
47
|
+
- **Activity**: the kind of work, in orange italic: `code`, `debug`, `explore`, `plan`, `review`, `ops` (commands: git, builds, tests, CI) or `docs`. See [Route by activity](#route-by-activity). When the reason already names the activity, the band does not repeat it.
|
|
48
|
+
- **Reason**: a glyph and a few words. `↑` moved up, `↓` moved down, `=` stayed, `…` waits, `!` a problem, `⏵` a pin: `↑ clearly stronger`, `↓ cheaper fits`, `= fits`, `… cheaper, waiting`, `↑ code` for an activity move.
|
|
48
49
|
- **Classifier support**: what the active classifier, such as Jev or Clef Flash, gave the switch against the bar the policy required, such as `Jev 88% ≥ 82%`. When whole percents would read as equal, it shows tenths: `Jev 81.0% < 81.4%`.
|
|
49
|
-
- **
|
|
50
|
-
- **ctx** and **cache
|
|
51
|
-
|
|
52
|
-
| Band shows
|
|
53
|
-
|
|
|
54
|
-
|
|
|
55
|
-
|
|
|
56
|
-
| `⏵ next
|
|
57
|
-
| `⚠ Jev: no API key
|
|
58
|
-
| `⚠ Clef: no account ID
|
|
59
|
-
| `⚠ Jev timed out
|
|
60
|
-
| `○
|
|
61
|
-
| `✕
|
|
62
|
-
|
|
|
63
|
-
|
|
64
|
-
|
|
50
|
+
- **Switch cost**: `switch ≈ $0.48`, the policy's price for the switch it weighed this turn, mostly the prompt cache the other model must write. For a move to a cheaper model it is net of what that model saves over the next turns. The higher the cost, the higher the bar a stronger model must clear.
|
|
51
|
+
- **ctx** and **cache**: a gauge of context use on the model that runs next, and the share of input read from the cache on the last reply. The gauge turns yellow at 60% and red at 80%.
|
|
52
|
+
|
|
53
|
+
| Band shows | Meaning |
|
|
54
|
+
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
55
|
+
| `▂▄▆█ Opus 5.5 · xhigh ready` | Routing is on and ready for a new turn. |
|
|
56
|
+
| `▂▄▆█ choosing… Jev ≤ 1.5 s` | The classifier and local policy are running, within the classifier's deadline. The spinner says `Choosing model`. |
|
|
57
|
+
| `⏵ next ▂▄▆ Opus·medium ✕` | A pin is set for the next turn. **✕** cancels it. |
|
|
58
|
+
| `⚠ Jev: no API key [ Set up ]` | The active classifier lacks a setting; routing keeps the model (`= no advice`). **Set up** opens the secure plugin dialog. |
|
|
59
|
+
| `⚠ Clef: no account ID [ Set up ]` | Clef has its API token but no Cloudflare account ID. **Set up** opens the dialog. |
|
|
60
|
+
| `⚠ Jev timed out [ Details ]` | The classifier failed: timed out, unreachable, rejected the key, or paused. **Details** opens the pane. |
|
|
61
|
+
| `○ Opus 5.5 · xhigh [ Turn on ] routing off` | Routing is off: Claude's model answers every turn. **Turn on** turns it back on. The footer also shows `routing off`. |
|
|
62
|
+
| `✕ Opus 5.5 · xhigh [ Fix ] routing unavailable` | Nothing routes: a missing/invalid provider file, an old Claude Code, or leftover v0.8 settings. **Fix** opens the pane. |
|
|
63
|
+
| `agent ■ Haiku 5.5 ↓ from Opus 5.5 (Claude Code’s pick)` | You are viewing a subagent's transcript: the model it runs on, and who picked it; see below. |
|
|
64
|
+
|
|
65
|
+
**Turn on** and **Fix** sit next to the model and stay at any width.
|
|
66
|
+
|
|
67
|
+
### The hover row and two rows
|
|
68
|
+
|
|
69
|
+
While routing is on, hover over the band for a second row: a pin per tier, low to high, each named by what it runs (`▂▄ Haiku·high`); **Turn off**; and **2 rows** or **1 row**. A pin forces that tier for the next turn only. On a narrow band the pins lose their model names first; **Turn off** and the row choice stay. The hover row needs a pointer: from the keyboard, run `/router off`, or open the pane and press `f`.
|
|
70
|
+
|
|
71
|
+
**2 rows** adds the session under the route, in the same numbers as the pane's SESSION block. On a Claude plan it leads with the plan windows Claude Code reports:
|
|
72
|
+
|
|
73
|
+
```text
|
|
74
|
+
plan 5h ▰▰▰▰▱▱▱▱ 48% ↻18:00 7d 43% session ≈$6.40 API value −$1.84 (−22%) vs no routing 64 replies
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
On an API key, or a provider billed in credits, the same row reads `session $6.40 billed −$1.84 (−22%) vs no routing 64 replies`. Read it as: this session's replies and subagents cost $6.40 at list prices, $1.84 less than without the router. **No routing** is your model on every main-thread reply and Claude Code's own pick for every subagent, priced on the same tokens. Minus is cheaper than no routing, plus is dearer; past double it reads as a ratio, `+$2.48 (×5.0)`. `≈` marks [API value](#how-dollars-are-paid): plan quota, not a charge. A profile that mixes plan and credits models adds the billed part, `billed $4.10`. Before the tenth routed reply the difference adds `· early`, because one switch can decide a short run. Some situations change the middle part:
|
|
78
|
+
|
|
79
|
+
- `effort low 4 · high 2`: the profile runs one model and routing moves only the effort, so no saving is estimated; see [Providers](providers.md).
|
|
80
|
+
- `3 of 20 not compared`: some replies have no comparison, such as on a provider whose cache hit rate cannot be known; no saving is shown.
|
|
81
|
+
|
|
82
|
+
The router's total counts the replies it routes and the subagents. Claude Code's `/cost` also counts side calls the router does not see, such as titles and compaction, and its server-side tools; run `/cost` for the whole session cost.
|
|
83
|
+
|
|
84
|
+
When the row is short, the reset time, the counts and the words drop first; the 5h window and the session total stay. Router remembers the one- or two-row 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.
|
|
65
85
|
|
|
66
86
|
The band steps aside while a survey needs the space.
|
|
67
87
|
|
|
68
|
-
Inside a turn the router checks the route again as the work changes; see [Changes during a task](#changes-during-a-task). A subagent gets at most one model, when it starts, and keeps it for every step: For the Anthropic profile, these are Haiku for exploration, Opus for clearly hard tasks, and Sonnet for the rest. Other profiles have [their own defaults](providers.md#activity-overrides). An agent that pins a model in its definition keeps it, unless it sets `modelRouting: auto`. The Usage tab's **SUBAGENTS** section shows what each agent type ran on and cost, and the Now tab
|
|
88
|
+
Inside a turn the router checks the route again as the work changes; see [Changes during a task](#changes-during-a-task). A subagent gets at most one model, when it starts, and keeps it for every step: For the Anthropic profile, these are Haiku for exploration, Opus for clearly hard tasks, and Sonnet for the rest. Other profiles have [their own defaults](providers.md#activity-overrides). An agent that pins a model in its definition keeps it, unless it sets `modelRouting: auto`. The Usage tab's **SUBAGENTS** section shows what each agent type ran on and cost, and the Now tab adds this session's agents to its total. See [Subagent routing](configuration.md#subagent-routing).
|
|
69
89
|
|
|
70
|
-
In a subagent's transcript the band names the model the agent runs on and who picked it.
|
|
90
|
+
In a subagent's transcript the band names the model the agent runs on and who picked it. `agent ■ Haiku 5.5 ↓ from Opus 5.5 (Claude Code’s pick)` means the router chose a cheaper model than Claude Code would have; `↑` means a stronger one. A hollow `□` means the agent ran on Claude Code's pick, because the router agreed or did not route it, and says why: `agent □ Opus 5.5 = Claude Code’s pick: the workflow sets it`. A narrow band drops the comparison first. The band falls back to `agent · model chosen at spawn` when the router has no record of the agent, such as after a plugin reload, and to `agent · keeps its own model (subagent routing off)`.
|
|
71
91
|
|
|
72
92
|
## Open the router pane
|
|
73
93
|
|
|
@@ -75,21 +95,43 @@ Run `/router` or select **Router** above the prompt. Without a UI surface, as in
|
|
|
75
95
|
|
|
76
96
|
| Tab | What it answers |
|
|
77
97
|
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
78
|
-
| 1 Now | What runs next turn, and why, with a **pin** per tier; this session
|
|
98
|
+
| 1 Now | What runs next turn, and why, with a **pin** per tier; the plan windows; this session's cost against no routing; context and cache. |
|
|
79
99
|
| 2 Routes | Which model runs: one grid of tiers by activities, the activity routing mode, and an editor for the selected cell. |
|
|
80
100
|
| 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. |
|
|
81
101
|
| 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. |
|
|
82
|
-
| 5 Usage | What routing cost against
|
|
102
|
+
| 5 Usage | What routing cost against no routing this session, today, over 7 or 30 days, this month or in all: by activity, model or tier, and what is worth a look. |
|
|
83
103
|
|
|
84
|
-
The top line of every tab, `
|
|
104
|
+
The top line of every tab, `ROUTER [ ◉ on ] [ ○ off ] Jev ready · 347 ms`, shows the routing mode, switches it, and says whether the classifier is ready. Press `o` or `f` while the pane has focus. The tabs under it carry their digits, `[ 1 Now ] [ 2 Routes ] …`, and **?** shows what the numbers mean above the tab. When routing is unavailable, the top line reads `ROUTER unavailable Claude’s model is kept` with the reason under it, and offers no on or off: see [Troubleshooting](#troubleshooting).
|
|
85
105
|
|
|
86
|
-

|
|
87
107
|
|
|
88
|
-
The **Now** tab
|
|
108
|
+
The **Now** tab has four blocks, each with its name in capitals.
|
|
89
109
|
|
|
90
|
-
**
|
|
110
|
+
**NEXT TURN** answers "what runs next turn, and why". The first line is the tier meter, the model and effort, and the classifier's activity with its share, such as `code 84% debug 8%`. When an activity override runs, a line under it names the tier's own route. **why** gives the reason in the band's words and, beside it, the classifier's support against the bar the policy set and the switch cost: `↑ clearly stronger Jev 88% ≥ 82% · switch ≈ $0.48`. **pin** has one button per tier, low to high, each named by what it runs, such as `▂▄ Haiku·high 3%`, with the support the classifier gave it on the last turn; `▶` marks the tier that runs now. A press forces that tier for the next turn only, and `⏵ next turn ▂▄▆ Opus·medium [ unpin ]` shows the pin until it applies. With routing off, the block names Claude's model, `routing off · /model choice`, and the pins say they need routing on; nothing from an earlier routed turn stays.
|
|
91
111
|
|
|
92
|
-
**
|
|
112
|
+
**PLAN** appears on a Claude plan: Claude Code's 5-hour and 7-day windows as gauges, with when each resets. They turn yellow at 75% and red at 90%.
|
|
113
|
+
|
|
114
|
+
**SESSION** sums this session, the main thread and its subagents: `since 14:18 · 86 replies · 6 agents · 9 switches`, and `● 1 running` while a subagent is in the middle of a turn (an agent that waits on its own background command is not counted until it resumes). The counts include the replies of the turn still running.
|
|
115
|
+
|
|
116
|
+
```text
|
|
117
|
+
SESSION since 14:18 · 86 replies · 6 agents · 9 switches ● 1 running
|
|
118
|
+
≈$8.97 API value · plan quota, not billed [ Usage ]
|
|
119
|
+
−$4.09 (−31%) vs no routing of ≈$13.06
|
|
120
|
+
main ≈$6.45 ████████████████ −$4.17 vs Opus 5.5 · xhigh
|
|
121
|
+
agents ≈$2.52 ██████░░░░░░░░░░ +$0.08 vs their picks
|
|
122
|
+
tiers ███████████████████████████████████████████ 2 replies per cell
|
|
123
|
+
▂▄ 41 ▂▄▆ 12 ▂▄▆█ 33
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
- The first line is the total and how it is paid: `API value · plan quota, not billed` on a plan, `billed at list prices` on an API key or credits, and `API value · $4.10 of it billed as credits` when a profile mixes the two. See [How dollars are paid](#how-dollars-are-paid). **Usage** opens the Usage tab on this session.
|
|
127
|
+
- The second line is the difference against no routing and what no routing would have cost. The parts add up: main and agents make the total, and their differences make the session's difference (−$4.17 + $0.08 = −$4.09). Before the tenth main reply it adds `early sample`; a narrow pane drops that note first.
|
|
128
|
+
- **main** compares the main thread with your model, **agents** compares the subagents with Claude Code's picks. The bars share one scale.
|
|
129
|
+
- An effort-only profile shows `effort routing on one model: no saving is estimated` and its effort mix instead. When some replies have no comparison, the block says how many and shows no saving.
|
|
130
|
+
- When cache rebuilds cost more than the cheaper models saved, `▲ switches cost more than they saved` follows, with **Policy** to raise the bar for a switch.
|
|
131
|
+
- **tiers** is a strip that colors every reply since Claude Code started the session by the tier that served it; a dot marks replies routing did not serve, such as those with routing off. Each cell is one reply up to 48 cells. Past that, and on a pane too narrow for the cells, pairs of cells merge and the strip says how many replies a cell holds. After Claude Code restarts a resumed session, the strip starts again and says since when, such as `since 15:02`. The replies per tier, low to high, follow as their meters.
|
|
132
|
+
- Replies on a model without a list price reach the strip but have no cost: the block says `no priced replies: cost unknown`.
|
|
133
|
+
|
|
134
|
+
**CONTEXT** gives the context gauge on the model that runs next, with the tokens against its window, and the cache reuse of the last reply and of the session. **details** adds the counters and estimates in [Understand usage and estimates](#understand-usage-and-estimates).
|
|
93
135
|
|
|
94
136
|
### Save and undo changes
|
|
95
137
|
|
|
@@ -100,37 +142,54 @@ The settings tabs follow one of two rules, and the section captions say which:
|
|
|
100
142
|
|
|
101
143
|
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.
|
|
102
144
|
|
|
103
|
-
### Compare routing with
|
|
145
|
+
### Compare routing with no routing
|
|
104
146
|
|
|
105
|
-

|
|
106
148
|
|
|
107
|
-
The Usage tab keeps observed routed spend and, when the cache history permits it, compares
|
|
149
|
+
The Usage tab keeps observed routed spend and, when the cache history permits it, compares it with **no routing**: your model on every main-thread reply and Claude Code's own pick for every subagent, priced on the same tokens. Your model is the model `/model` (or `--model`) selected, at the session effort, when a reply ran. The router prices observed tokens at the list prices in `router.json`.
|
|
108
150
|
|
|
109
151
|
The top row picks the period: **Session**, **Today**, **7d** (today and the six days before), **30d**, **Month** (since the first of this month) and **All**. Press `p` for the next one. The pane remembers the choice across sessions. Session holds this session's replies, and the line under the row names your model, or every model when `/model` changed during the session. The other periods add up the replies of every session on those calendar days. Each session counts against its own model, and the line reads `all projects · Oct 7 – Oct 13 · each session vs its own model`.
|
|
110
152
|
|
|
111
|
-
When
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
153
|
+
When the period is comparable, the difference comes first, then one table whose cents add up:
|
|
154
|
+
|
|
155
|
+
```text
|
|
156
|
+
−$12.29 (−37%) vs no routing
|
|
157
|
+
|
|
158
|
+
cost vs no routing no routing
|
|
159
|
+
main · 221 replies ≈$15.33 −$11.78 ≈$27.11
|
|
160
|
+
cheaper models −$12.29
|
|
161
|
+
cache rebuilds +$0.51 4% of the saving
|
|
162
|
+
agents · 15 ≈$5.60 −$0.51 ≈$6.11
|
|
163
|
+
─────────────────────────────────────────────────────────────
|
|
164
|
+
7 days · ≈ API value ≈$20.93 −$12.29 ≈$33.22
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
| Row | What it is |
|
|
168
|
+
| ---------------- | ------------------------------------------------------------------------------------------------------------ |
|
|
169
|
+
| main | The main thread's routed replies, against the same tokens on your model with one cache that never switched. |
|
|
170
|
+
| cheaper models | What routing saved on replies that ran on models cheaper than yours. |
|
|
171
|
+
| stronger models | What replies on models stronger than yours cost on top. Shown only when not zero. |
|
|
172
|
+
| cache rebuilds | What rewriting the prompt cache after a model switch cost, and its share of the saving. |
|
|
173
|
+
| agents | The subagents, against the same tokens on Claude Code's pick for each. |
|
|
174
|
+
| total | The period's cost, its difference, and what no routing would have cost: `billed` or `≈ API value`. |
|
|
175
|
+
|
|
176
|
+
Each row reads across: cost − no routing = the difference. Down the table, main and agents make the total, and cheaper models, stronger models and cache rebuilds make main's difference. A profile that mixes plan and credits models adds `billed as credits` under the total. Below 10 routed replies the difference adds `early sample`, because one switch and its cache write can decide a short run.
|
|
177
|
+
|
|
178
|
+
When some replies have no comparison, the tab says `3 of 20 replies have no comparison: no saving is shown.`, and the table shows the cost alone. Counts, tokens, breakdowns and trends still include those replies; a row with incomplete coverage shows `—` against no routing, and **What if** stays unavailable rather than inventing a baseline. This is common with automatic provider caches, whose future hit rates are unknown. An effort-only profile says `Effort routing on one model: no saving is estimated; the cost is what was billed.`
|
|
116
179
|
|
|
117
|
-
|
|
180
|
+
#### How dollars are paid
|
|
118
181
|
|
|
119
|
-
|
|
120
|
-
| --------------------- | ---------------------------------------------------------------------------------------------- |
|
|
121
|
-
| Your model | What the same input and output tokens cost on your model, with one cache that never switched. |
|
|
122
|
-
| − Cheaper models | What routing saved on replies that ran on models cheaper than yours. |
|
|
123
|
-
| + Stronger models | What replies on models stronger than yours cost on top. |
|
|
124
|
-
| + Cache rebuilds | What rewriting the prompt cache after a model switch cost, and its share of the saving. |
|
|
125
|
-
| = Routed | What the routed replies cost, with a bar against your model: `54% of your model`, or `×2.1`. |
|
|
182
|
+
Every dollar in the band, `/router`, the Now tab and Usage is the same measure: the reply's tokens at the list prices in `router.json`. How it is paid decides its label:
|
|
126
183
|
|
|
127
|
-
|
|
184
|
+
- **On a Claude plan** it is quota, not a charge: an API value, shown with `≈`, such as `≈$8.97 API value`. The plan's windows are on the band and the Now tab.
|
|
185
|
+
- **On an API key, or a provider billed in credits**, it is what is billed: `$8.97 billed`.
|
|
186
|
+
- **A profile that mixes the two**, such as the [model-proxy profile](providers.md#mix-anthropic-and-deepseek-with-model-proxy) with Opus on the plan and DeepSeek in credits, gets one sum and one comparison, and says which part is billed: `≈$24.10 API value · billed $4.10`.
|
|
128
187
|
|
|
129
|
-
|
|
188
|
+
The router reads the plan from Claude Code's plan windows, from the first reply on; until then a plan session reads as billed, with nothing spent yet. `billing` in `router.json` sets only the credits cap on cold cache writes. The router's dollars leave out what it does not see: titles, compaction, server-side tools and classifier charges. For the whole session cost, run Claude Code's `/cost`.
|
|
130
189
|
|
|
131
|
-
A line of counts follows: replies, turns, input tokens, the share of the input read from the cache, and output tokens. With routing off or unavailable and no routed reply this session, the tab says the replies use your model and are not counted.
|
|
190
|
+
A line of counts follows the table: replies, turns, input tokens, the share of the input read from the cache, and output tokens. With routing off or unavailable and no routed reply this session, the tab says the replies use your model and are not counted.
|
|
132
191
|
|
|
133
|
-
**BY** splits the period's cost by **Activity**, **Model** or **Tier**. Press `g` for the next grouping. Each row gives the replies, the routed cost and
|
|
192
|
+
**BY** splits the period's cost by **Activity**, **Model** or **Tier**. Press `g` for the next grouping. Each row gives the replies, the routed cost and its difference against no routing. The last column is the route most of the row's replies used, or, by model, the row's share of the cost. By tier the rows run low to high, each named by its meter. Select **▸** to open a row. An activity lists its routes, and a model or a tier lists its activities. A line under them gives the row's cheaper, stronger and cache-rebuild parts and its tokens. A narrow pane drops the last column first.
|
|
134
193
|
|
|
135
194
|
The next line draws the routed cost as blocks: **COST BY HOUR** over today's hours for Session and Today, **COST BY WEEK** for a period longer than 45 days, and **COST BY DAY** otherwise. A dot is a bucket without replies. **What if** (`c`) shows instead the period's tokens priced on each model alone, beside the routed cost and your model. It answers whether a cheaper default would have cost less than routing. A model without a price for some reply is left out. **Trend** (`c`) goes back.
|
|
136
195
|
|
|
@@ -142,29 +201,29 @@ From 20 routed replies in the period, **WORTH A LOOK** lists up to three finding
|
|
|
142
201
|
|
|
143
202
|
Each line has a button to the tab that changes it. **Routes** opens that cell in the grid, and **Policy** the switching thresholds. The tab never says which model to use, because it does not measure answer quality.
|
|
144
203
|
|
|
145
|
-
**All** also counts the totals that earlier versions kept without dates, and says so: `includes $4.10 routed before dated records, kept without a breakdown`. The breakdown and the trend start at the first dated day. The router keeps the daily records for 400 days.
|
|
204
|
+
**All** also counts the totals that earlier versions kept without dates, and says so under the total: `includes $4.10 routed before dated records, kept without a breakdown`. The breakdown and the trend start at the first dated day. The router keeps the daily records for 400 days.
|
|
146
205
|
|
|
147
206
|
**Delete history**, at the bottom, asks once more, then deletes the usage, activity and subagent records of every session and clears this session's counts. Nothing brings them back. To look at a shorter span, pick a period instead.
|
|
148
207
|
|
|
149
|
-
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.
|
|
208
|
+
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. 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-no-routing) explains the method.
|
|
150
209
|
|
|
151
|
-

|
|
152
211
|
|
|
153
212
|
### Understand usage and estimates
|
|
154
213
|
|
|
155
|
-
- **
|
|
156
|
-
- **Context** compares the larger available context reading with the
|
|
214
|
+
- **Plan windows** are Claude Code's 5-hour and 7-day readings of the plan quota used. A reset time that has passed is not shown, because the reading is then stale.
|
|
215
|
+
- **Context** compares the larger available context reading with the configured window of the model that runs next. Values can be unknown when Claude does not provide the needed estimate. A route never moves to a model whose window the context would fill past 80%.
|
|
157
216
|
- **Cache** reuse is cache-read tokens divided by the last response's input counters.
|
|
158
|
-
- **Classifier support**, such as **Jev support**, is the probability the classifier gave each tier on the last classified turn.
|
|
159
|
-
- **Route switches** on the Now tab count the turns whose route differed from the turn before: a change of model or effort, so a move from Sonnet to Haiku inside `low` counts too, although its strip color stays. They are the switches the Usage tab counts, and a pin is not one. **
|
|
217
|
+
- **Classifier support**, such as **Jev support**, is the probability the classifier gave each tier on the last classified turn. **why** on the Now tab compares the support for a switch with the bar the policy required, and shows the estimated switch cost.
|
|
218
|
+
- **Route switches** on the Now tab count the turns whose route differed from the turn before: a change of model or effort, so a move from Sonnet to Haiku inside `low` counts too, although its strip color stays. They are the switches the Usage tab counts, and a pin is not one. **Cache rebuilds** is the cache-write cost of those switches inside the saving.
|
|
160
219
|
- **Input per reply**, under **details** on the Now tab, scales the input sizes of the last 30 replies from the lowest to the highest reading. It is a scale comparison, not a forecast.
|
|
161
220
|
- **Cache hits saved** is a configured-price estimate for cached reads before write costs. It is not a measured saving.
|
|
162
221
|
- **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.
|
|
163
222
|
- **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.
|
|
164
223
|
|
|
165
|
-
On the Usage tab, **SUBAGENTS** covers the same period as the rest of the tab: this session, or every session in every project that uses this router install (`all projects`), since the last **Delete history**. Each agent is one square, colored by the model it ran on: filled (`■`) when the router moved it off the model Claude Code would have picked, hollow (`□`) when it ran on Claude Code's pick, because the router agreed or did not route it. The models and their agents follow the squares, then how many the router moved, and what routing saved or cost on the routed agents against Claude Code's picks, in the session
|
|
224
|
+
On the Usage tab, **SUBAGENTS** covers the same period as the rest of the tab: this session, or every session in every project that uses this router install (`all projects`), since the last **Delete history**. Each agent is one square, colored by the model it ran on: filled (`■`) when the router moved it off the model Claude Code would have picked, hollow (`□`) when it ran on Claude Code's pick, because the router agreed or did not route it. The models and their agents follow the squares, then how many the router moved, and what routing saved or cost on the routed agents against Claude Code's picks, in the session's words: `routing −$0.10 (−13%) vs Claude Code’s picks on 3 routed agents`. 7d, 30d, Month and All add the agents per day. **ROUTED** lists each agent type the router picked a model for: its squares, agents, cost, and **vs CC**, the same tokens on Claude Code's pick. A row opens to its models, each with how many agents the router kept, moved up or moved down, and to its requests per agent, respawns and classifier failures. **NOT ROUTED** lists the agents Claude Code picked a model for, by reason, with why: `the workflow sets it`, `your model` for a fork, `its agent file sets it`. A row without any priced request says `no price`. Records from before 1.14.0 have no date or model: Session and All add them as one line, and an empty Today or 7d says so. See [Subagent routing](configuration.md#subagent-routing). On the Now tab, **details** adds the context and cache counters, the output of the last reply, the input per reply, and the estimates above.
|
|
166
225
|
|
|
167
|
-
The router keeps no bill.
|
|
226
|
+
The router keeps no bill. Its dollars are estimates at configured list prices and leave out classifier charges and the side calls it does not see; run `/cost` for Claude Code's own session cost.
|
|
168
227
|
|
|
169
228
|
## Route by activity
|
|
170
229
|
|
|
@@ -191,7 +250,7 @@ The mode decides what happens with the label:
|
|
|
191
250
|
|
|
192
251
|
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.
|
|
193
252
|
|
|
194
|
-
When an override runs,
|
|
253
|
+
When an override runs, **NEXT TURN** on the Now tab adds a line with the tier's own route: `code at low runs on Sonnet 5.5 · high · tier route Haiku 5.5 · high`.
|
|
195
254
|
|
|
196
255
|
How the router moves inside a tier:
|
|
197
256
|
|
|
@@ -229,14 +288,14 @@ These thresholds are starting values. They are not tuned on data yet.
|
|
|
229
288
|
|
|
230
289
|
### Read the activity on the pane
|
|
231
290
|
|
|
232
|
-
- **Now**: the **
|
|
291
|
+
- **Now**: the first line of **NEXT TURN** names the classifier's activity with its share and the next answer, such as `code 84% debug 8%`. An `uncertain` answer is shown dim: it applies no activity. In `on`, a line under it names the cell when the route is an override, such as `code at low runs on Sonnet 5.5 · high · tier route Haiku 5.5 · high`, and **why** reads `↑ code` or `↓ ops` when the activity moved the route; a refused move, a hold, or a tier change keeps its reason.
|
|
233
292
|
- **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.
|
|
234
|
-
- **Usage**: **BY** with **Activity** lists the period's replies, cost and difference against
|
|
293
|
+
- **Usage**: **BY** with **Activity** lists the period's replies, cost and difference against no routing per activity, and `mostly on`, the route most of its replies used, such as `Sonnet 5.5 · high`; opening a row lists its routes. Replies whose turn had no applied activity count as `no activity`. The **cache rebuilds** row counts the route switches by tier and by activity together. See [Compare routing with no routing](#compare-routing-with-no-routing).
|
|
235
294
|
- **Classifier**: **THIS SESSION** gives **Agreement**, how often the tools a turn used fit the classifier's activity (see [Evaluation](evaluation.md#tool-agreement)).
|
|
236
295
|
|
|
237
296
|
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. **Delete history** on the Usage tab deletes these counts with the usage and subagent records, for this session and across sessions.
|
|
238
297
|
|
|
239
|
-
`/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 in the band's words, such as `Session:
|
|
298
|
+
`/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 in the band's words, such as `Session: $6.40 billed · −$1.84 (−22%) vs no routing · 64 replies`, after a `Plan: 5h 48% · 7d 43%` line on a Claude plan.
|
|
240
299
|
|
|
241
300
|
## Change routing
|
|
242
301
|
|
|
@@ -265,7 +324,7 @@ A pin does not change the next turn after the pinned turn finishes. A fresh sess
|
|
|
265
324
|
|
|
266
325
|
## Edit routes and policy
|
|
267
326
|
|
|
268
|
-

|
|
269
328
|
|
|
270
329
|
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`.
|
|
271
330
|
|
|
@@ -374,13 +433,13 @@ To stop routing for a session, run `/router off`. To keep tier routing but stop
|
|
|
374
433
|
| A custom profile containing `{}` fails | No built-in model catalog exists for that provider name. | Define all four routes and their model entries. See the [custom profile example](providers.md#add-another-provider). |
|
|
375
434
|
| Router reports invalid configuration | The selected file is invalid, or project/local settings redirect the profile. | Inspect the file shown in the pane. Remove project/local `HOME`, `CLAUDE_CONFIG_DIR`, or `CLAUDE_ROUTER_PROVIDER` overrides. |
|
|
376
435
|
| 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). |
|
|
377
|
-
| `⚠ OpenAI rejected the key
|
|
378
|
-
| `⚠ Ollama unreachable
|
|
379
|
-
| `⚠ Ollama timed out
|
|
380
|
-
| `⚠ Ollama request failed
|
|
436
|
+
| `⚠ OpenAI rejected the key` | The OpenAI key is wrong, revoked, or lacks access to `gpt-6-luna`. | Run `/plugin configure router` and save a valid OpenAI API key. |
|
|
437
|
+
| `⚠ Ollama unreachable` | No Ollama server listens on `127.0.0.1:11434`. | Run `ollama serve`, then start a new turn. |
|
|
438
|
+
| `⚠ Ollama timed out` | The model is loading after an idle period, or the machine is slow. | Wait for one more turn. If it recurs, raise `classifiers.ollama.timeoutMs` in `router.json`. |
|
|
439
|
+
| `⚠ Ollama request failed` | The tag in `model` is not pulled, or Ollama rejected a request setting. | Run `ollama pull <model>` for the tag in `model`, or choose another model. |
|
|
381
440
|
| 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. |
|
|
382
441
|
| Router controls are unavailable | Claude Code is older than 2.1.289. | Update Claude Code. |
|
|
383
|
-
| Pane reads `
|
|
442
|
+
| Pane reads `ROUTER unavailable` | Old gateway settings, an old Claude Code, or an invalid `router.json`. The line under it names which. | Fix the cause it names and restart. Until then every turn keeps Claude's model, and `/router auto`, `off`, `pin`, and `activities` reply with the reason and change nothing. |
|
|
384
443
|
| 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. |
|
|
385
444
|
|
|
386
445
|
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).
|
package/hooks/native-router.mjs
CHANGED
|
@@ -596,7 +596,8 @@ async function routerCommand($, router, args) {
|
|
|
596
596
|
};
|
|
597
597
|
const storedView = await readView($, router);
|
|
598
598
|
const view = { ...storedView, mode: await modeOf($, router, storedView.mode) };
|
|
599
|
-
if (!(await $.session.surfaces()).length)
|
|
599
|
+
if (!(await $.session.surfaces()).length)
|
|
600
|
+
return { text: detailText(router.config, view, await $.session.usage().catch(() => null)) };
|
|
600
601
|
await openPane($, router);
|
|
601
602
|
return {};
|
|
602
603
|
}
|
|
@@ -712,7 +713,7 @@ async function saveConfig($, active, change) {
|
|
|
712
713
|
|
|
713
714
|
const unavailableText = (view) => `Routing unavailable: ${unavailableReason(view)}. Claude’s model is kept.`;
|
|
714
715
|
|
|
715
|
-
function detailText(config, view) {
|
|
716
|
+
function detailText(config, view, usage) {
|
|
716
717
|
if (view.phase === 'unavailable')
|
|
717
718
|
return [
|
|
718
719
|
unavailableText(view),
|
|
@@ -732,7 +733,7 @@ function detailText(config, view) {
|
|
|
732
733
|
...activityDetailLines(config, view),
|
|
733
734
|
storeAgreementLine(view),
|
|
734
735
|
...[unpricedLine(view.activityMetrics)].filter(Boolean),
|
|
735
|
-
savingsLine(config, view, Date.now()),
|
|
736
|
+
savingsLine(config, view, usage, Date.now()),
|
|
736
737
|
view.error || missing ? classifierStatus(config, view.error ?? missing) : `${activeClassifier(config).label} ready`,
|
|
737
738
|
`Context: ${view.contextKnown ? `${view.contextTokens} tokens (estimate)` : 'unknown'}`,
|
|
738
739
|
`Observed cache: ${view.cacheRead ?? 'unknown'} read, ${view.cacheWrite ?? 'unknown'} written tokens`,
|
|
@@ -1157,7 +1158,7 @@ async function observeRouted($, router, { turnId, cfg, loop, loopVersion, reques
|
|
|
1157
1158
|
const tier = isSameModel(request.model, response.usage?.model) ? loop.decision.tier : null;
|
|
1158
1159
|
const route = `${request.model}@${request.effort ?? 'session'}`;
|
|
1159
1160
|
// Why the usage record leaves this reply out, when it does (UNPRICED_CAUSES).
|
|
1160
|
-
const observedUsd = compared?.reply?.routedUsd ?? observedReplyUsd(cfg, response.usage, compared?.ttl);
|
|
1161
|
+
const observedUsd = compared?.reply?.routedUsd ?? observedReplyUsd(cfg, response.usage, compared?.ttl, at);
|
|
1161
1162
|
const cause = !compared
|
|
1162
1163
|
? response.usage?.model
|
|
1163
1164
|
? 'error'
|
|
@@ -1637,7 +1638,10 @@ async function* stepAgent($, router, e, next) {
|
|
|
1637
1638
|
const ttl = await subagentTtlOf($);
|
|
1638
1639
|
const agent = router.agents.get(e.agentId);
|
|
1639
1640
|
if (agent)
|
|
1640
|
-
router.agents.set(e.agentId, {
|
|
1641
|
+
router.agents.set(e.agentId, {
|
|
1642
|
+
...addAgentReply(router.config, agent, response.usage, ttl, Date.now()),
|
|
1643
|
+
running: true,
|
|
1644
|
+
});
|
|
1641
1645
|
if (agent && !agent.running) await showRunning($, router);
|
|
1642
1646
|
} catch {}
|
|
1643
1647
|
}
|