@alexeiled/claude-router 1.1.1 → 1.3.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 +15 -4
- package/CHANGELOG.md +33 -0
- package/README.md +9 -9
- package/docs/architecture.md +25 -23
- package/docs/configuration.md +76 -22
- package/docs/native-router.md +22 -17
- package/docs/router-band.svg +14 -14
- package/docs/router-pane-classifier.svg +45 -0
- package/docs/router-pane-now.svg +6 -5
- package/docs/router-pane-routing.svg +81 -0
- package/docs/user-guide.md +72 -35
- package/hooks/native-router.mjs +263 -56
- package/lib/config.mjs +116 -30
- package/lib/jev-contract.mjs +25 -6
- package/lib/native-band.mjs +31 -14
- package/lib/native-display.mjs +34 -3
- package/lib/native-jev.mjs +7 -5
- package/lib/native-panel.mjs +202 -134
- package/package.json +2 -2
- package/scripts/migrate-config.mjs +14 -3
- package/types/index.d.ts +6 -4
- package/docs/router-pane-tiers.svg +0 -62
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 626 363" role="img" aria-labelledby="title desc">
|
|
2
|
+
<title id="title">Router pane, Classifier tab</title>
|
|
3
|
+
<desc id="desc">The classifier rows with the active one marked, a missing Jev API key with Set up, the deadline, health, the receiving host and the credentials each classifier needs, and Undo after a switch.</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="626" height="363" rx="8" fill="#1c1c1c"/>
|
|
9
|
+
<rect x="10" y="10" width="606" height="343" rx="6" fill="none" stroke="#3f5f8f"/>
|
|
10
|
+
<text x="24.0" y="34" fill="#5fafd7" font-weight="700" xml:space="preserve">ROUTER · Auto</text>
|
|
11
|
+
<text x="148.8" y="34" fill="#87d787" xml:space="preserve">Clef Flash ready</text>
|
|
12
|
+
<text x="24.0" y="53" fill="#87afff" font-weight="700" xml:space="preserve">[ Auto ]</text>
|
|
13
|
+
<text x="94.2" y="53" fill="#d0d0d0" xml:space="preserve">[ Manual ]</text>
|
|
14
|
+
<text x="172.2" y="53" fill="#7c7c7c" xml:space="preserve"> Manual keeps the /model choice</text>
|
|
15
|
+
<text x="24.0" y="72" fill="#d0d0d0" xml:space="preserve">[ Now ]</text>
|
|
16
|
+
<text x="86.4" y="72" fill="#d0d0d0" xml:space="preserve">[ Routing ]</text>
|
|
17
|
+
<text x="180.0" y="72" fill="#87afff" font-weight="700" xml:space="preserve">[ Classifier ]</text>
|
|
18
|
+
<text x="297.0" y="72" fill="#d0d0d0" xml:space="preserve">[ Usage ]</text>
|
|
19
|
+
<text x="375.0" y="72" fill="#d0d0d0" xml:space="preserve">[ ? ]</text>
|
|
20
|
+
<text x="24.0" y="110" fill="#5fafd7" font-weight="700" xml:space="preserve">CLASSIFIER</text>
|
|
21
|
+
<text x="102.0" y="110" fill="#7c7c7c" xml:space="preserve"> · applies next turn · saves at once</text>
|
|
22
|
+
<text x="24.0" y="129" fill="#7c7c7c" xml:space="preserve">Asked once per new turn.</text>
|
|
23
|
+
<text x="24.0" y="148" fill="#d0d0d0" xml:space="preserve">[ ○ Jev ]</text>
|
|
24
|
+
<text x="164.4" y="148" fill="#7c7c7c" xml:space="preserve">api.typesafe.ai</text>
|
|
25
|
+
<text x="320.4" y="148" fill="#d7af5f" xml:space="preserve">○ no API key </text>
|
|
26
|
+
<text x="429.6" y="148" fill="#d0d0d0" xml:space="preserve">[ Set up ]</text>
|
|
27
|
+
<text x="24.0" y="167" fill="#d0d0d0" xml:space="preserve">[ ○ Clef ]</text>
|
|
28
|
+
<text x="164.4" y="167" fill="#7c7c7c" xml:space="preserve">api.cloudflare.com</text>
|
|
29
|
+
<text x="320.4" y="167" fill="#87d787" xml:space="preserve">● ready</text>
|
|
30
|
+
<text x="24.0" y="186" fill="#87afff" font-weight="700" xml:space="preserve">[ ◉ Clef Flash ]</text>
|
|
31
|
+
<text x="164.4" y="186" fill="#7c7c7c" xml:space="preserve">api.cloudflare.com</text>
|
|
32
|
+
<text x="320.4" y="186" fill="#87d787" xml:space="preserve">● ready</text>
|
|
33
|
+
<text x="24.0" y="205" fill="#d0d0d0" xml:space="preserve">Deadline</text>
|
|
34
|
+
<text x="94.2" y="205" fill="#d0d0d0" xml:space="preserve">3000 ms ▾</text>
|
|
35
|
+
<text x="187.8" y="205" fill="#7c7c7c" xml:space="preserve">then keep the model</text>
|
|
36
|
+
<text x="24.0" y="224" fill="#d0d0d0" xml:space="preserve">Health active · 0 recent failures</text>
|
|
37
|
+
<text x="24.0" y="243" fill="#7c7c7c" xml:space="preserve">Sends prompt + 6 recent turns → api.cloudflare.com</text>
|
|
38
|
+
<text x="24.0" y="262" fill="#d0d0d0" xml:space="preserve">Credentials </text>
|
|
39
|
+
<text x="125.4" y="262" fill="#d0d0d0" xml:space="preserve">[ Edit ]</text>
|
|
40
|
+
<text x="187.8" y="262" fill="#7c7c7c" xml:space="preserve"> opens /plugin configure</text>
|
|
41
|
+
<text x="24.0" y="281" fill="#7c7c7c" xml:space="preserve"> Jev: API key · Clef, Clef Flash: API token, account ID</text>
|
|
42
|
+
<text x="24.0" y="319" fill="#87d787" xml:space="preserve">Saved: classifier Clef → Clef Flash. Applies from the next turn. </text>
|
|
43
|
+
<text x="538.8" y="319" fill="#d0d0d0" xml:space="preserve">[ Undo ]</text>
|
|
44
|
+
<text x="24.0" y="338" fill="#d0d0d0" xml:space="preserve">[ Close ]</text>
|
|
45
|
+
</svg>
|
package/docs/router-pane-now.svg
CHANGED
|
@@ -10,12 +10,13 @@
|
|
|
10
10
|
<text x="24.0" y="34" fill="#5fafd7" font-weight="700" xml:space="preserve">ROUTER · Auto</text>
|
|
11
11
|
<text x="148.8" y="34" fill="#87d787" xml:space="preserve">Jev ready · 347 ms</text>
|
|
12
12
|
<text x="24.0" y="53" fill="#87afff" font-weight="700" xml:space="preserve">[ Auto ]</text>
|
|
13
|
-
<text x="94.2" y="53" fill="#d0d0d0" xml:space="preserve">[ Manual
|
|
13
|
+
<text x="94.2" y="53" fill="#d0d0d0" xml:space="preserve">[ Manual ]</text>
|
|
14
|
+
<text x="172.2" y="53" fill="#7c7c7c" xml:space="preserve"> Manual keeps the /model choice</text>
|
|
14
15
|
<text x="24.0" y="72" fill="#87afff" font-weight="700" xml:space="preserve">[ Now ]</text>
|
|
15
|
-
<text x="86.4" y="72" fill="#d0d0d0" xml:space="preserve">[
|
|
16
|
-
<text x="
|
|
17
|
-
<text x="
|
|
18
|
-
<text x="
|
|
16
|
+
<text x="86.4" y="72" fill="#d0d0d0" xml:space="preserve">[ Routing ]</text>
|
|
17
|
+
<text x="180.0" y="72" fill="#d0d0d0" xml:space="preserve">[ Classifier ]</text>
|
|
18
|
+
<text x="297.0" y="72" fill="#d0d0d0" xml:space="preserve">[ Usage ]</text>
|
|
19
|
+
<text x="375.0" y="72" fill="#d0d0d0" xml:space="preserve">[ ? ]</text>
|
|
19
20
|
<text x="24.0" y="110" fill="#d0d0d0" xml:space="preserve">Now </text>
|
|
20
21
|
<text x="78.6" y="110" fill="#e0708a" font-weight="700" xml:space="preserve">▌high </text>
|
|
21
22
|
<text x="133.2" y="110" fill="#d0d0d0" xml:space="preserve">Opus 5.5 · xhigh</text>
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 594 686" role="img" aria-labelledby="title desc">
|
|
2
|
+
<title id="title">Router pane, Routing tab</title>
|
|
3
|
+
<desc id="desc">Model and effort per tier with prices and windows, the baseline tier, how the policy prices each step up, the policy controls, and the unsaved router.json change with Save and Discard.</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="594" height="686" rx="8" fill="#1c1c1c"/>
|
|
9
|
+
<rect x="10" y="10" width="574" height="666" rx="6" fill="none" stroke="#3f5f8f"/>
|
|
10
|
+
<text x="24.0" y="34" fill="#5fafd7" font-weight="700" xml:space="preserve">ROUTER · Auto</text>
|
|
11
|
+
<text x="148.8" y="34" fill="#87d787" xml:space="preserve">Jev ready · 347 ms</text>
|
|
12
|
+
<text x="24.0" y="53" fill="#87afff" font-weight="700" xml:space="preserve">[ Auto ]</text>
|
|
13
|
+
<text x="94.2" y="53" fill="#d0d0d0" xml:space="preserve">[ Manual ]</text>
|
|
14
|
+
<text x="172.2" y="53" fill="#7c7c7c" xml:space="preserve"> Manual keeps the /model choice</text>
|
|
15
|
+
<text x="24.0" y="72" fill="#d0d0d0" xml:space="preserve">[ Now ]</text>
|
|
16
|
+
<text x="86.4" y="72" fill="#87afff" font-weight="700" xml:space="preserve">[ Routing ● ]</text>
|
|
17
|
+
<text x="195.6" y="72" fill="#d0d0d0" xml:space="preserve">[ Classifier ]</text>
|
|
18
|
+
<text x="312.6" y="72" fill="#d0d0d0" xml:space="preserve">[ Usage ]</text>
|
|
19
|
+
<text x="390.6" y="72" fill="#d0d0d0" xml:space="preserve">[ ? ]</text>
|
|
20
|
+
<text x="24.0" y="110" fill="#5fafd7" font-weight="700" xml:space="preserve">ROUTES</text>
|
|
21
|
+
<text x="70.8" y="110" fill="#7c7c7c" xml:space="preserve"> · applies next turn · edit, then Save</text>
|
|
22
|
+
<text x="24.0" y="129" fill="#7c7c7c" xml:space="preserve">tier model effort $/M in · out window</text>
|
|
23
|
+
<text x="24.0" y="148" fill="#e0708a" font-weight="700" xml:space="preserve">high</text>
|
|
24
|
+
<text x="86.4" y="148" fill="#d0d0d0" xml:space="preserve">Opus 5.5 ▾</text>
|
|
25
|
+
<text x="195.6" y="148" fill="#d0d0d0" xml:space="preserve">xhigh ▾</text>
|
|
26
|
+
<text x="304.8" y="148" fill="#d0d0d0" xml:space="preserve">4 · 20</text>
|
|
27
|
+
<text x="414.0" y="148" fill="#d0d0d0" xml:space="preserve">1M</text>
|
|
28
|
+
<text x="24.0" y="167" fill="#d7af5f" font-weight="700" xml:space="preserve">medium</text>
|
|
29
|
+
<text x="86.4" y="167" fill="#d0d0d0" xml:space="preserve">Sonnet 5.5 ▾</text>
|
|
30
|
+
<text x="195.6" y="167" fill="#d0d0d0" xml:space="preserve">xhigh ▾</text>
|
|
31
|
+
<text x="289.2" y="167" fill="#d7af5f" xml:space="preserve">●</text>
|
|
32
|
+
<text x="304.8" y="167" fill="#d0d0d0" xml:space="preserve">2 · 10</text>
|
|
33
|
+
<text x="414.0" y="167" fill="#d0d0d0" xml:space="preserve">1M</text>
|
|
34
|
+
<text x="24.0" y="186" fill="#5f9fe0" font-weight="700" xml:space="preserve">low</text>
|
|
35
|
+
<text x="86.4" y="186" fill="#d0d0d0" xml:space="preserve">Sonnet 5.5 ▾</text>
|
|
36
|
+
<text x="195.6" y="186" fill="#d0d0d0" xml:space="preserve">session ▾</text>
|
|
37
|
+
<text x="304.8" y="186" fill="#d0d0d0" xml:space="preserve">2 · 10</text>
|
|
38
|
+
<text x="414.0" y="186" fill="#d0d0d0" xml:space="preserve">1M</text>
|
|
39
|
+
<text x="24.0" y="205" fill="#5fd7af" font-weight="700" xml:space="preserve">micro</text>
|
|
40
|
+
<text x="86.4" y="205" fill="#d0d0d0" xml:space="preserve">Haiku 4.5 ▾</text>
|
|
41
|
+
<text x="195.6" y="205" fill="#7c7c7c" xml:space="preserve">none</text>
|
|
42
|
+
<text x="304.8" y="205" fill="#d0d0d0" xml:space="preserve">1 · 5</text>
|
|
43
|
+
<text x="414.0" y="205" fill="#d0d0d0" xml:space="preserve">200K</text>
|
|
44
|
+
<text x="24.0" y="224" fill="#d0d0d0" xml:space="preserve">Baseline tier: low ▾</text>
|
|
45
|
+
<text x="304.8" y="224" fill="#7c7c7c" xml:space="preserve">start here, fall back here</text>
|
|
46
|
+
<text x="24.0" y="262" fill="#5fafd7" font-weight="700" xml:space="preserve">SWITCH COST · from these routes</text>
|
|
47
|
+
<text x="24.0" y="281" fill="#7c7c7c" xml:space="preserve">· </text>
|
|
48
|
+
<text x="39.6" y="281" fill="#d0d0d0" xml:space="preserve">medium → high </text>
|
|
49
|
+
<text x="164.4" y="281" fill="#d0d0d0" xml:space="preserve">model change: priced as a cold cache write</text>
|
|
50
|
+
<text x="24.0" y="300" fill="#7c7c7c" xml:space="preserve">· </text>
|
|
51
|
+
<text x="39.6" y="300" fill="#d0d0d0" xml:space="preserve">low → medium </text>
|
|
52
|
+
<text x="164.4" y="300" fill="#d0d0d0" xml:space="preserve">same model, new effort: priced as a new cache</text>
|
|
53
|
+
<text x="24.0" y="319" fill="#7c7c7c" xml:space="preserve">· </text>
|
|
54
|
+
<text x="39.6" y="319" fill="#d0d0d0" xml:space="preserve">micro → low </text>
|
|
55
|
+
<text x="164.4" y="319" fill="#d0d0d0" xml:space="preserve">model change: priced as a cold cache write</text>
|
|
56
|
+
<text x="24.0" y="338" fill="#d0d0d0" xml:space="preserve">[ Reset routes to defaults ]</text>
|
|
57
|
+
<text x="24.0" y="357" fill="#7c7c7c" xml:space="preserve">A new model ID needs router.json → models: price, window, efforts.</text>
|
|
58
|
+
<text x="24.0" y="395" fill="#5fafd7" font-weight="700" xml:space="preserve">POLICY</text>
|
|
59
|
+
<text x="70.8" y="395" fill="#7c7c7c" xml:space="preserve"> · applies next turn · edit, then Save</text>
|
|
60
|
+
<text x="24.0" y="414" fill="#d0d0d0" xml:space="preserve">Votes to go down</text>
|
|
61
|
+
<text x="180.0" y="414" fill="#d0d0d0" xml:space="preserve">2 ▾</text>
|
|
62
|
+
<text x="289.2" y="414" fill="#7c7c7c" xml:space="preserve">agreeing turns before cheaper</text>
|
|
63
|
+
<text x="24.0" y="433" fill="#d0d0d0" xml:space="preserve">Payback horizon</text>
|
|
64
|
+
<text x="180.0" y="433" fill="#d0d0d0" xml:space="preserve">5 turns ▾</text>
|
|
65
|
+
<text x="289.2" y="433" fill="#7c7c7c" xml:space="preserve">a switch repays its cache</text>
|
|
66
|
+
<text x="24.0" y="452" fill="#d0d0d0" xml:space="preserve">Credits cap</text>
|
|
67
|
+
<text x="180.0" y="452" fill="#d0d0d0" xml:space="preserve">$2.00 ▾</text>
|
|
68
|
+
<text x="289.2" y="452" fill="#7c7c7c" xml:space="preserve">max cold write on credits</text>
|
|
69
|
+
<text x="24.0" y="471" fill="#d0d0d0" xml:space="preserve">[ Reset policy to defaults ]</text>
|
|
70
|
+
<text x="24.0" y="509" fill="#5fafd7" font-weight="700" xml:space="preserve">CONFIG</text>
|
|
71
|
+
<text x="24.0" y="528" fill="#d0d0d0" xml:space="preserve">File ~/.claude/router.json </text>
|
|
72
|
+
<text x="273.6" y="528" fill="#d0d0d0" xml:space="preserve">[ copy ]</text>
|
|
73
|
+
<text x="24.0" y="547" fill="#7c7c7c" xml:space="preserve">Main conversation only. Subagents keep their own model.</text>
|
|
74
|
+
<text x="24.0" y="585" fill="#7c7c7c" xml:space="preserve">router.json changes:</text>
|
|
75
|
+
<text x="24.0" y="604" fill="#e06c6c" xml:space="preserve">- routes.medium Opus 5.5 · medium</text>
|
|
76
|
+
<text x="24.0" y="623" fill="#87d787" xml:space="preserve">+ routes.medium Sonnet 5.5 · xhigh</text>
|
|
77
|
+
<text x="24.0" y="642" fill="#d7af5f" xml:space="preserve">● 1 unsaved routing change </text>
|
|
78
|
+
<text x="242.4" y="642" fill="#87afff" font-weight="700" xml:space="preserve">[ Save ]</text>
|
|
79
|
+
<text x="312.6" y="642" fill="#d0d0d0" xml:space="preserve">[ Discard ]</text>
|
|
80
|
+
<text x="24.0" y="661" fill="#d0d0d0" xml:space="preserve">[ Close ]</text>
|
|
81
|
+
</svg>
|
package/docs/user-guide.md
CHANGED
|
@@ -18,14 +18,17 @@ claude --model claude-sonnet-5-5
|
|
|
18
18
|
In Claude Code:
|
|
19
19
|
|
|
20
20
|
1. Run `/plugin configure router`.
|
|
21
|
-
2.
|
|
22
|
-
|
|
21
|
+
2. Enter the credentials of the classifier you use, and save them:
|
|
22
|
+
- **Jev** (the default): the Jev API key from typesafe.ai.
|
|
23
|
+
- **Clef** or **Clef Flash** on Cloudflare Workers AI: the Cloudflare API token and the Cloudflare account ID. One token covers both models.
|
|
24
|
+
3. To use Clef or Clef Flash, open the pane's **Classifier** tab and select its row. See [Choose the classifier](#choose-the-classifier).
|
|
25
|
+
4. Check the band above the prompt: `▂▄▆█ Auto · ready`. On another model the session starts in Manual; run `/router auto` to route.
|
|
23
26
|
|
|
24
|
-
|
|
27
|
+
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.
|
|
25
28
|
|
|
26
29
|
## Read the status band
|
|
27
30
|
|
|
28
|
-
Router draws one line above the prompt. The line ends with a **Router** button that opens the pane. When the band is narrow, the less important parts drop first: classifier figures, then context and cache, then the reason. The tier and model always stay.
|
|
31
|
+
Router draws one line above the prompt. The line ends with a **Router** button that opens the pane. When the band is narrow, the less important parts drop first: classifier figures, then context and cache, then the reason. The tier and model always stay, except behind a classifier warning: the warning and its **Set up** button come first, and the route gives way to them.
|
|
29
32
|
|
|
30
33
|

|
|
31
34
|
|
|
@@ -34,7 +37,7 @@ Read the first line of the picture from left to right:
|
|
|
34
37
|
- **Tier meter** `▂▄▆█`: one bar per tier, lit up to the current tier in its color, like signal strength.
|
|
35
38
|
- **Tier and model**: the route for this turn. **fallback** means Claude Code answered with another model.
|
|
36
39
|
- **Reason**: one or two words with a direction, such as `↑ jump`, `↓ downgrade`, `= fits`, or `… waiting to go down`.
|
|
37
|
-
- **Classifier support**: what Jev gave the switch against the bar the policy required.
|
|
40
|
+
- **Classifier support**: what the active classifier, such as Jev or Clef Flash, gave the switch against the bar the policy required.
|
|
38
41
|
- **ctx** and **cache**: context use and cache reuse on the last reply. They turn yellow at 60% context and red at 80%.
|
|
39
42
|
|
|
40
43
|
| Band shows | Meaning |
|
|
@@ -42,7 +45,8 @@ Read the first line of the picture from left to right:
|
|
|
42
45
|
| `Auto · ready` | Auto mode is ready for a new turn. |
|
|
43
46
|
| `choosing for this turn…` | The classifier and local policy are running. The spinner says `Choosing model`. |
|
|
44
47
|
| `⏵ next turn: high ✕` | A pin is set. **✕** cancels it. |
|
|
45
|
-
| `⚠ Jev
|
|
48
|
+
| `⚠ Jev: no API key · keeping model` | The active classifier lacks a setting. **Set up** opens the secure plugin dialog. |
|
|
49
|
+
| `⚠ Clef: no account ID · keeping model` | Clef has its API token but no Cloudflare account ID. **Set up** opens the dialog. |
|
|
46
50
|
| `⚠ Jev timed out · keeping model` | The classifier failed: timed out, unreachable, rejected the key, or paused. |
|
|
47
51
|
| `○ Router off · keeping …` | Manual mode. **Auto** resumes routing. The footer also shows `router off`. |
|
|
48
52
|
| `✕ Router unavailable` | Nothing routes: an old Claude Code or leftover v0.8 settings. **Fix** opens the pane. |
|
|
@@ -62,32 +66,41 @@ Run `/router` or select **Router** above the prompt. Without a UI surface, as in
|
|
|
62
66
|
|
|
63
67
|
The **Now** tab answers "what runs next turn, and why". The ladder lists the tiers from strongest to cheapest with the route each one uses. The bar is the support the classifier gave that tier on the last turn. The line under the ladder compares the support for a switch with the bar the policy required and shows the estimated switch tax. **pin** forces that tier for the next turn only.
|
|
64
68
|
|
|
65
|
-

|
|
66
70
|
|
|
67
|
-
The **
|
|
71
|
+
The **Routing** tab edits the routes 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 one `router.json` line that **Save** will write. [Edit routes and policy](#edit-routes-and-policy) explains the controls.
|
|
68
72
|
|
|
69
|
-
| Tab
|
|
70
|
-
|
|
|
71
|
-
| 1 Now
|
|
72
|
-
| 2
|
|
73
|
-
| 3
|
|
74
|
-
| 4 Usage
|
|
73
|
+
| Tab | What it shows |
|
|
74
|
+
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
75
|
+
| 1 Now | The current tier, model, and reason; the classifier's support for each tier with a **pin** button; the last 30 replies by tier; context and cache. |
|
|
76
|
+
| 2 Routing | The model and effort for each tier, the baseline tier, the cache cost of each step up; downgrade votes, payback horizon, and credits cap; the `router.json` path. |
|
|
77
|
+
| 3 Classifier | The classifier rows with their credentials state, the active classifier's deadline and health, and the credentials each classifier needs. |
|
|
78
|
+
| 4 Usage | Claude-reported cost, context and cache detail, input per reply, quota, and configured-price estimates. |
|
|
75
79
|
|
|
76
|
-
**Auto** and **Manual
|
|
80
|
+
**Auto** and **Manual** stay at the top of every tab. **?** shows what the estimates leave out.
|
|
81
|
+
|
|
82
|
+
### Save and undo changes
|
|
83
|
+
|
|
84
|
+
The two settings tabs follow one rule each, and the section captions say which:
|
|
85
|
+
|
|
86
|
+
- **Routing**: edit as a set, then save. Changes stay a draft until **Save** (`s`). **Discard** (`d`) drops them. The draft stays when you change tab or close the pane: the tab reads **Routing ●**, and every tab shows the `router.json` lines that **Save** will write, with **Save** and **Discard**. A new session drops the draft.
|
|
87
|
+
- **Classifier**: a row or a deadline is written to `router.json` when you select it.
|
|
88
|
+
|
|
89
|
+
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.
|
|
77
90
|
|
|
78
91
|
### Understand usage and estimates
|
|
79
92
|
|
|
80
93
|
- **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.
|
|
81
94
|
- **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.
|
|
82
95
|
- **Cache** reuse is cache-read tokens divided by the last response's input counters.
|
|
83
|
-
- **
|
|
96
|
+
- **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.
|
|
84
97
|
- **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 in Manual mode.
|
|
85
98
|
- **Input per reply** scales the last 30 input sizes from the lowest to the highest reading. It is a scale comparison, not a forecast.
|
|
86
99
|
- **Cache read benefit** is a configured-price estimate for cached reads before write costs. It is not a measured saving.
|
|
87
100
|
- **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.
|
|
88
101
|
- **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.
|
|
89
102
|
|
|
90
|
-
There is no router-side spend or savings ledger. The pane does not include
|
|
103
|
+
There is no router-side spend or savings ledger. The pane does not include classifier charges. Claude's native `/cost` is the source for its reported API cost.
|
|
91
104
|
|
|
92
105
|
## Change routing
|
|
93
106
|
|
|
@@ -98,31 +111,54 @@ There is no router-side spend or savings ledger. The pane does not include Jev c
|
|
|
98
111
|
| `/router off` | Enter Manual mode and preserve Claude's selected model. |
|
|
99
112
|
| `/router pin <micro\|low\|medium\|high>` | Pin the next turn and its tool continuations. Auto must already be enabled. |
|
|
100
113
|
| `/model <name>` | Select a model and enter Manual mode. Use `/router auto` to resume. |
|
|
101
|
-
| **Auto** / **Manual
|
|
114
|
+
| **Auto** / **Manual** | The same as `/router auto` and `/router off`. |
|
|
102
115
|
| **pin** on the Now tab | Pin that tier for the next turn. Auto must already be enabled. |
|
|
103
116
|
|
|
104
117
|
A pin does not change the next turn after the pinned turn finishes. A fresh session on the baseline model starts in Auto. A fresh session on another model starts in Manual. `/clear` starts the new session in Auto. Resuming a saved session restores its saved Auto or Manual mode.
|
|
105
118
|
|
|
106
|
-
## Edit
|
|
119
|
+
## Edit routes and policy
|
|
107
120
|
|
|
108
|
-
On the **
|
|
121
|
+
On the **Routing** tab, pick a model and an effort for any tier. The model list comes from the aliases in `router.json` `models`, limited by the `availableModels` setting. `session` keeps the effort Claude Code sends. A model without effort levels, such as Haiku, shows `none`.
|
|
109
122
|
|
|
110
|
-
Changed tiers show **●**.
|
|
123
|
+
Changed tiers show **●**. **Reset routes to defaults** (`r`) loads the built-in routes into the draft; **Save** then removes your route overrides from `router.json`.
|
|
111
124
|
|
|
112
125
|
**Switch cost** reads the draft from the bottom tier up and shows how the policy prices each step. A model change is priced as a cold cache write. An effort change on the same model is also priced as a new messages cache; whether the API actually keeps the cache across an effort change is not measured. Two identical tiers make that step change nothing.
|
|
113
126
|
|
|
114
127
|
A new model ID needs an entry in `router.json` `models` with its price, context window, and effort levels. See [Configuration](configuration.md).
|
|
115
128
|
|
|
116
|
-
|
|
129
|
+
### Tune future decisions
|
|
117
130
|
|
|
118
|
-
|
|
131
|
+
Under **Policy** on the same tab, pick the values. One **Save** writes them with any route changes:
|
|
119
132
|
|
|
120
|
-
- **Jev deadline:** 500, 1,000, 1,500, or 3,000 ms for the total advice attempt, including any retry.
|
|
121
133
|
- **Votes to go down:** 1, 2, or 3 consecutive votes before a cheaper tier.
|
|
122
134
|
- **Payback horizon:** 1, 3, 5, or 10 later turns used by the downgrade estimate.
|
|
123
135
|
- **Credits cap:** $0.50, $1, $2, or $5 for an estimated cold cache write on a `credits` model.
|
|
124
136
|
|
|
125
|
-
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.
|
|
137
|
+
**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.
|
|
138
|
+
|
|
139
|
+
## Choose the classifier
|
|
140
|
+
|
|
141
|
+
Router asks one classifier per turn. Three are built in:
|
|
142
|
+
|
|
143
|
+
| Classifier | Service | Credentials | Deadline |
|
|
144
|
+
| ---------- | -------------------------- | ---------------------------------------------- | -------: |
|
|
145
|
+
| Jev | typesafe.ai | Jev API key | 1,500 ms |
|
|
146
|
+
| Clef | Cloudflare Workers AI, 27B | Cloudflare API token and Cloudflare account ID | 3,000 ms |
|
|
147
|
+
| Clef Flash | Cloudflare Workers AI, 9B | Cloudflare API token and Cloudflare account ID | 3,000 ms |
|
|
148
|
+
|
|
149
|
+

|
|
150
|
+
|
|
151
|
+
You can save credentials for all of them; only the active one is asked. The **Classifier** tab has one row per classifier: `◉` marks the active one, followed by its service and whether its credentials are complete. A row that lacks one names it, such as `○ no API token`, and has its own **Set up** button.
|
|
152
|
+
|
|
153
|
+
Select a row to switch. The choice is written to `router.json` at once and applies from the next turn. **Undo** in the status bar returns to the previous classifier. A turn that is already being classified finishes with the classifier it started with. The new classifier starts with a clean failure count.
|
|
154
|
+
|
|
155
|
+
- **Deadline:** 500, 1,000, 1,500, or 3,000 ms for the active classifier's total advice attempt, including any retry. Each classifier keeps its own deadline, saved at once, with **Undo**.
|
|
156
|
+
- **Health** shows recent failures or a pause. **Sends** names the service that receives prompt text.
|
|
157
|
+
- **Credentials** lists what each classifier needs, such as `Jev: API key · Clef, Clef Flash: API token, account ID`. **Edit** opens Claude Code's secure plugin configuration, where you enter them.
|
|
158
|
+
|
|
159
|
+
**Sends** names the service that receives the prompt and recent dialogue. With Clef or Clef Flash that is Cloudflare, not typesafe.ai. Give the Cloudflare token Workers AI permissions only.
|
|
160
|
+
|
|
161
|
+
The routing policy thresholds were tuned against Jev's probabilities. Clef's probabilities have not been compared with Jev's, so the same prompt can switch tiers at a different point. Watch **Classifier support** for a few sessions before you rely on a new classifier.
|
|
126
162
|
|
|
127
163
|
## Move from v0.8 gateway setup
|
|
128
164
|
|
|
@@ -143,15 +179,16 @@ To stop routing for a session, run `/router off`. To stop loading the Mod, run `
|
|
|
143
179
|
|
|
144
180
|
## Troubleshooting
|
|
145
181
|
|
|
146
|
-
| Symptom
|
|
147
|
-
|
|
|
148
|
-
| Status says
|
|
149
|
-
|
|
|
150
|
-
|
|
|
151
|
-
|
|
|
152
|
-
| Router
|
|
153
|
-
|
|
|
154
|
-
|
|
|
155
|
-
|
|
|
182
|
+
| Symptom | Cause | Fix |
|
|
183
|
+
| ------------------------------------------ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
184
|
+
| 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. |
|
|
185
|
+
| 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. |
|
|
186
|
+
| 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. |
|
|
187
|
+
| `/model` changed but routing stopped | Choosing a model enters Manual mode. | Run `/router auto` to resume automatic routing. |
|
|
188
|
+
| 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). |
|
|
189
|
+
| 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). |
|
|
190
|
+
| 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. |
|
|
191
|
+
| Router controls are unavailable | Claude Code is older than 2.1.289. | Update Claude Code. |
|
|
192
|
+
| 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. |
|
|
156
193
|
|
|
157
194
|
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).
|