@alexeiled/claude-router 1.13.0 → 1.15.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 +46 -0
- package/README.md +3 -0
- package/docs/architecture.md +11 -1
- package/docs/configuration.md +6 -2
- package/docs/evaluation.md +8 -7
- package/docs/native-router.md +2 -1
- package/docs/router-band.svg +30 -8
- package/docs/router-pane-now.svg +134 -111
- package/docs/router-pane-policy.svg +47 -43
- package/docs/router-pane-usage-whatif.svg +75 -12
- package/docs/router-pane-usage.svg +79 -13
- package/docs/routing-modes.md +139 -0
- package/docs/user-guide.md +11 -5
- package/hooks/native-router.mjs +170 -23
- package/lib/activity.mjs +8 -2
- package/lib/band.mjs +43 -11
- package/lib/config.mjs +69 -17
- package/lib/cost.mjs +3 -0
- package/lib/display.mjs +21 -2
- package/lib/modes.mjs +98 -0
- package/lib/panel.mjs +338 -45
- package/lib/route.mjs +80 -23
- package/lib/subagents.mjs +182 -64
- package/lib/usage.mjs +32 -20
- package/lib/view.mjs +3 -0
- package/package.json +2 -1
- package/types/index.d.ts +34 -10
|
@@ -1,12 +1,12 @@
|
|
|
1
|
-
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 696
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 696 1104" role="img" aria-labelledby="title desc">
|
|
2
2
|
<title id="title">Router pane, Usage tab</title>
|
|
3
3
|
<desc id="desc">The last 7 days across sessions: the period row, routing saved against each session’s own model as a ledger (your model, cheaper models, stronger models, switch cache writes, routed), the replies and tokens, the cost by activity with coding opened to its routes and cost parts, the cost by day, what is worth a look with a link to Routes, subagents, and Delete history.</desc>
|
|
4
4
|
<style>
|
|
5
5
|
text { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace; font-size: 13px; }
|
|
6
6
|
.cap { font-family: system-ui, -apple-system, 'Segoe UI', sans-serif; font-size: 12px; fill: #9a988f; }
|
|
7
7
|
</style>
|
|
8
|
-
<rect width="696" height="
|
|
9
|
-
<rect x="10" y="10" width="676" height="
|
|
8
|
+
<rect width="696" height="1104" rx="8" fill="#1c1c1c"/>
|
|
9
|
+
<rect x="10" y="10" width="676" height="1084" rx="6" fill="none" stroke="#3f5f8f"/>
|
|
10
10
|
<text x="24.0" y="34" fill="#5fafd7" font-weight="700" xml:space="preserve">ROUTING</text>
|
|
11
11
|
<rect x="94.2" y="20" width="62.4" height="18" rx="4" fill="#87afff"/>
|
|
12
12
|
<text x="94.2" y="34" fill="#0d1016" font-weight="700" xml:space="preserve">[ ◉ on ]</text>
|
|
@@ -38,7 +38,7 @@
|
|
|
38
38
|
<rect x="390.6" y="77" width="54.6" height="18" rx="4" fill="#2e3340"/>
|
|
39
39
|
<text x="390.6" y="91" fill="#d0d0d0" xml:space="preserve">[ All ]</text>
|
|
40
40
|
<text x="453.0" y="91" fill="#7c7c7c" xml:space="preserve"> p next</text>
|
|
41
|
-
<text x="24.0" y="110" fill="#7c7c7c" xml:space="preserve">all
|
|
41
|
+
<text x="24.0" y="110" fill="#7c7c7c" xml:space="preserve">all projects · Oct 7 – Oct 13 · each session vs its own model</text>
|
|
42
42
|
<text x="24.0" y="148" fill="#d0d0d0" xml:space="preserve">Routing saved </text>
|
|
43
43
|
<text x="133.2" y="148" fill="#6fcf97" font-weight="700" xml:space="preserve">$11.78 (43%)</text>
|
|
44
44
|
<text x="226.8" y="148" fill="#d0d0d0" xml:space="preserve"> vs your model</text>
|
|
@@ -112,13 +112,79 @@
|
|
|
112
112
|
<text x="328.2" y="585" fill="#7c7c7c" xml:space="preserve"> · mostly Opus 5.5 · xhigh</text>
|
|
113
113
|
<rect x="546.6" y="571" width="78.0" height="18" rx="4" fill="#2e3340"/>
|
|
114
114
|
<text x="546.6" y="585" fill="#d0d0d0" xml:space="preserve">[ Routes ]</text>
|
|
115
|
-
<text x="24.0" y="623" fill="#5fafd7" font-weight="700" xml:space="preserve">SUBAGENTS
|
|
116
|
-
<text x="
|
|
117
|
-
<text x="
|
|
118
|
-
<text x="
|
|
119
|
-
<text x="
|
|
120
|
-
<
|
|
121
|
-
<text x="
|
|
122
|
-
<
|
|
123
|
-
<text x="
|
|
115
|
+
<text x="24.0" y="623" fill="#5fafd7" font-weight="700" xml:space="preserve">SUBAGENTS</text>
|
|
116
|
+
<text x="94.2" y="623" fill="#7c7c7c" xml:space="preserve"> · all projects · Oct 7 – Oct 13 subagent routing on</text>
|
|
117
|
+
<text x="39.6" y="642" fill="#c3e88d" xml:space="preserve">■■■■■</text>
|
|
118
|
+
<text x="78.6" y="642" fill="#f78c6c" xml:space="preserve">■</text>
|
|
119
|
+
<text x="86.4" y="642" fill="#f78c6c" xml:space="preserve">□□</text>
|
|
120
|
+
<text x="102.0" y="642" fill="#c792ea" xml:space="preserve">■■</text>
|
|
121
|
+
<text x="117.6" y="642" fill="#c792ea" xml:space="preserve">□□□□□</text>
|
|
122
|
+
<text x="172.2" y="642" fill="#c3e88d" xml:space="preserve">Haiku 5.5 5</text>
|
|
123
|
+
<text x="258.0" y="642" fill="#7c7c7c" xml:space="preserve"> · </text>
|
|
124
|
+
<text x="281.4" y="642" fill="#f78c6c" xml:space="preserve">Sonnet 5.5 3</text>
|
|
125
|
+
<text x="375.0" y="642" fill="#7c7c7c" xml:space="preserve"> · </text>
|
|
126
|
+
<text x="398.4" y="642" fill="#c792ea" xml:space="preserve">Opus 5.5 7</text>
|
|
127
|
+
<text x="24.0" y="661" fill="#d0d0d0" xml:space="preserve"> 15 agents</text>
|
|
128
|
+
<text x="109.8" y="661" fill="#7c7c7c" xml:space="preserve"> · </text>
|
|
129
|
+
<text x="133.2" y="661" fill="#d0d0d0" xml:space="preserve">■ 8 moved by the router</text>
|
|
130
|
+
<text x="312.6" y="661" fill="#7c7c7c" xml:space="preserve"> · </text>
|
|
131
|
+
<text x="336.0" y="661" fill="#d0d0d0" xml:space="preserve">□ 7 on Claude Code’s pick</text>
|
|
132
|
+
<text x="24.0" y="680" fill="#d0d0d0" xml:space="preserve"> Routing saved </text>
|
|
133
|
+
<text x="148.8" y="680" fill="#6fcf97" xml:space="preserve">$0.51</text>
|
|
134
|
+
<text x="187.8" y="680" fill="#d0d0d0" xml:space="preserve"> (14%)</text>
|
|
135
|
+
<text x="234.6" y="680" fill="#7c7c7c" xml:space="preserve"> on 9 routed agents</text>
|
|
136
|
+
<text x="24.0" y="699" fill="#d0d0d0" xml:space="preserve"> per day </text>
|
|
137
|
+
<text x="102.0" y="699" fill="#d0d0d0" font-weight="700" xml:space="preserve">▁▂▂▃▃▅█</text>
|
|
138
|
+
<text x="156.6" y="699" fill="#7c7c7c" xml:space="preserve"> peak 6 on Oct 13</text>
|
|
139
|
+
<text x="24.0" y="737" fill="#d0d0d0" font-weight="700" xml:space="preserve"> ROUTED</text>
|
|
140
|
+
<text x="86.4" y="737" fill="#7c7c7c" xml:space="preserve"> · the router picked the model at spawn</text>
|
|
141
|
+
<text x="24.0" y="756" fill="#7c7c7c" xml:space="preserve"> type agents cost vs CC</text>
|
|
142
|
+
<text x="39.6" y="775" fill="#d0d0d0" xml:space="preserve">▸</text>
|
|
143
|
+
<text x="55.2" y="775" fill="#d0d0d0" xml:space="preserve">Explore</text>
|
|
144
|
+
<text x="203.4" y="775" fill="#c3e88d" xml:space="preserve">■■■■</text>
|
|
145
|
+
<text x="297.0" y="775" fill="#d0d0d0" xml:space="preserve"> 4</text>
|
|
146
|
+
<text x="320.4" y="775" fill="#d0d0d0" xml:space="preserve"> $0.18</text>
|
|
147
|
+
<text x="390.6" y="775" fill="#6fcf97" xml:space="preserve"> −$0.72 ▼</text>
|
|
148
|
+
<text x="39.6" y="794" fill="#d0d0d0" xml:space="preserve">▸</text>
|
|
149
|
+
<text x="55.2" y="794" fill="#d0d0d0" xml:space="preserve">dev-flow:reviewer</text>
|
|
150
|
+
<text x="203.4" y="794" fill="#f78c6c" xml:space="preserve">□</text>
|
|
151
|
+
<text x="211.2" y="794" fill="#c792ea" xml:space="preserve">■■</text>
|
|
152
|
+
<text x="297.0" y="794" fill="#d0d0d0" xml:space="preserve"> 3</text>
|
|
153
|
+
<text x="320.4" y="794" fill="#d0d0d0" xml:space="preserve"> $2.50</text>
|
|
154
|
+
<text x="390.6" y="794" fill="#f0b429" xml:space="preserve"> +$0.77 ▲</text>
|
|
155
|
+
<text x="39.6" y="813" fill="#d0d0d0" xml:space="preserve">▸</text>
|
|
156
|
+
<text x="55.2" y="813" fill="#d0d0d0" xml:space="preserve">general-purpose</text>
|
|
157
|
+
<text x="203.4" y="813" fill="#c3e88d" xml:space="preserve">■</text>
|
|
158
|
+
<text x="211.2" y="813" fill="#f78c6c" xml:space="preserve">■</text>
|
|
159
|
+
<text x="297.0" y="813" fill="#d0d0d0" xml:space="preserve"> 2</text>
|
|
160
|
+
<text x="320.4" y="813" fill="#d0d0d0" xml:space="preserve"> $0.47</text>
|
|
161
|
+
<text x="390.6" y="813" fill="#6fcf97" xml:space="preserve"> −$0.56 ▼</text>
|
|
162
|
+
<text x="24.0" y="851" fill="#d0d0d0" font-weight="700" xml:space="preserve"> NOT ROUTED</text>
|
|
163
|
+
<text x="117.6" y="851" fill="#7c7c7c" xml:space="preserve"> · Claude Code picked the model</text>
|
|
164
|
+
<text x="39.6" y="870" fill="#d0d0d0" xml:space="preserve">▸</text>
|
|
165
|
+
<text x="55.2" y="870" fill="#d0d0d0" xml:space="preserve">workflow agent</text>
|
|
166
|
+
<text x="203.4" y="870" fill="#c792ea" xml:space="preserve">□□□□</text>
|
|
167
|
+
<text x="297.0" y="870" fill="#d0d0d0" xml:space="preserve"> 4</text>
|
|
168
|
+
<text x="320.4" y="870" fill="#d0d0d0" xml:space="preserve"> $2.00</text>
|
|
169
|
+
<text x="390.6" y="870" fill="#7c7c7c" xml:space="preserve"> the workflow sets it</text>
|
|
170
|
+
<text x="39.6" y="889" fill="#d0d0d0" xml:space="preserve">▸</text>
|
|
171
|
+
<text x="55.2" y="889" fill="#d0d0d0" xml:space="preserve">fork</text>
|
|
172
|
+
<text x="203.4" y="889" fill="#c792ea" xml:space="preserve">□</text>
|
|
173
|
+
<text x="297.0" y="889" fill="#d0d0d0" xml:space="preserve"> 1</text>
|
|
174
|
+
<text x="320.4" y="889" fill="#d0d0d0" xml:space="preserve"> $0.33</text>
|
|
175
|
+
<text x="390.6" y="889" fill="#7c7c7c" xml:space="preserve"> your model</text>
|
|
176
|
+
<text x="39.6" y="908" fill="#d0d0d0" xml:space="preserve">▸</text>
|
|
177
|
+
<text x="55.2" y="908" fill="#d0d0d0" xml:space="preserve">pinned model</text>
|
|
178
|
+
<text x="203.4" y="908" fill="#f78c6c" xml:space="preserve">□</text>
|
|
179
|
+
<text x="297.0" y="908" fill="#d0d0d0" xml:space="preserve"> 1</text>
|
|
180
|
+
<text x="320.4" y="908" fill="#d0d0d0" xml:space="preserve"> $0.12</text>
|
|
181
|
+
<text x="390.6" y="908" fill="#7c7c7c" xml:space="preserve"> its agent file sets it</text>
|
|
182
|
+
<text x="24.0" y="946" fill="#7c7c7c" xml:space="preserve"> ■ moved by the router · □ Claude Code’s pick · color: the model</text>
|
|
183
|
+
<text x="24.0" y="965" fill="#7c7c7c" xml:space="preserve"> vs CC: the same tokens on Claude Code’s pick, at list prices</text>
|
|
184
|
+
<text x="24.0" y="1003" fill="#7c7c7c" xml:space="preserve"> API list prices · same tokens and output length · not a bill;</text>
|
|
185
|
+
<text x="24.0" y="1022" fill="#7c7c7c" xml:space="preserve"> on a Claude plan it stands for quota · answer quality not measured</text>
|
|
186
|
+
<rect x="24.0" y="1046" width="140.4" height="18" rx="4" fill="#2e3340"/>
|
|
187
|
+
<text x="24.0" y="1060" fill="#7c7c7c" xml:space="preserve">[ Delete history ]</text>
|
|
188
|
+
<rect x="24.0" y="1065" width="70.2" height="18" rx="4" fill="#2e3340"/>
|
|
189
|
+
<text x="24.0" y="1079" fill="#d0d0d0" xml:space="preserve">[ Close ]</text>
|
|
124
190
|
</svg>
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
# Routing modes
|
|
2
|
+
|
|
3
|
+
One setting trades cost against answer quality: `cost`, `balanced` (the default) or `quality`. The classifier and
|
|
4
|
+
your routes stay as they are. The mode moves the route each tier runs by one fixed step.
|
|
5
|
+
|
|
6
|
+
| Mode | What changes |
|
|
7
|
+
| --- | --- |
|
|
8
|
+
| `cost` | A cheaper route where the turn allows it: the tier below when that tier runs a model with a lower input price, else one effort level less on the same model. Never below `low`. |
|
|
9
|
+
| `balanced` | Nothing: every tier runs its route as configured. |
|
|
10
|
+
| `quality` | One effort level more on the same model, else the route of the tier above. |
|
|
11
|
+
|
|
12
|
+
In every mode:
|
|
13
|
+
|
|
14
|
+
- `micro` turns keep the `micro` route. Only the classifier makes a turn `micro`; `cost` never does.
|
|
15
|
+
- A pin (`/router pin <tier>`) runs that tier's configured route. With routing off (`/router off`, `/model`),
|
|
16
|
+
Claude's model runs, as before.
|
|
17
|
+
- A route never loses its effort: an effort level moves only within what the model lists in `models.<alias>.efforts`,
|
|
18
|
+
and a route with a `null` effort (the session's) or a model without efforts has no effort step.
|
|
19
|
+
|
|
20
|
+
## Choose a mode
|
|
21
|
+
|
|
22
|
+
The mode comes from the first of these that sets one:
|
|
23
|
+
|
|
24
|
+
1. **This session:** `/router mode cost`, `/router mode balanced` or `/router mode quality`. `/router mode default`
|
|
25
|
+
clears it. A resume of the session keeps it; a new session does not.
|
|
26
|
+
2. **The project:** `.claude/router.json` in the directory Claude Code runs in. It may hold only the mode, for
|
|
27
|
+
example `{ "mode": "cost" }`. A file with any other key, a mode that is not one of the three, or JSON that does not
|
|
28
|
+
parse is ignored, and the pane and `/router` say why. Add it to `.gitignore` to keep the choice to yourself.
|
|
29
|
+
3. **The profile:** `"mode"` in `router.json`, or **Mode** on the pane's Policy tab, which saves at once with Undo.
|
|
30
|
+
4. `balanced`.
|
|
31
|
+
|
|
32
|
+
The band, the Now tab and `/router` show the mode and its source, for example `cost (session)`. The prompt footer
|
|
33
|
+
names a mode other than balanced.
|
|
34
|
+
|
|
35
|
+
## When a change applies
|
|
36
|
+
|
|
37
|
+
A change applies from the next turn. It changes the route the router prefers; the route in use moves through the
|
|
38
|
+
same checks as any other switch. On the same task a cheaper route waits until `minDwellRequests` requests have run on
|
|
39
|
+
the route in use and a check (tests, build, lint) has passed since. A move must also pay back its cache write. Until
|
|
40
|
+
then the band says why the route stays. Pin a tier to run its configured route now.
|
|
41
|
+
|
|
42
|
+
## Policy per mode
|
|
43
|
+
|
|
44
|
+
Each mode except `balanced` replaces some `policy` fields while it is active. The built-in values come from
|
|
45
|
+
codex-router and are **not tuned** on this router:
|
|
46
|
+
|
|
47
|
+
```json
|
|
48
|
+
{
|
|
49
|
+
"modes": {
|
|
50
|
+
"cost": { "policy": { "upgradeVotes": 3, "upgradeBase": 0.85, "jumpConfidence": 0.98, "downgradeVotes": 1,
|
|
51
|
+
"downgradeMass": 0.8, "minDwellRequests": 4, "escalationHoldTurns": 1 } },
|
|
52
|
+
"quality": { "policy": { "upgradeVotes": 1, "upgradeBase": 0.6, "jumpConfidence": 0.9, "downgradeVotes": 3,
|
|
53
|
+
"downgradeMass": 0.95, "minDwellRequests": 16, "escalationHoldTurns": 4 } }
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Your `modes` entries merge field by field over these. A mode's field beats the same field in `policy`. Only `policy`
|
|
59
|
+
keys are allowed, and the result must pass the same checks as `policy`.
|
|
60
|
+
|
|
61
|
+
## Every decision
|
|
62
|
+
|
|
63
|
+
The route each mode gives a session's first turn, for each classifier answer, through the router's real decision
|
|
64
|
+
path. Generated from the test data by `npm run docs:modes`; `test/mode-matrix.test.mjs` fails when it is stale.
|
|
65
|
+
|
|
66
|
+
<!-- mode-matrix:start -->
|
|
67
|
+
**Built-in routes**
|
|
68
|
+
|
|
69
|
+
| Classifier | Activities | cost | balanced | quality |
|
|
70
|
+
| --- | --- | --- | --- | --- |
|
|
71
|
+
| micro | code, debug, explore, plan, review, ops, docs, uncertain | Haiku · medium | Haiku · medium | Haiku · medium |
|
|
72
|
+
| low | code, debug, plan, review | Sonnet · medium | Sonnet · high | Sonnet · xhigh |
|
|
73
|
+
| low | explore, ops, docs, uncertain | Haiku · medium | Haiku · high | Haiku · xhigh |
|
|
74
|
+
| medium | code, debug, plan, review | Sonnet · high | Opus · medium | Opus · high |
|
|
75
|
+
| medium | explore, docs, uncertain | Haiku · high | Opus · medium | Opus · high |
|
|
76
|
+
| medium | ops | Haiku · medium | Haiku · high | Haiku · xhigh |
|
|
77
|
+
| high | code, debug, explore, plan, review, docs, uncertain | Opus · high | Opus · xhigh | Opus · max |
|
|
78
|
+
| high | ops | Haiku · high | Opus · xhigh | Opus · max |
|
|
79
|
+
| uncertain | code, debug, plan, review | Sonnet · medium | Sonnet · high | Sonnet · xhigh |
|
|
80
|
+
| uncertain | explore, ops, docs, uncertain | Haiku · medium | Haiku · high | Haiku · xhigh |
|
|
81
|
+
|
|
82
|
+
**`routes.high` = Opus · high**
|
|
83
|
+
|
|
84
|
+
| Classifier | Activities | cost | balanced | quality |
|
|
85
|
+
| --- | --- | --- | --- | --- |
|
|
86
|
+
| micro | code, debug, explore, plan, review, ops, docs, uncertain | Haiku · medium | Haiku · medium | Haiku · medium |
|
|
87
|
+
| low | code, debug, plan, review | Sonnet · medium | Sonnet · high | Sonnet · xhigh |
|
|
88
|
+
| low | explore, ops, docs, uncertain | Haiku · medium | Haiku · high | Haiku · xhigh |
|
|
89
|
+
| medium | code, debug, plan, review | Sonnet · high | Opus · medium | Opus · high |
|
|
90
|
+
| medium | explore, docs, uncertain | Haiku · high | Opus · medium | Opus · high |
|
|
91
|
+
| medium | ops | Haiku · medium | Haiku · high | Haiku · xhigh |
|
|
92
|
+
| high | code, debug, explore, plan, review, docs, uncertain | Opus · medium | Opus · high | Opus · xhigh |
|
|
93
|
+
| high | ops | Haiku · high | Opus · high | Opus · xhigh |
|
|
94
|
+
| uncertain | code, debug, plan, review | Sonnet · medium | Sonnet · high | Sonnet · xhigh |
|
|
95
|
+
| uncertain | explore, ops, docs, uncertain | Haiku · medium | Haiku · high | Haiku · xhigh |
|
|
96
|
+
<!-- mode-matrix:end -->
|
|
97
|
+
|
|
98
|
+
## Known trade-offs
|
|
99
|
+
|
|
100
|
+
The steps are fixed rules, with no per-activity exceptions. Two cells go against this router's own model notes
|
|
101
|
+
(`lib/config.mjs`), and replay data should decide them later:
|
|
102
|
+
|
|
103
|
+
- `cost` at `high` for **ops** runs Haiku 5.5 at high (the `medium` ops route), although Haiku trails Opus on
|
|
104
|
+
multi-step tool work. Repeated tool errors cannot escalate it: no tier is above `high`. For such a task, pin `high`
|
|
105
|
+
or switch to `balanced`.
|
|
106
|
+
- `cost` at `low` for **code, debug, plan and review** runs Sonnet 5.5 at medium, which scored below Haiku 5.5 at high
|
|
107
|
+
on FrontierCode and costs more per token.
|
|
108
|
+
|
|
109
|
+
With the built-in routes, `cost` at `low` runs Haiku 5.5 at medium, the same route as `micro`.
|
|
110
|
+
|
|
111
|
+
## Measured impact
|
|
112
|
+
|
|
113
|
+
One 5-turn coding task (read two files, add a function with tests, run the tests, review, add edge-case tests), the
|
|
114
|
+
same prompts in a new session per mode, Jev classifier, built-in routes. Cost is a list-price estimate of the measured
|
|
115
|
+
tokens ([raw results](../experiments/mod-router/results/mode-live-acceptance.json)).
|
|
116
|
+
|
|
117
|
+
| Mode | Replies by route | Switches | Output tokens | Estimated cost |
|
|
118
|
+
| -------- | ----------------------------------- | -------- | ------------- | -------------- |
|
|
119
|
+
| cost | Haiku · medium 2, Sonnet · medium 6 | 1 | 2,860 | $0.166 |
|
|
120
|
+
| balanced | Opus · medium 10 | 0 | 3,986 | $0.323 |
|
|
121
|
+
| quality | Opus · high 8 | 0 | 5,332 | $0.358 |
|
|
122
|
+
|
|
123
|
+
**These are single runs.** The classifier's answers vary from run to run: its confidence that the first turn was
|
|
124
|
+
`micro` was 92%, 74% and 79% in the three runs, so part of the first-turn difference is classifier noise, not the mode.
|
|
125
|
+
Read the numbers as the direction and rough size of the effect, not as a benchmark.
|
|
126
|
+
|
|
127
|
+
- `quality` ran the same model as `balanced`, at the same price per token. All of its extra cost is output: 34% more
|
|
128
|
+
tokens at the higher effort. A list-price estimate can't show this: priced as one nominal turn each, a fixed set of 20
|
|
129
|
+
prompts comes to $2.916 in both modes ([probe](../experiments/mod-router/results/mode-probe-jev.json)).
|
|
130
|
+
- `cost` spent $0.069 of its $0.166 on one cache write, for the move to Sonnet. A longer session spreads that write
|
|
131
|
+
over more turns.
|
|
132
|
+
- Every task ended with the tests passing; this run does not compare the quality of the answers.
|
|
133
|
+
|
|
134
|
+
## Records
|
|
135
|
+
|
|
136
|
+
The decision at the start of each turn writes one line to Claude Code's debug log (`claude --debug`): `router
|
|
137
|
+
decision` with the mode, its source, the classifier's tier, the tier and reason the router chose, and the route. A move
|
|
138
|
+
later in the turn (a review, the turn's tool calls, a context fit) writes none; the usage cells show it. Usage records keep each reply
|
|
139
|
+
under its mode (`mode|activity|tier|model@effort`).
|
package/docs/user-guide.md
CHANGED
|
@@ -53,13 +53,15 @@ Read the first line of the picture from left to right:
|
|
|
53
53
|
| `⚠ Jev timed out · keeping model` | The classifier failed: timed out, unreachable, rejected the key, or paused. |
|
|
54
54
|
| `○ 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`. |
|
|
55
55
|
| `✕ Routing unavailable` | Nothing routes: an old Claude Code or leftover v0.8 settings. **Fix** opens the pane. |
|
|
56
|
-
| `○ Router ·
|
|
56
|
+
| `○ Router · ■ Haiku 5.5 · moved down by the router` | You are viewing a subagent's transcript. The model it runs on, and who picked it; see below. |
|
|
57
57
|
|
|
58
58
|
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 this session against your model, the one `/model` selects now: `session saved $1.84 (22%) vs Opus 5.5 · xhigh · 64 replies · cold-cache writes +$0.47`, or `session extra $2.48 (×5.0) vs Haiku 5.5 · high · 41 replies · stronger models +$2.31` when routing cost more. The last part names the larger of the two costs behind the result, when there is one. After a `/model` change the row shows the whole session against the new model. Before the tenth routed reply it reads `session 3 replies · too early to compare`. When the row is short, the cost part drops first, then the reply count. 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.
|
|
59
59
|
|
|
60
60
|
The band steps aside while a survey needs the space.
|
|
61
61
|
|
|
62
|
-
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: Haiku for exploration, Opus for clearly hard tasks, Sonnet for the rest. 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. See [Subagent routing](configuration.md#subagent-routing).
|
|
62
|
+
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: Haiku for exploration, Opus for clearly hard tasks, Sonnet for the rest. 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 shows this session's agents. See [Subagent routing](configuration.md#subagent-routing).
|
|
63
|
+
|
|
64
|
+
In a subagent's transcript the band names the model the agent runs on and who picked it. `■ Haiku 5.5 · moved down by the router · Claude Code: Opus 5.5` means the router chose a cheaper model than Claude Code would have; `up` means a stronger one. `□ Sonnet 5.5 · the router kept Claude Code’s pick` means the router agreed. `□ Opus 5.5 · Claude Code’s pick: the workflow sets it` means the router did not route the agent, and says why. A narrow band drops the `Claude Code:` part first. The band falls back to `subagent model chosen at spawn` when the router has no record of the agent, such as after a plugin reload, and to `subagents keep their own model` with subagent routing off.
|
|
63
65
|
|
|
64
66
|
## Open the router pane
|
|
65
67
|
|
|
@@ -75,13 +77,13 @@ Run `/router` or select **Router** above the prompt. Without a UI surface, as in
|
|
|
75
77
|
|
|
76
78
|
The top line of every tab, `ROUTING [ ◉ on ] [ ○ off ] Jev ready · 347 ms`, shows the routing mode, switches it, and says whether the classifier is ready. Press `o` or `f` while the pane has focus. **?** shows what the estimates leave out. When routing is unavailable, the top line reads `ROUTING unavailable Claude’s model is kept` with the reason under it, and offers no on or off: see [Troubleshooting](#troubleshooting).
|
|
77
79
|
|
|
78
|
-

|
|
80
|
+

|
|
79
81
|
|
|
80
82
|
The **Now** tab answers "what runs next turn, and why". **Next turn** names the tier, the model and effort, and, when an activity override runs, the tier's own model beside it. **Activity** names the classifier's activity as a verb, such as `coding 84%`, with the two next answers and the threshold at which an activity applies. **Why** gives the reason; under it, `Jev gave stronger tiers 88% (needs 82%) · switch ≈ $0.48` compares the classifier's support for the switch with the bar the policy set, and gives the estimated switch cost. **Pin next** has one button per tier, strongest first, 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.
|
|
81
83
|
|
|
82
84
|
**SESSION** sums this session from its first routed reply: `since 14:18 · 86 routed replies · 9 route switches`. The strip under it 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, so it spans all those replies on one line. After Claude Code restarts a resumed session, the strip starts again and says since when, such as `since 15:02`, while the heading still counts the whole session. The replies per tier, `■ low 41 ■ medium 12 ■ high 33`, double as the color key, and the routed replies per activity follow. **last switch** says when the route last changed and between which tiers, or between which routes when a switch stayed inside a tier, with the activity it ran for. The last line is what routing saved, or cost, against your model this session, with the switch cache writes in it; **Usage** opens the Usage tab on this session.
|
|
83
85
|
|
|
84
|
-
**TODAY** appears once another session added to today, with the same line for every session today and its own **Usage** link. **WORTH A LOOK** shows today's first finding from the Usage tab, from 20 routed replies, with the tab that changes it. The last lines give the context gauge, the cache reuse and the cost Claude reports; **details** adds the counters and estimates in [Understand usage and estimates](#understand-usage-and-estimates).
|
|
86
|
+
**TODAY** appears once another session added to today, with the same line for every session today and its own **Usage** link. **SUBAGENTS** appears once this session started a subagent: how many are in the middle of a turn now (`● 1 running`; an agent that waits on its own background command is not counted until it resumes), the same squares as on the Usage tab, and what routing saved on them; **Usage** opens the Usage tab on this session. **WORTH A LOOK** shows today's first finding from the Usage tab, from 20 routed replies, with the tab that changes it. The last lines give the context gauge, the cache reuse and the cost Claude reports; **details** adds the counters and estimates in [Understand usage and estimates](#understand-usage-and-estimates).
|
|
85
87
|
|
|
86
88
|
### Save and undo changes
|
|
87
89
|
|
|
@@ -144,7 +146,7 @@ These are estimates, not a bill. They hold the tokens and the output length the
|
|
|
144
146
|
- **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.
|
|
145
147
|
- **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.
|
|
146
148
|
|
|
147
|
-
On the Usage tab, **SUBAGENTS
|
|
149
|
+
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. 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). Plan quota is not on the pane: Claude Code shows it in `/usage`. 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.
|
|
148
150
|
|
|
149
151
|
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.
|
|
150
152
|
|
|
@@ -223,11 +225,15 @@ On the **Classifier** tab, **ACROSS SESSIONS · since the last reset** shows the
|
|
|
223
225
|
| `/router off` | Turn routing off and keep Claude's selected model. |
|
|
224
226
|
| `/router pin <micro\|low\|medium\|high>` | Pin the next turn and its tool continuations. Routing on must already be enabled. |
|
|
225
227
|
| `/router activities <off\|on>` | Set the [activity routing](#route-by-activity) mode. Saved to `router.json` at once; **Undo** reverts it. |
|
|
228
|
+
| `/router mode <cost\|balanced\|quality>` | Set this session's [routing mode](routing-modes.md) from the next turn. A resume keeps it. |
|
|
229
|
+
| `/router mode default` | Clear the session's mode: the project's or the profile's applies again. |
|
|
226
230
|
| `/model <name>` | Select a model and turn routing off. Use `/router auto` to turn it back on. |
|
|
227
231
|
| **Turn on** / **Turn off** on the band | The same as `/router auto` and `/router off`. |
|
|
228
232
|
| **on** / **off** on the pane (`o` / `f`) | The same as `/router auto` and `/router off`. |
|
|
229
233
|
| **pin** on the Now tab | Pin that tier for the next turn. Routing on must already be enabled. |
|
|
230
234
|
|
|
235
|
+
A routing mode moves each tier's route one step toward cost or quality; pins and `micro` turns are not moved. The band and the Now tab show the mode and where it comes from, such as `cost (session)`. A change applies from the next turn, and the route in use moves only through the usual checks, so on a running task a cheaper route can wait a few requests and for a passed test. **Mode** on the Policy tab sets the profile's mode. See [Routing modes](routing-modes.md).
|
|
236
|
+
|
|
231
237
|
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.
|
|
232
238
|
|
|
233
239
|
## Edit routes and policy
|