@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
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "router",
|
|
3
3
|
"displayName": "Router",
|
|
4
|
-
"version": "1.
|
|
4
|
+
"version": "1.21.0",
|
|
5
5
|
"description": "Native model and effort routing within your provider. Anthropic, DeepSeek, z.ai, MiniMax, MiMo and Kimi defaults, custom provider profiles, classifier advice and one model per subagent.",
|
|
6
6
|
"author": {
|
|
7
7
|
"name": "Alexei Ledenev",
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,32 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.21.0 (2026-11-04)
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
|
|
7
|
+
- The band shows the tier meter (`▂` micro to `▂▄▆█` high) and the model instead of tier words, and activities as nouns: `code`, `debug`, `explore`, `plan`, `review`, `ops`, `docs`.
|
|
8
|
+
- One cost model for the band, the pane and `/router`. The session total includes subagents and says how it is paid: `≈ API value` on a Claude plan, `billed` on an API key or credits.
|
|
9
|
+
- Routing is compared with no routing: your `/model` choice for the main thread, Claude Code's own pick for subagents. Usage shows one table that adds up.
|
|
10
|
+
- The Now tab reads in order: next turn with a pin per tier, plan windows with reset times, the session cost, then context.
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- `lib/prices.mjs`: every built-in price with its vendor's page and check date. All were checked on 2026-11-04.
|
|
15
|
+
- `npm run prices:check` compares those prices with the Anthropic, DeepSeek, Kimi, MiniMax and z.ai pages. A weekly GitHub Actions job opens a pull request when a price changes, or an issue when a page cannot be read. MiMo needs a manual check.
|
|
16
|
+
|
|
17
|
+
### Removed
|
|
18
|
+
|
|
19
|
+
- Claude Code's `/cost` value and the `/cost differs` warning. Run `/cost` for the whole session cost, side calls included.
|
|
20
|
+
|
|
21
|
+
### Fixed
|
|
22
|
+
|
|
23
|
+
- Sonnet 5.5 cache reads cost $0.10 per million tokens, not $0.20. Sonnet sessions read cheaper, and moving down from Sonnet saves less per turn. No golden routing decision changes.
|
|
24
|
+
- DeepSeek Flash is priced at half outside its peak hours (01:00–04:00 and 06:00–10:00 UTC, weekdays). A Chinese public holiday is priced at peak. `router.json` models can set the same `offPeak` rule.
|
|
25
|
+
|
|
26
|
+
### Upgrade
|
|
27
|
+
|
|
28
|
+
Restart Claude Code after updating. No router-file or record changes are needed.
|
|
29
|
+
|
|
3
30
|
## 1.20.1 (2026-11-03)
|
|
4
31
|
|
|
5
32
|
### Changed
|
package/README.md
CHANGED
|
@@ -48,11 +48,11 @@ The active classifier is asked at the start of each logical turn, for the tier a
|
|
|
48
48
|
|
|
49
49
|
Jev is the default. [Configuration](docs/configuration.md#classifiers) gives the endpoints, timeouts, and how to add another service that speaks one of the supported protocols.
|
|
50
50
|
|
|
51
|
-

|
|
52
52
|
|
|
53
53
|
The band above the prompt shows the tier, activity, model, and reason for each turn. `/router` opens a pane to pin a tier, edit the model and effort of each tier, and tune the policy. See the [user guide](docs/user-guide.md#read-the-status-band).
|
|
54
54
|
|
|
55
|
-
The router needs Claude Code 2.1.289 or newer. Savings are not measured. The pane's Usage tab estimates what routing cost against your own model for the same tokens at configured list prices, for this session, today, 7 or 30 days, this month or all; it is not a bill and does not judge answer quality. See the [evaluation](docs/evaluation.md).
|
|
55
|
+
The router needs Claude Code 2.1.289 or newer. Savings are not measured. The pane's Usage tab estimates what routing cost against no routing (your own model on the main thread, Claude Code's pick for each subagent) for the same tokens at configured list prices, for this session, today, 7 or 30 days, this month or all; it is not a bill and does not judge answer quality. See the [evaluation](docs/evaluation.md).
|
|
56
56
|
|
|
57
57
|
## How it works
|
|
58
58
|
|
|
@@ -136,7 +136,7 @@ claude --plugin-dir "$PWD" --model claude-haiku-5-5
|
|
|
136
136
|
|
|
137
137
|
In Claude Code, run `/plugin configure router` and save your classifier key in the sensitive plugin option. The Mod adds its status band and `/router` pane. No status-line setup or gateway environment variables are needed.
|
|
138
138
|
|
|
139
|
-
Run `/router` to open the pane: route status, per-tier controls, tuning, and usage, including routing vs
|
|
139
|
+
Run `/router` to open the pane: route status, per-tier controls, tuning, and usage, including routing vs no routing. Run `/model` to select a model and turn routing off, and `/router auto` to turn it back on. For controls, metrics, tuning, and troubleshooting, see the [user guide](docs/user-guide.md).
|
|
140
140
|
|
|
141
141
|
Before a push, run the same checks as CI. `npm run setup` installs Biome and TypeScript into `tools/`; the plugin root keeps no lockfile, so Claude Code installs nothing with the plugin. `npm run validate` and `npm run test:plugin` need the `claude` CLI: they load the Mod in the Claude Code engine, which refuses some faults that lint and unit tests miss.
|
|
142
142
|
|
package/docs/activity-routing.md
CHANGED
|
@@ -262,4 +262,4 @@ Limits:
|
|
|
262
262
|
- Claude Opus 5.5 system card: Table 8.1.A; FrontierCode (§8.4); CursorBench 4.0 (§8.8); AA-Briefcase (§8.14.4).
|
|
263
263
|
- Anthropic prompting guides for Haiku 5.5 and Sonnet 5.5: effort starting points, Haiku at `xhigh` in multi-turn
|
|
264
264
|
chat.
|
|
265
|
-
- List prices: [`
|
|
265
|
+
- List prices: [`lib/prices.mjs`](../lib/prices.mjs).
|
package/docs/architecture.md
CHANGED
|
@@ -60,6 +60,8 @@ Claude Code builds each request for the model the Mod selects, so no request rew
|
|
|
60
60
|
| [Facts](../lib/facts.mjs) | The turn's facts for policy, and the bucket of a finished turn from its tool calls. |
|
|
61
61
|
| [Policy](../lib/policy.mjs) | Tier votes, escalation, and switching gates, for routes as well as tiers. |
|
|
62
62
|
| [Costs](../lib/cost.mjs) | Cache uncertainty bounds and switching estimates. |
|
|
63
|
+
| [Session cost](../lib/costs.mjs) | One cost per period for every readout: main and subagents, against no routing, and how it is paid. |
|
|
64
|
+
| [Prices](../lib/prices.mjs) | Built-in list prices with each vendor's page and check date; rewritten by `scripts/check-prices.mjs`. |
|
|
63
65
|
| [Router view](../lib/view.mjs) | The view's initial shape and the usage readings each reply adds to it. |
|
|
64
66
|
| [Config file](../lib/config-file.mjs) | Pane writes to `router.json`: the validated rewrite and what Undo restores. |
|
|
65
67
|
| [Panel](../lib/panel.mjs) | Tabbed pane: route status, tier pins, the route editor, tuning, and usage. |
|
|
@@ -131,9 +133,9 @@ Two stores hold counts:
|
|
|
131
133
|
|
|
132
134
|
Nothing is recorded with `activityRouting: off`. Stats run inside a guard: a failed transcript read or store access loses that turn's counts and never fails the turn. Readings already in the session's metrics record stay in memory after a failed write and go out with the next turn that adds a reading. A turn from a session that has since changed is dropped.
|
|
133
135
|
|
|
134
|
-
### Routing vs
|
|
136
|
+
### Routing vs no routing
|
|
135
137
|
|
|
136
|
-
After each main reply, where the response is observed, `savings.mjs` prices the reply on the model that served it and the same tokens on "your model": the session's model and the effort Claude Code sent on the turn's first request. `compareModels` prices each reply against every model in `router.json` as "your model", at the session effort. Each keeps a simulated single cache in the loop under its models key in `yoursBy` (`{ total, at, onYours, model, effort }`), which a history reset clears; after an effort change the next reply finds it cold. Each reply also becomes a `replyEntry` in `usage.mjs`: its time, its cell `mode|activity|tier|modelId@effort` with the model that served it, its prices against the model selected then, its input, cache-read and output tokens, and what the same tokens cost on each model as yours. Models are kept by id, not by models key, because a key can later name another model. Until the turn ends its entries are also the view's `usageLive`; every readout (the two-row band, the Now and Usage tabs, `/router`) adds them to the record with `withReplies`, so they count the same replies at the same moment. At turn completion the entries leave `turnUsage` in the same tick they enter the held record, and every view write of the records carries `usageLive` with them, so a pane opened mid-write, a failed store write or a Reset counts a turn once or not at all, never twice. At turn completion `recordUsage` adds the turn's entries to the session's own `$.store` key `usage:v1:<session id>`, by local calendar day: per day the cells' nine sums, the what-if sums, the replies per your model, the routed cost per hour, the turns, and the route switches by tier and by activity, with `since`, the record's first write. Days older than 400 days leave the record when it is written. Each key has one writer, and Claude Code 2.1.296 writes one key under a file lock (observed in its code; the `$.store` types do not promise it), so sessions that finish turns at the same moment do not overwrite each other. The view's `usageStore` adds up two parts: every other session's key, read at session start and when the pane opens, and this session's record (`usageSession`), which the router reads once, holds in memory, adds each finished turn to and then writes, so a pane opened during that write counts the turn once. On that read, `prunedUsage` names other sessions' records with no day in the last 400 days and, past 1,000 records, those whose last day is oldest; a record that does not read whole, such as one a later version wrote, is never named. Each named record is read again and deleted only if it has not changed, so a session that wrote its record since keeps it; with no conditional delete in `$.store`, a write between that read and the delete is still lost. A day that does not read is dropped, and the others stay. The Usage tab sums the days of the chosen period (`summarize`); the period is kept across sessions in `usage:period`. Before these records each session kept undated totals in `savings:v1:<session id>`; they are no longer written, and the view's `savingsStore`, their sum, is added to the All period. **Delete history** first writes the time in `savings:reset:v1`, then deletes every usage, savings, activity stats, metrics and subagent record. A record whose first reply is older than that time reads as empty, and each session reads the time before it adds a turn, so a session that still holds its record from before a Reset in another session drops it instead of writing it back. The comparison is by milliseconds: a record whose first reply has the reset's millisecond, or one written while the clock had moved back, still counts. A stored value of any other shape reads as empty. A reply with routing off or after an engine fallback is not counted, but it still moves your model's cache. A reply whose cache lifetime cannot be read loses its prices only, and your model's cache still follows it; a usage without rate limits prices writes at five minutes. No failure here fails the turn. [Evaluation](evaluation.md#routing-vs-
|
|
138
|
+
After each main reply, where the response is observed, `savings.mjs` prices the reply on the model that served it and the same tokens on "your model": the session's model and the effort Claude Code sent on the turn's first request. `compareModels` prices each reply against every model in `router.json` as "your model", at the session effort. Each keeps a simulated single cache in the loop under its models key in `yoursBy` (`{ total, at, onYours, model, effort }`), which a history reset clears; after an effort change the next reply finds it cold. Each reply also becomes a `replyEntry` in `usage.mjs`: its time, its cell `mode|activity|tier|modelId@effort` with the model that served it, its prices against the model selected then, its input, cache-read and output tokens, and what the same tokens cost on each model as yours. Models are kept by id, not by models key, because a key can later name another model. Until the turn ends its entries are also the view's `usageLive`; every readout (the two-row band, the Now and Usage tabs, `/router`) adds them to the record with `withReplies`, so they count the same replies at the same moment. At turn completion the entries leave `turnUsage` in the same tick they enter the held record, and every view write of the records carries `usageLive` with them, so a pane opened mid-write, a failed store write or a Reset counts a turn once or not at all, never twice. At turn completion `recordUsage` adds the turn's entries to the session's own `$.store` key `usage:v1:<session id>`, by local calendar day: per day the cells' nine sums, the what-if sums, the replies per your model, the routed cost per hour, the turns, and the route switches by tier and by activity, with `since`, the record's first write. Days older than 400 days leave the record when it is written. Each key has one writer, and Claude Code 2.1.296 writes one key under a file lock (observed in its code; the `$.store` types do not promise it), so sessions that finish turns at the same moment do not overwrite each other. The view's `usageStore` adds up two parts: every other session's key, read at session start and when the pane opens, and this session's record (`usageSession`), which the router reads once, holds in memory, adds each finished turn to and then writes, so a pane opened during that write counts the turn once. On that read, `prunedUsage` names other sessions' records with no day in the last 400 days and, past 1,000 records, those whose last day is oldest; a record that does not read whole, such as one a later version wrote, is never named. Each named record is read again and deleted only if it has not changed, so a session that wrote its record since keeps it; with no conditional delete in `$.store`, a write between that read and the delete is still lost. A day that does not read is dropped, and the others stay. The Usage tab sums the days of the chosen period (`summarize`); the period is kept across sessions in `usage:period`. Before these records each session kept undated totals in `savings:v1:<session id>`; they are no longer written, and the view's `savingsStore`, their sum, is added to the All period. **Delete history** first writes the time in `savings:reset:v1`, then deletes every usage, savings, activity stats, metrics and subagent record. A record whose first reply is older than that time reads as empty, and each session reads the time before it adds a turn, so a session that still holds its record from before a Reset in another session drops it instead of writing it back. The comparison is by milliseconds: a record whose first reply has the reset's millisecond, or one written while the clock had moved back, still counts. A stored value of any other shape reads as empty. A reply with routing off or after an engine fallback is not counted, but it still moves your model's cache. A reply whose cache lifetime cannot be read loses its prices only, and your model's cache still follows it; a usage without rate limits prices writes at five minutes. No failure here fails the turn. `costs.mjs` turns a period's usage summary and its subagent summary into the one cost every readout shows (`periodCost`): the main thread and the subagents, their total, what no routing would have cost (your model on the main thread, Claude Code's pick for each subagent), and how the session pays, from the configured models' `billing` and Claude Code's plan windows. The band, the Now and Usage tabs and `/router` read it, so they show the same numbers at the same moment. [Evaluation](evaluation.md#routing-vs-no-routing) gives the method and its limits.
|
|
137
139
|
|
|
138
140
|
Usage storage is version 3 under the same `usage:v1:<session id>` keys. Each day separates comparable `cells`
|
|
139
141
|
from observed-only `uncompared` cells. Both retain reply counts, served-model cost and tokens; only comparable cells
|
|
@@ -174,7 +176,7 @@ Cache identity uses the response model ID with the `[1m]` context hint removed,
|
|
|
174
176
|
|
|
175
177
|
The cached prefix is observed `cache_read + cache_creation`. Output tokens count only toward the next context size. Freshness uses the configured five-minute lifetime with its safety margin. Claude's usage counters do not prove one-hour cache lifetime.
|
|
176
178
|
|
|
177
|
-
Every estimate prices tokens through `ratesAt` in `cost.mjs`, which applies a model's `longContext` multiplier when the prompt (input, cache read and cache write) is over its threshold: Haiku 5.5 bills every rate at 5x above 100,000 tokens. Routing vs
|
|
179
|
+
Every estimate prices tokens through `ratesAt` in `cost.mjs`, which applies a model's `longContext` multiplier when the prompt (input, cache read and cache write) is over its threshold, and its `offPeak` multiplier outside its peak hours: Haiku 5.5 bills every rate at 5x above 100,000 tokens, and DeepSeek Flash at half outside its peak. A time the router does not know prices at peak. The built-in rates live in `prices.mjs`, which `scripts/check-prices.mjs` checks against each vendor's page. Routing vs no routing prices cache writes at the lifetime Claude Code gives the main conversation, since the usage it reports to a Mod has no 5m/1h split: `FORCE_PROMPT_CACHING_5M`, then `CLAUDE_CODE_PROMPT_CACHE_TTL`, then the `promptCacheTtl` setting, then `ENABLE_PROMPT_CACHING_1H`, then one hour when replies report plan rate limits, else five minutes.
|
|
178
180
|
|
|
179
181
|
The switching policy prices the candidate at a conservative cache-write bound and the incumbent at its best supported input bound. The pane shows the configured-price range and a conditional payback estimate. These are estimates, not measured savings. Claude's native `/cost` ledger owns total API cost. Classifier spend is not included.
|
|
180
182
|
|
package/docs/configuration.md
CHANGED
|
@@ -40,8 +40,7 @@ A non-Anthropic file must exist and validate. It never falls back to `router.jso
|
|
|
40
40
|
### Provider prices
|
|
41
41
|
|
|
42
42
|
All non-Anthropic built-in model windows are at least 1M tokens.
|
|
43
|
-
|
|
44
|
-
DeepSeek and z.ai rates were checked on 2026-10-28; the new provider rates on 2026-10-31.
|
|
43
|
+
Every built-in price, Claude and provider, comes from [`lib/prices.mjs`](../lib/prices.mjs), which names each vendor's official price page and the date the prices were last checked: 2026-11-04 for all of them. See [Keep prices current](#keep-prices-current).
|
|
45
44
|
|
|
46
45
|
| Model | Input / output / cached input, USD per million tokens |
|
|
47
46
|
| --- | --- |
|
|
@@ -53,12 +52,14 @@ DeepSeek and z.ai rates were checked on 2026-10-28; the new provider rates on 20
|
|
|
53
52
|
| MiMo-V2.6-Pro | 0.435 / 0.87 / 0.0036 |
|
|
54
53
|
| Kimi-K3.1-Pro | 2.00 / 10.00 / 0.20 |
|
|
55
54
|
|
|
56
|
-
These are
|
|
57
|
-
|
|
58
|
-
|
|
55
|
+
These are estimate inputs, not an invoice; z.ai plan quota uses its own multipliers. DeepSeek Flash lists its peak rates: 01:00–04:00 and 06:00–10:00 UTC, Monday to Friday. At every other hour it bills half, and the router prices each reply and each routing estimate at the rate of its time. DeepSeek also bills Chinese public holidays at off-peak rates, which the router does not know, so a holiday is priced at peak, the higher bound.
|
|
56
|
+
|
|
57
|
+
### Keep prices current
|
|
58
|
+
|
|
59
|
+
A weekly GitHub Actions job (`.github/workflows/prices.yml`) runs `npm run prices:check`. It reads the Anthropic, DeepSeek, Kimi, MiniMax and z.ai price pages, compares them with `lib/prices.mjs`, and opens a pull request when a price, a long-context tier or DeepSeek's peak hours change. A page it cannot read opens a "Price check failed" issue. The MiMo page needs a browser, so the job lists it for a person to check. The pull request needs the repository setting **Allow GitHub Actions to create and approve pull requests**, and CI starts on it once a maintainer closes and reopens it. Run the check yourself with `npm run prices:check`; add `-- --write` to rewrite `lib/prices.mjs`. Prices in `router.json` always override the built-in ones.
|
|
59
60
|
All non-Anthropic built-in presets use `billing: "credits"`.
|
|
60
61
|
For an included-plan model, set `billing: "plan"` to disable the cold-input cash cap.
|
|
61
|
-
`billing` does not change a
|
|
62
|
+
`billing` does not change a price: the pane prices plan and credits models alike, at list prices, and labels the plan part `≈ API value` and the credits part billed; see [how dollars are paid](user-guide.md#how-dollars-are-paid).
|
|
62
63
|
A provider name or URL does not establish its billing product.
|
|
63
64
|
|
|
64
65
|
### Provider cache behavior
|
|
@@ -131,7 +132,7 @@ Default model settings:
|
|
|
131
132
|
| Alias | Input / output / cache read, USD per million tokens | Context window | Billing | Effort levels |
|
|
132
133
|
| -------- | --------------------------------------------------- | -------------- | ------- | --------------------------------------- |
|
|
133
134
|
| `opus` | 4 / 20 / 0.2 | 1,000,000 | `plan` | `low`, `medium`, `high`, `xhigh`, `max` |
|
|
134
|
-
| `sonnet` | 2 / 10 / 0.
|
|
135
|
+
| `sonnet` | 2 / 10 / 0.1 | 1,000,000 | `plan` | `low`, `medium`, `high`, `xhigh`, `max` |
|
|
135
136
|
| `haiku` | 0.1 / 0.5 / 0.01 | 1,000,000 | `plan` | `low`, `medium`, `high`, `xhigh`, `max` |
|
|
136
137
|
|
|
137
138
|
Prices are configured list-price inputs for estimates. They are not a subscription bill or a claim of savings. Haiku 5.5 lists these prices for prompts up to 100,000 tokens and five times each of them, cache reads and writes included, above that. Its default `longContext` is `{ "above": 100000, "multiplier": 5 }`: a request whose prompt, counting input, cache reads and cache writes, is over `above` tokens is priced at `multiplier` times every rate. Every estimate prices through it. Set `"longContext": null` to remove it, for example when you point the `haiku` alias at another model with `id`. A model with `"efforts": []` receives no effort field. A route in `router.json` without an `effort` takes the effort of that tier's default route. To keep the session effort, clamped to what the model supports, set `"effort": null`, for example `"routes": { "high": { "model": "opus", "effort": null } }`. A 1.3 file whose `low` route had no `effort` kept the session effort; in 1.4 it runs at `high` until you add `"effort": null`.
|
|
@@ -328,7 +329,7 @@ The Mod validates the whole file. Unknown keys and invalid values make routing u
|
|
|
328
329
|
| `mode` | `cost`, `balanced`, `quality` ([Routing modes](routing-modes.md)) | `balanced` |
|
|
329
330
|
| `modes.<cost\|quality>.policy` | any `policy` field, used while that mode is active | [Routing modes](routing-modes.md#policy-per-mode); not tuned |
|
|
330
331
|
| `activities.<activity>.<tier>` | optional `model` and `effort`, as in `routes` | The overrides in [Activity routing](#activity-routing) |
|
|
331
|
-
| `models.<alias>` | `id`, `input`, optional `output`, `cacheRead`, optional `longContext` (`above`, `multiplier`, or `null`), `contextWindow`, `billing`, `efforts`, optional `strength`, `imageInput` | Three defaults above |
|
|
332
|
+
| `models.<alias>` | `id`, `input`, optional `output`, `cacheRead`, optional `longContext` (`above`, `multiplier`, or `null`), optional `offPeak` (`multiplier`, `peakDays` as UTC weekdays 0–6 from Sunday, `peakHoursUtc` as `[from, to)` hour ranges, or `null`), `contextWindow`, `billing`, `efforts`, optional `strength`, `imageInput` | Three defaults above |
|
|
332
333
|
| `cache` | `mode`, `effortScope`, `writeMultiplier`, `ttlMs`, `warmMarginMs` | `5m: 1.25`, `1h: 2`; `300000` / `3600000` ms; `30000` ms |
|
|
333
334
|
| `policy` | Fields below | Values below |
|
|
334
335
|
| `classifier` | An id in `classifiers` | `jev` |
|
package/docs/evaluation.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Evaluation
|
|
2
2
|
|
|
3
|
-
The native Mod has no measured savings result. The pane reports Claude's own usage and configured-price scenarios. Its one counterfactual is [routing vs
|
|
3
|
+
The native Mod has no measured savings result. The pane reports Claude's own usage and configured-price scenarios. Its one counterfactual is [routing vs no routing](#routing-vs-no-routing), an estimate at configured list prices, not a bill or a measured saving.
|
|
4
4
|
|
|
5
5
|
This page separates an older gateway experiment from a shadow replay of native policy. Neither result measures answer quality or proves lower real spend. [Activity routing](#activity-routing) adds two checks of the activity label, with no savings result either.
|
|
6
6
|
|
|
@@ -150,9 +150,9 @@ Five probe results are checked in, run on 2026-10-09 and 2026-10-10 (UTC) with t
|
|
|
150
150
|
|
|
151
151
|
Ollama's latency covers both requests and stays inside its 5000 ms deadline; on slower hardware the activity step is skipped when less than 300 ms remain. They measure the label on synthetic prompts, not routing quality or savings. The activity question costs little time: 30 alternating pairs of the same prompts, with and without it, gave Jev p50 259 ms both ways and p95 300 ms without, 306 ms with; OpenAI p50 163 ms and 162 ms, p95 296 ms and 349 ms. OpenAI's first request of a run took about 2.3 s of its 3000 ms deadline. The Classifier tab shows each result under its classifier, such as `activity probe 70/70 · p95 299 ms · Oct 10` (UTC date), when the classifier runs the probed model. The script regenerates `lib/probe-results.mjs` from the result files after each run; `npm run probe:results` does it alone, and a test fails when the two disagree. A run without a single activity answer (an activity or `uncertain`) or without a p95 latency, such as one with a revoked key or a model whose answers all lack the activity, exits with an error and writes neither file. `policy.activityMass` was not tuned on any classifier; run the probe before you trust it with a new one. Clef Omni has no probe result yet, so its Classifier tab row shows none.
|
|
152
152
|
|
|
153
|
-
## Routing vs
|
|
153
|
+
## Routing vs no routing
|
|
154
154
|
|
|
155
|
-
The
|
|
155
|
+
The pane compares what routed replies and subagents cost with what the same tokens would cost without the router: on your model, the model `/model` selected at the session effort when each reply ran, and for each subagent on the model Claude Code would have picked. It answers "at list prices, did routing spend more or less than no routing for this work". It does not answer whether the answers were as good. The main thread's method follows; a subagent is priced on its own tokens on both models, as [Subagent routing](#subagent-routing) describes.
|
|
156
156
|
|
|
157
157
|
Method, per main reply that routing chose:
|
|
158
158
|
|
|
@@ -173,7 +173,7 @@ Limits:
|
|
|
173
173
|
- Answer quality is not measured. A saving bought with worse answers would read the same.
|
|
174
174
|
- Your model's cache is simulated, and a five-minute session that the lifetime rule takes for one hour (a plan subscriber billed as overage) would read too much cache on your side.
|
|
175
175
|
- A route that changes only the effort costs the same per token. On Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 it shares your cache and reads $0.00; on a provider that caches each effort apart, it shows its cache writes.
|
|
176
|
-
-
|
|
176
|
+
- Classifier charges, replies with routing off, and the side calls the router does not see (titles, compaction, server-side tools) are not counted; Claude Code's `/cost` counts them. On a Claude plan the dollars stand for quota, not cash, and the pane marks them `≈`.
|
|
177
177
|
- The usage records keep one record per session, by local calendar day, so sessions finishing turns at the same moment both count. A turn's switch counts on the day it ended, its replies on the days they arrived. Claude Code's store has no atomic update, which leaves these gaps: the same session open in two Claude Code processes at once can lose one's turn; a turn finishing in another process during **Delete history** can be lost; and a session's total from before a reset comes back if its first saved reply has the same millisecond as the reset, or if the system clock moved back across the reset. The router reads every session's record at session start and when the pane opens, so that read grows with the number of sessions kept. A session drops its days older than 400 days when it writes its record; on that read, another session's record with no day in the last 400 days is deleted, and past 1,000 records of other sessions those with the oldest last day go too. A record that does not read whole, such as one a later version wrote, counts toward the 1,000 but is never deleted. Totals kept before the dated usage records have no dates: All adds them, and the other periods leave them out.
|
|
178
178
|
|
|
179
179
|
## Subagent routing
|
package/docs/native-router.md
CHANGED
|
@@ -31,19 +31,19 @@ Mode belongs to a Claude Code session. Clear starts a new session with routing o
|
|
|
31
31
|
|
|
32
32
|
## Router pane
|
|
33
33
|
|
|
34
|
-
The status band is one line above the prompt: a tier meter, the
|
|
34
|
+
The status band is one line above the prompt: a tier meter, the model, the activity, a short reason, classifier support and the switch cost, and context and cache use. Segments drop by priority when the band is narrow: classifier support and the switch cost first, then context and cache, then the activity, then the reason. Hovering reveals a pin per tier, **Turn off**, and a two-row view whose second row shows the plan windows on a Claude plan and the session's cost against no routing; while routing is off, **Turn on** sits on the band itself, so the band carries one routing control at a time. A fresh session that starts with routing off because of its model shows `not a routing tier` on the band until the mode changes. The band yields to surveys. In a subagent's transcript it names the agent's model and who picked it, such as `agent ■ Haiku 5.5 ↓ from Opus 5.5 (Claude Code’s pick)`; without a record of the agent it reads `agent · model chosen at spawn`, or `agent · keeps its own model (subagent routing off)`. A model change between turns raises a toast. A pin, or a step that changes only the effort, such as `medium` to `high` on the defaults, raises none. While the classifier runs, the turn's spinner says `Choosing model`. In Manual mode or when routing is unavailable, the prompt footer carries `routing off` or `routing unavailable`. The **Router** button opens the pane. The pane has five numbered tabs, Now, Routes, Policy, Classifier, and Usage, under one `ROUTER` line with the routing on/off pair and the classifier state. The [user guide](user-guide.md#open-the-router-pane) describes each tab.
|
|
35
35
|
|
|
36
36
|
| Reading | Meaning and limits |
|
|
37
37
|
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
38
|
-
| Next turn
|
|
39
|
-
| Classifier support | Per-tier probabilities from the last classification;
|
|
40
|
-
| Activity | The classifier's activity choice
|
|
41
|
-
|
|
|
42
|
-
|
|
|
43
|
-
|
|
|
38
|
+
| Next turn | The tier meter, the requested model and effort, and, under an activity override, the tier's own route. `! served by … · native fallback` appears only when the engine answered with another model. Actual effort is not reported. |
|
|
39
|
+
| Classifier support | Per-tier probabilities from the last classification, on each pin; beside **why**, the support for the switch against the bar the policy required, and the switch cost. Pins and skipped calls leave it empty. |
|
|
40
|
+
| Activity | The classifier's activity choice with its share and the next-best answer, on the Next turn line; `uncertain` shown dim. Empty with routing off, a pin, or no answer. |
|
|
41
|
+
| Plan (Now) | Claude Code's 5-hour and 7-day plan windows with their reset times, on a Claude plan only. A reset time that has passed is not shown. |
|
|
42
|
+
| Session (Now) | This session's total, main thread and subagents, labelled by how it is paid (`≈ API value` on a plan, `billed` otherwise), its difference against no routing and what no routing would cost, the main thread and the subagents as bars, and every main-conversation reply as a strip colored by tier, pairs of cells merging past 48 cells or on a narrow pane. The two-row band and `/router` show the same numbers. |
|
|
43
|
+
| Routing vs no routing (Usage) | For a period (this session, today, 7 or 30 days, this month, or all), one table that adds up: the main thread against the same tokens on your model, the model `/model` selected at the session effort when each reply ran, with its cheaper-model saving, stronger-model cost and cache rebuilds; the subagents against Claude Code's picks; the total against no routing. The running turn's replies are included. `early sample` below 10 replies. Output length is held the same; answer quality is not measured. |
|
|
44
|
+
| Breakdown (Usage) | The period's replies, cost and difference against no routing by activity, model or tier, each row opening to its routes or activities; the cost per hour, day or week, or **What if**, the same tokens on each model alone; from 20 replies, the cells worth a look, linked to Routes or Policy. |
|
|
44
45
|
| Across sessions (Classifier) | The counts kept since the last reset: labelled turns, tool agreement on the classifier's raw answer, overall and for `code`, `ops` and `explore`, the two largest mismatches, activity moves inside a tier taken and refused, and escalations after a cheaper activity move. The active classifier's p95 latency shows on its **Deadline** line. `/router` text shows the agreement. |
|
|
45
|
-
|
|
|
46
|
-
| Context bar | Maximum available observed and local estimated context, compared with the routed model's window. The fit rule reserves 20%. |
|
|
46
|
+
| Context gauge | Maximum available observed and local estimated context, compared with the window of the model that runs next. The fit rule keeps a route only while the context fills at most 80% of its window. |
|
|
47
47
|
| Observed / estimated input | Under **details** on Now: Claude's local context reading and the router's best current context estimate. `unknown` blocks a move to a smaller window. |
|
|
48
48
|
| Cache reuse | Last response's cache-read tokens divided by its reported input counters. |
|
|
49
49
|
| Cache read / written; Output | Response usage counters. Cache warmth does not prove a particular TTL. |
|
|
@@ -53,7 +53,7 @@ The status band is one line above the prompt: a tier meter, the activity, the ro
|
|
|
53
53
|
| Conservative payback | Conditional later-turn estimate based on configured cache prices, future reads, and the last output size. It is not measured savings. |
|
|
54
54
|
| Cache hits saved | Estimated price difference for observed cache reads before cache writes. It is not net savings. |
|
|
55
55
|
|
|
56
|
-
The router keeps no bill. Routing vs
|
|
56
|
+
The router keeps no bill. Routing vs no routing is a configured-price estimate, not a measured saving, and leaves out classifier charges and the side calls the router does not see; Claude Code's `/cost` counts those. See [Evaluation](evaluation.md) for what the available trace can support.
|
|
57
57
|
|
|
58
58
|
## Routing and classifier settings
|
|
59
59
|
|
|
@@ -84,7 +84,7 @@ The pane refuses to write through a symlink. A failed validation names the setti
|
|
|
84
84
|
- Three launched classifier failures open a 60-second pause for that classifier. One in-flight request is allowed per classifier in each active Mod instance. Pending host HTTP work blocks another request until it settles.
|
|
85
85
|
- A `router.json` with v0.8 gateway keys or the 1.1 `jev` section marks the router unavailable until the [migration command](configuration.md#convert-an-older-routerjson) converts it.
|
|
86
86
|
- Unsupported Claude Code versions and leftover v0.8 gateway settings (the `jev-router` model or the `127.0.0.1:43170` base URL) mark the router unavailable. `/router` lists the settings to remove. A local gateway does not run as part of this Mod.
|
|
87
|
-
- While the router is unavailable, the pane header reads `
|
|
87
|
+
- While the router is unavailable, the pane header reads `ROUTER unavailable Claude’s model is kept` with the reason, and offers no on/off pair or pins. `/router` without a surface starts with `Routing unavailable: <reason>. Claude’s model is kept.`, and `/router auto`, `off`, `pin`, and `activities` reply the same and change nothing.
|
|
88
88
|
- A context-window error makes that model ineligible until the next history reset. The Mod does not retry an Anthropic request after a stream begins.
|
|
89
89
|
- Unknown context retains the current model. There is no characters-to-tokens fallback.
|
|
90
90
|
- Unknown model substitutions receive no cache credit for the requested model.
|
package/docs/providers.md
CHANGED
|
@@ -279,7 +279,7 @@ Claude Code sends every request to one local `claude-proxy` endpoint. The proxy
|
|
|
279
279
|
```
|
|
280
280
|
|
|
281
281
|
These are experimental starting routes, not measured quality rankings. Both lower tiers use DeepSeek at low effort; medium uses high effort; high uses Opus at xhigh.
|
|
282
|
-
The price fields are API list-price estimates, not subscription charges. DeepSeek values
|
|
282
|
+
The price fields are API list-price estimates, not subscription charges. DeepSeek values are its peak prices; add DeepSeek's `offPeak` rule from [`lib/prices.mjs`](../lib/prices.mjs) to price its off-peak hours at half.
|
|
283
283
|
Cache-cost assumptions, activity routing and subagent routing are off initially; upstream caching remains active.
|
|
284
284
|
The default classifier is Jev and needs its existing plugin credential. Select another configured classifier explicitly if needed; no local classifier server is required.
|
|
285
285
|
|
|
@@ -318,8 +318,8 @@ Launch on the model you would otherwise use:
|
|
|
318
318
|
A launch model must be a model that some route runs. On any other model, a fresh session starts with routing off.
|
|
319
319
|
To start on another Claude model, such as Sonnet, add it to `models`, put it on a route, and map it in the proxy configuration.
|
|
320
320
|
|
|
321
|
-
Opus is billed by the plan and DeepSeek in credits, but
|
|
322
|
-
See [
|
|
321
|
+
Opus is billed by the plan and DeepSeek in credits, but the pane prices both at list prices, so one sum compares them: `session ≈$24.10 API value billed $4.10 −$45.90 (−66%) vs no routing`, where `billed $4.10` is the DeepSeek part.
|
|
322
|
+
See [how dollars are paid](user-guide.md#how-dollars-are-paid).
|
|
323
323
|
|
|
324
324
|
Open `/router` and check the selected file, classifier health and routing state before use.
|
|
325
325
|
The catalog must contain the bare native IDs; `[1m]` is client metadata, not a proxy alias.
|