@alexeiled/claude-router 1.6.0 → 1.7.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 +47 -0
- package/README.md +14 -4
- package/docs/activity-routing.md +254 -0
- package/docs/architecture.md +9 -3
- package/docs/configuration.md +56 -44
- package/docs/evaluation.md +37 -6
- package/docs/native-router.md +17 -13
- package/docs/router-band.svg +78 -80
- package/docs/router-pane-classifier.svg +7 -7
- package/docs/router-pane-now.svg +9 -9
- package/docs/router-pane-routing.svg +73 -87
- package/docs/router-pane-usage.svg +123 -0
- package/docs/user-guide.md +79 -53
- package/hooks/native-router.mjs +236 -39
- package/lib/activity-stats.mjs +87 -21
- package/lib/band.mjs +82 -55
- package/lib/config.mjs +49 -32
- package/lib/cost.mjs +32 -5
- package/lib/display.mjs +79 -4
- package/lib/panel.mjs +389 -67
- package/lib/route.mjs +27 -12
- package/lib/savings.mjs +237 -0
- package/lib/view.mjs +10 -1
- package/package.json +1 -1
- package/types/index.d.ts +51 -3
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 758 971" role="img" aria-labelledby="title desc">
|
|
2
|
+
<title id="title">Router pane, Usage tab</title>
|
|
3
|
+
<desc id="desc">Routing vs your model first: routed replies against the same tokens on your model, Opus 5.5 at xhigh this session and each session’s own model since the last reset, the difference split into cheaper models, stronger models and switch cache writes, the two costs as bars and the replies by tier; then Claude’s own readings, activity counts and estimates.</desc>
|
|
4
|
+
<style>
|
|
5
|
+
text { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace; font-size: 13px; }
|
|
6
|
+
.cap { font-family: system-ui, -apple-system, 'Segoe UI', sans-serif; font-size: 12px; fill: #9a988f; }
|
|
7
|
+
</style>
|
|
8
|
+
<rect width="758" height="971" rx="8" fill="#1c1c1c"/>
|
|
9
|
+
<rect x="10" y="10" width="738" height="951" rx="6" fill="none" stroke="#3f5f8f"/>
|
|
10
|
+
<text x="24.0" y="34" fill="#5fafd7" font-weight="700" xml:space="preserve">ROUTING</text>
|
|
11
|
+
<rect x="94.2" y="20" width="62.4" height="18" rx="4" fill="#87afff"/>
|
|
12
|
+
<text x="94.2" y="34" fill="#0d1016" font-weight="700" xml:space="preserve">[ ◉ on ]</text>
|
|
13
|
+
<rect x="164.4" y="20" width="70.2" height="18" rx="4" fill="#2e3340"/>
|
|
14
|
+
<text x="164.4" y="34" fill="#d0d0d0" xml:space="preserve">[ ○ off ]</text>
|
|
15
|
+
<text x="234.6" y="34" fill="#7c7c7c" xml:space="preserve"> off keeps the /model choice</text>
|
|
16
|
+
<text x="24.0" y="53" fill="#87d787" xml:space="preserve">Jev ready · 347 ms</text>
|
|
17
|
+
<rect x="24.0" y="58" width="54.6" height="18" rx="4" fill="#2e3340"/>
|
|
18
|
+
<text x="24.0" y="72" fill="#d0d0d0" xml:space="preserve">[ Now ]</text>
|
|
19
|
+
<rect x="86.4" y="58" width="85.8" height="18" rx="4" fill="#2e3340"/>
|
|
20
|
+
<text x="86.4" y="72" fill="#d0d0d0" xml:space="preserve">[ Routing ]</text>
|
|
21
|
+
<rect x="180.0" y="58" width="109.2" height="18" rx="4" fill="#2e3340"/>
|
|
22
|
+
<text x="180.0" y="72" fill="#d0d0d0" xml:space="preserve">[ Classifier ]</text>
|
|
23
|
+
<rect x="297.0" y="58" width="70.2" height="18" rx="4" fill="#87afff"/>
|
|
24
|
+
<text x="297.0" y="72" fill="#0d1016" font-weight="700" xml:space="preserve">[ Usage ]</text>
|
|
25
|
+
<rect x="375.0" y="58" width="39.0" height="18" rx="4" fill="#2e3340"/>
|
|
26
|
+
<text x="375.0" y="72" fill="#d0d0d0" xml:space="preserve">[ ? ]</text>
|
|
27
|
+
<text x="24.0" y="110" fill="#5fafd7" font-weight="700" xml:space="preserve">ROUTING VS YOUR MODEL</text>
|
|
28
|
+
<text x="187.8" y="110" fill="#7c7c7c" xml:space="preserve"> · </text>
|
|
29
|
+
<text x="211.2" y="110" fill="#e0708a" font-weight="700" xml:space="preserve">Opus 5.5 · xhigh</text>
|
|
30
|
+
<text x="359.4" y="110" fill="#7c7c7c" xml:space="preserve">this session</text>
|
|
31
|
+
<text x="476.4" y="110" fill="#7c7c7c" xml:space="preserve">since Oct 3</text>
|
|
32
|
+
<text x="24.0" y="129" fill="#d0d0d0" xml:space="preserve"> Routed replies</text>
|
|
33
|
+
<text x="359.4" y="129" fill="#d0d0d0" xml:space="preserve">$6.40</text>
|
|
34
|
+
<text x="476.4" y="129" fill="#d0d0d0" xml:space="preserve">$41.18</text>
|
|
35
|
+
<text x="24.0" y="148" fill="#d0d0d0" xml:space="preserve"> Same tokens on your model</text>
|
|
36
|
+
<text x="359.4" y="148" fill="#d0d0d0" xml:space="preserve">$8.24</text>
|
|
37
|
+
<text x="476.4" y="148" fill="#d0d0d0" xml:space="preserve">$52.60</text>
|
|
38
|
+
<text x="24.0" y="167" fill="#d0d0d0" font-weight="700" xml:space="preserve"> Difference</text>
|
|
39
|
+
<text x="359.4" y="167" fill="#6fcf97" font-weight="700" xml:space="preserve">−$1.84 −22%</text>
|
|
40
|
+
<text x="476.4" y="167" fill="#6fcf97" font-weight="700" xml:space="preserve">−$11.42 −22%</text>
|
|
41
|
+
<text x="24.0" y="186" fill="#7c7c7c" xml:space="preserve"> cheaper models</text>
|
|
42
|
+
<text x="359.4" y="186" fill="#6fcf97" xml:space="preserve">−$2.31</text>
|
|
43
|
+
<text x="476.4" y="186" fill="#6fcf97" xml:space="preserve">−$14.90</text>
|
|
44
|
+
<text x="24.0" y="205" fill="#7c7c7c" xml:space="preserve"> stronger than yours</text>
|
|
45
|
+
<text x="359.4" y="205" fill="#d0d0d0" xml:space="preserve">$0.00</text>
|
|
46
|
+
<text x="476.4" y="205" fill="#d0d0d0" xml:space="preserve">$0.00</text>
|
|
47
|
+
<text x="24.0" y="224" fill="#7c7c7c" xml:space="preserve"> cache writes from switches</text>
|
|
48
|
+
<text x="359.4" y="224" fill="#f0b429" xml:space="preserve">+$0.47</text>
|
|
49
|
+
<text x="476.4" y="224" fill="#f0b429" xml:space="preserve">+$3.48</text>
|
|
50
|
+
<text x="24.0" y="262" fill="#7c7c7c" xml:space="preserve"> routed </text>
|
|
51
|
+
<text x="133.2" y="262" fill="#5fd7af" xml:space="preserve">█</text>
|
|
52
|
+
<text x="141.0" y="262" fill="#5f9fe0" xml:space="preserve">██████</text>
|
|
53
|
+
<text x="187.8" y="262" fill="#d7af5f" xml:space="preserve">██████</text>
|
|
54
|
+
<text x="234.6" y="262" fill="#e0708a" xml:space="preserve">████</text>
|
|
55
|
+
<text x="265.8" y="262" fill="#7c7c7c" xml:space="preserve">░░░░░</text>
|
|
56
|
+
<text x="304.8" y="262" fill="#d0d0d0" xml:space="preserve"> $6.40</text>
|
|
57
|
+
<text x="24.0" y="281" fill="#7c7c7c" xml:space="preserve"> your model </text>
|
|
58
|
+
<text x="133.2" y="281" fill="#e0708a" xml:space="preserve">██████████████████████</text>
|
|
59
|
+
<text x="304.8" y="281" fill="#d0d0d0" xml:space="preserve"> $8.24</text>
|
|
60
|
+
<text x="39.6" y="300" fill="#5fd7af" font-weight="700" xml:space="preserve">■ </text>
|
|
61
|
+
<text x="55.2" y="300" fill="#7c7c7c" xml:space="preserve">micro 19% </text>
|
|
62
|
+
<text x="141.0" y="300" fill="#5f9fe0" font-weight="700" xml:space="preserve">■ </text>
|
|
63
|
+
<text x="156.6" y="300" fill="#7c7c7c" xml:space="preserve">low 41% </text>
|
|
64
|
+
<text x="226.8" y="300" fill="#d7af5f" font-weight="700" xml:space="preserve">■ </text>
|
|
65
|
+
<text x="242.4" y="300" fill="#7c7c7c" xml:space="preserve">medium 27% </text>
|
|
66
|
+
<text x="336.0" y="300" fill="#e0708a" font-weight="700" xml:space="preserve">■ </text>
|
|
67
|
+
<text x="351.6" y="300" fill="#7c7c7c" xml:space="preserve">high 14% of replies</text>
|
|
68
|
+
<text x="24.0" y="338" fill="#7c7c7c" xml:space="preserve"> since Oct 3: each session compared with its own model</text>
|
|
69
|
+
<text x="24.0" y="357" fill="#7c7c7c" xml:space="preserve"> API list prices · same tokens and output length · not a bill;</text>
|
|
70
|
+
<text x="24.0" y="376" fill="#7c7c7c" xml:space="preserve"> on a Claude plan it stands for quota · answer quality not measured</text>
|
|
71
|
+
<text x="24.0" y="414" fill="#5fafd7" font-weight="700" xml:space="preserve">USAGE · Claude readings</text>
|
|
72
|
+
<text x="24.0" y="433" fill="#d0d0d0" xml:space="preserve">Cost $18.003 </text>
|
|
73
|
+
<text x="172.2" y="433" fill="#7c7c7c" xml:space="preserve">reported by Claude</text>
|
|
74
|
+
<text x="24.0" y="452" fill="#87d787" xml:space="preserve">Context ██████░░░░░░░░░░ 40% ~402.9K / 1.00M</text>
|
|
75
|
+
<text x="24.0" y="471" fill="#7c7c7c" xml:space="preserve"> observed 402.4K · estimated 401.8K</text>
|
|
76
|
+
<text x="24.0" y="490" fill="#87d787" xml:space="preserve">Cache ████████████████ 100% last reply</text>
|
|
77
|
+
<text x="24.0" y="509" fill="#7c7c7c" xml:space="preserve"> read 400.6K · written 1.8K tokens</text>
|
|
78
|
+
<text x="24.0" y="528" fill="#d0d0d0" xml:space="preserve">Output 499 tokens on the last reply</text>
|
|
79
|
+
<text x="24.0" y="566" fill="#5fafd7" font-weight="700" xml:space="preserve">INPUT PER REPLY · lowest to highest</text>
|
|
80
|
+
<text x="39.6" y="585" fill="#5f9fe0" font-weight="700" xml:space="preserve">▁</text>
|
|
81
|
+
<text x="47.4" y="585" fill="#5f9fe0" font-weight="700" xml:space="preserve">▂</text>
|
|
82
|
+
<text x="55.2" y="585" fill="#5f9fe0" font-weight="700" xml:space="preserve">▂</text>
|
|
83
|
+
<text x="63.0" y="585" fill="#5f9fe0" font-weight="700" xml:space="preserve">▂</text>
|
|
84
|
+
<text x="70.8" y="585" fill="#5f9fe0" font-weight="700" xml:space="preserve">▃</text>
|
|
85
|
+
<text x="78.6" y="585" fill="#5f9fe0" font-weight="700" xml:space="preserve">▃</text>
|
|
86
|
+
<text x="86.4" y="585" fill="#d7af5f" font-weight="700" xml:space="preserve">▃</text>
|
|
87
|
+
<text x="94.2" y="585" fill="#d7af5f" font-weight="700" xml:space="preserve">▄</text>
|
|
88
|
+
<text x="102.0" y="585" fill="#5f9fe0" font-weight="700" xml:space="preserve">▄</text>
|
|
89
|
+
<text x="109.8" y="585" fill="#5f9fe0" font-weight="700" xml:space="preserve">▅</text>
|
|
90
|
+
<text x="117.6" y="585" fill="#5f9fe0" font-weight="700" xml:space="preserve">▅</text>
|
|
91
|
+
<text x="125.4" y="585" fill="#5f9fe0" font-weight="700" xml:space="preserve">▆</text>
|
|
92
|
+
<text x="133.2" y="585" fill="#e0708a" font-weight="700" xml:space="preserve">▆</text>
|
|
93
|
+
<text x="141.0" y="585" fill="#e0708a" font-weight="700" xml:space="preserve">▆</text>
|
|
94
|
+
<text x="148.8" y="585" fill="#e0708a" font-weight="700" xml:space="preserve">▇</text>
|
|
95
|
+
<text x="156.6" y="585" fill="#e0708a" font-weight="700" xml:space="preserve">▇</text>
|
|
96
|
+
<text x="164.4" y="585" fill="#e0708a" font-weight="700" xml:space="preserve">▇</text>
|
|
97
|
+
<text x="172.2" y="585" fill="#e0708a" font-weight="700" xml:space="preserve">▇</text>
|
|
98
|
+
<text x="180.0" y="585" fill="#e0708a" font-weight="700" xml:space="preserve">█</text>
|
|
99
|
+
<text x="187.8" y="585" fill="#e0708a" font-weight="700" xml:space="preserve">█</text>
|
|
100
|
+
<text x="195.6" y="585" fill="#7c7c7c" xml:space="preserve"> 361.0K … 402.4K</text>
|
|
101
|
+
<text x="24.0" y="604" fill="#87d787" xml:space="preserve">five hour ████████░░░░░░░░ 48% used</text>
|
|
102
|
+
<text x="24.0" y="623" fill="#87d787" xml:space="preserve">seven day ███████░░░░░░░░░ 43% used</text>
|
|
103
|
+
<text x="24.0" y="661" fill="#5fafd7" font-weight="700" xml:space="preserve">ACTIVITY · this session</text>
|
|
104
|
+
<text x="203.4" y="661" fill="#7c7c7c" xml:space="preserve"> activity routing on</text>
|
|
105
|
+
<text x="24.0" y="680" fill="#7c7c7c" xml:space="preserve"> turns requests share</text>
|
|
106
|
+
<text x="24.0" y="699" fill="#d0d0d0" xml:space="preserve"> code </text>
|
|
107
|
+
<text x="109.8" y="699" fill="#5fafd7" xml:space="preserve">██████████</text>
|
|
108
|
+
<text x="187.8" y="699" fill="#d0d0d0" xml:space="preserve"> 14 41 100%</text>
|
|
109
|
+
<text x="24.0" y="718" fill="#d0d0d0" xml:space="preserve">Switches 5 · 5 by tier · 0 by activity</text>
|
|
110
|
+
<text x="24.0" y="737" fill="#d0d0d0" xml:space="preserve">Agreement classifier vs tools: 12 of 14 turns (86%)</text>
|
|
111
|
+
<text x="24.0" y="756" fill="#d0d0d0" xml:space="preserve">Shadow on would route 4 of 14 turns differently · est. −$0.420 … −$0.110 at list prices</text>
|
|
112
|
+
<text x="24.0" y="794" fill="#5fafd7" font-weight="700" xml:space="preserve">ACROSS SESSIONS · since the last reset</text>
|
|
113
|
+
<text x="24.0" y="813" fill="#7c7c7c" xml:space="preserve"> no turns recorded yet</text>
|
|
114
|
+
<rect x="24.0" y="818" width="117.0" height="18" rx="4" fill="#2e3340"/>
|
|
115
|
+
<text x="24.0" y="832" fill="#d0d0d0" xml:space="preserve">[ Reset stats ]</text>
|
|
116
|
+
<text x="141.0" y="832" fill="#7c7c7c" xml:space="preserve"> clears activity stats and routing vs your model, all sessions</text>
|
|
117
|
+
<text x="24.0" y="870" fill="#5fafd7" font-weight="700" xml:space="preserve">ESTIMATES · configured list prices</text>
|
|
118
|
+
<text x="24.0" y="889" fill="#d0d0d0" xml:space="preserve">Cache read benefit $1.522</text>
|
|
119
|
+
<text x="24.0" y="908" fill="#d0d0d0" xml:space="preserve">Switch tax $0.476</text>
|
|
120
|
+
<text x="24.0" y="927" fill="#7c7c7c" xml:space="preserve">Press ? for what these estimates leave out.</text>
|
|
121
|
+
<rect x="24.0" y="932" width="70.2" height="18" rx="4" fill="#2e3340"/>
|
|
122
|
+
<text x="24.0" y="946" fill="#d0d0d0" xml:space="preserve">[ Close ]</text>
|
|
123
|
+
</svg>
|
package/docs/user-guide.md
CHANGED
|
@@ -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
|
|
46
|
-
|
|
|
47
|
-
| `Routing on · ready`
|
|
48
|
-
| `choosing for this turn…`
|
|
49
|
-
| `⏵ next turn: high ✕`
|
|
50
|
-
| `⚠ Jev: no API key · keeping model`
|
|
51
|
-
| `⚠ Clef: no account ID · keeping model`
|
|
52
|
-
| `⚠ Jev timed out · keeping model`
|
|
53
|
-
| `○ Routing off · every turn uses …`
|
|
54
|
-
| `✕ Routing unavailable`
|
|
55
|
-
| `○ Router · subagents keep their own model`
|
|
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
|
|
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;
|
|
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 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
|
-
|
|
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
|
+

|
|
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
|
-
|
|
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,25 +137,27 @@ 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
|
|
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
|
-
| `
|
|
128
|
-
| `shadow` |
|
|
129
|
-
| `
|
|
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. |
|
|
130
149
|
|
|
131
|
-
|
|
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.
|
|
151
|
+
|
|
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`,
|
|
138
|
-
- A pinned turn uses the pin's
|
|
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
|
|
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.
|
|
@@ -144,10 +165,12 @@ The band's activity label appears only when the activity applies, so a weak or `
|
|
|
144
165
|
### Read the activity on the pane
|
|
145
166
|
|
|
146
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%`. The **Route** line shows the route the cell resolves to. **Replies** has a letter row under the strip.
|
|
147
|
-
- **Routing**: the **
|
|
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.
|
|
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, 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.
|
|
170
|
+
|
|
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, 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 stats** clears the activity counts and routing vs your model, for this session and across sessions.
|
|
149
172
|
|
|
150
|
-
`/router` without a UI surface adds an `Activity: ops (81%)` line and the
|
|
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`.
|
|
151
174
|
|
|
152
175
|
## Change routing
|
|
153
176
|
|
|
@@ -159,10 +182,11 @@ The band's activity label appears only when the activity applies, so a weak or `
|
|
|
159
182
|
| `/router pin <micro\|low\|medium\|high>` | Pin the next turn and its tool continuations. Routing on must already be enabled. |
|
|
160
183
|
| `/router activities <off\|shadow\|on>` | Set the [activity routing](#route-by-activity) mode. Saved to `router.json` at once; **Undo** reverts it. |
|
|
161
184
|
| `/model <name>` | Select a model and turn routing off. Use `/router auto` to turn it back on. |
|
|
162
|
-
| **
|
|
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`. |
|
|
163
187
|
| **pin** on the Now tab | Pin that tier for the next turn. Routing on must already be enabled. |
|
|
164
188
|
|
|
165
|
-
A pin does not change the next turn after the pinned turn finishes. A fresh session on a model that
|
|
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.
|
|
166
190
|
|
|
167
191
|
## Edit routes and policy
|
|
168
192
|
|
|
@@ -181,6 +205,7 @@ Under **Policy** on the same tab, pick the values. One **Save** writes them with
|
|
|
181
205
|
- **Votes to go down:** 1, 2, or 3 consecutive votes before a cheaper tier. A new or reset history needs one.
|
|
182
206
|
- **Payback horizon:** 1, 3, 5, or 10 later turns used by the downgrade estimate.
|
|
183
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).
|
|
184
209
|
|
|
185
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.
|
|
186
211
|
|
|
@@ -235,24 +260,25 @@ Keep the plugin enabled: in v1 it is the Mod. The Jev key option keeps its saved
|
|
|
235
260
|
|
|
236
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`.
|
|
237
262
|
|
|
238
|
-
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.
|
|
239
264
|
|
|
240
265
|
## Troubleshooting
|
|
241
266
|
|
|
242
|
-
| Symptom | Cause
|
|
243
|
-
| ------------------------------------------- |
|
|
244
|
-
| Status says `no API key` or `no API token` | The active classifier's plugin option is unset or unavailable to this process.
|
|
245
|
-
| Status says `no account ID` | Clef or Clef Flash is active without the Cloudflare account ID.
|
|
246
|
-
| Route stays on the current model | The classifier timed out, failed, is paused, or network policy refused it.
|
|
247
|
-
| `/model` changed but routing stopped | Choosing a model turns routing off.
|
|
248
|
-
| Router reports invalid configuration | `router.json` is invalid, or project/local settings redirect the router profile.
|
|
249
|
-
| Router says old settings need migration | `router.json` still contains v0.8 gateway keys or the 1.1 `jev` section.
|
|
250
|
-
| `⚠ OpenAI rejected the key · keeping model` | The OpenAI key is wrong, revoked, or lacks access to `gpt-6-luna`.
|
|
251
|
-
| `⚠ Ollama unreachable · keeping model` | No Ollama server listens on `127.0.0.1:11434`.
|
|
252
|
-
| `⚠ Ollama timed out · keeping model` | The model is loading after an idle period, or the machine is slow.
|
|
253
|
-
| `⚠ Ollama request failed · keeping model` | The tag in `model` is not pulled, or Ollama rejected a request setting.
|
|
254
|
-
| Band reads `v0.8 gateway settings remain` | The `jev-router[1m]` model or the `127.0.0.1:43170` base URL is still set.
|
|
255
|
-
| Router controls are unavailable | Claude Code is older than 2.1.289.
|
|
256
|
-
|
|
|
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. |
|
|
257
283
|
|
|
258
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).
|