@alexeiled/claude-router 0.7.2 → 1.0.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.
Files changed (44) hide show
  1. package/.claude-plugin/plugin.json +10 -6
  2. package/CHANGELOG.md +43 -0
  3. package/README.md +51 -100
  4. package/docs/architecture.md +55 -414
  5. package/docs/configuration.md +86 -182
  6. package/docs/evaluation.md +62 -81
  7. package/docs/native-router.md +79 -0
  8. package/docs/user-guide.md +103 -172
  9. package/hooks/hooks.json +1 -26
  10. package/hooks/native-router.mjs +635 -0
  11. package/lib/config.mjs +24 -60
  12. package/lib/{facts.mjs → facts-pure.mjs} +2 -23
  13. package/lib/{jev.mjs → jev-contract.mjs} +17 -38
  14. package/lib/native-cost.mjs +88 -0
  15. package/lib/native-display.mjs +75 -0
  16. package/lib/native-jev.mjs +125 -0
  17. package/lib/native-panel.mjs +150 -0
  18. package/lib/native-router.mjs +216 -0
  19. package/lib/policy.mjs +17 -21
  20. package/package.json +9 -8
  21. package/scripts/migrate-config.mjs +57 -0
  22. package/types/index.d.ts +95 -0
  23. package/lib/cost.mjs +0 -93
  24. package/lib/gateway.mjs +0 -221
  25. package/lib/idle.mjs +0 -41
  26. package/lib/rewrite.mjs +0 -130
  27. package/lib/router.mjs +0 -276
  28. package/lib/runtime.mjs +0 -78
  29. package/lib/sse.mjs +0 -57
  30. package/lib/status.mjs +0 -152
  31. package/lib/store.mjs +0 -76
  32. package/scripts/ensure-gateway.mjs +0 -143
  33. package/scripts/gateway.mjs +0 -81
  34. package/scripts/git-hooks/pre-commit +0 -27
  35. package/scripts/git-hooks/pre-push +0 -34
  36. package/scripts/status.mjs +0 -20
  37. package/scripts/statusline.mjs +0 -45
  38. package/scripts/transcript-models.sh +0 -4
  39. package/skills/high/SKILL.md +0 -9
  40. package/skills/low/SKILL.md +0 -7
  41. package/skills/medium/SKILL.md +0 -8
  42. package/skills/micro/SKILL.md +0 -7
  43. package/skills/setup/SKILL.md +0 -31
  44. package/skills/status/SKILL.md +0 -12
@@ -1,202 +1,133 @@
1
1
  # User guide
2
2
 
3
- After the [install](../README.md#install), work in Claude Code as usual. The
4
- router selects the model and the effort for each turn. This guide shows how
5
- to read what it does, and how to control it.
6
-
7
- - [Check the setup](#check-the-setup)
8
- - [A session, step by step](#a-session-step-by-step)
9
- - [Read the status line](#read-the-status-line)
10
- - [Read `/router:status`](#read-routerstatus)
11
- - [Pin a tier](#pin-a-tier)
12
- - [Read the decision log](#read-the-decision-log)
13
- - [Update](#update)
14
- - [Stop using the router](#stop-using-the-router)
15
- - [Troubleshooting](#troubleshooting)
16
-
17
- ## Check the setup
18
-
19
- 1. Start Claude Code. `/model` shows `Jev Router (auto)` as the model.
20
- 2. Send a prompt. If setup added the status line, it shows the route, for
21
- example `jev-router ▸ sonnet-5 · high · same-tier`.
22
- 3. Run `/router:status`. It shows `Jev routing: active.`
23
-
24
- If a step fails, read [Troubleshooting](#troubleshooting).
25
-
26
- ## A session, step by step
27
-
28
- An example of four turns. Each box is one prompt with its route and reason.
29
-
30
- ```mermaid
31
- flowchart LR
32
- T1["<b>1</b> · design a cache layer<br/>Opus · xhigh<br/><i>jump</i>"]
33
- T2["<b>2</b> · yes, go on<br/>Opus · xhigh<br/><i>continuation</i>"]
34
- T3["<b>3</b> · rename foo to bar<br/>Opus · xhigh<br/><i>downgrade-pending</i>"]
35
- T4["<b>4</b> · fix the typo<br/>Sonnet<br/><i>downgrade</i>"]
36
- T1 --> T2 --> T3 --> T4
37
-
38
- classDef opus fill:#0d366b,stroke:#0d366b,color:#ffffff
39
- classDef sonnet fill:#cde2fb,stroke:#2a78d6,color:#0b0b0b
40
- class T1,T2,T3 opus
41
- class T4 sonnet
42
- ```
3
+ ## Start a session
43
4
 
44
- 1. A confident vote for hard work goes up two tiers at once.
45
- 2. A prompt that continues the task keeps the route.
46
- 3. One vote for a lower tier is not enough. The route stays.
47
- 4. The second vote in a row moves the route down.
5
+ Install the plugin from its marketplace, or load a checkout with `--plugin-dir /path/to/claude-router`:
48
6
 
49
- The tool calls in a turn keep the route of the turn, so the cache stays warm.
50
- The [README](../README.md#how-jev-selects-a-tier) gives all the rules.
7
+ ```sh
8
+ claude plugin marketplace add alexei-led/claude-router
9
+ claude plugin install router@alexei-led-claude-router
10
+ ```
51
11
 
52
- ## Read the status line
12
+ Start with the full baseline model so Auto mode has a known starting point:
53
13
 
54
- ```text
55
- jev-router ▸ opus-5-5 · xhigh · upgrade
56
- │ │ └─ reason for the route
57
- │ └─ effort
58
- └─ model of the last turn
14
+ ```sh
15
+ claude --model claude-sonnet-5-5
59
16
  ```
60
17
 
61
- | Line | Meaning |
62
- | ------------------------------------------------ | --------------------------------------------------- |
63
- | `jev-router ▸ …` | The route of the last turn in this session. |
64
- | `jev-router: no turn yet` | This session has no routed turn. |
65
- | `router: gateway off, the next prompt starts it` | The gateway stopped after idle time, or it crashed. |
66
-
67
- The line changes after each message.
68
-
69
- **The route changed:**
70
-
71
- | Reason | Meaning |
72
- | ------------- | ---------------------------------------------------------------------------- |
73
- | `upgrade` | Two votes in a row for a higher tier, with enough confidence. |
74
- | `jump` | One vote confident enough to go up two tiers. |
75
- | `downgrade` | Two votes in a row for a lower tier, with enough confidence. |
76
- | `escalation` | The same error came back after an edit. The route went up one tier. |
77
- | `context-fit` | The selected model cannot hold the context. A larger window serves the turn. |
78
- | `cash-gate` | The cold-write guard stopped a switch to a `credits` model. |
79
-
80
- **The route stayed:**
81
-
82
- | Reason | Meaning |
83
- | ------------------- | ------------------------------------------------------------------- |
84
- | `same-tier` | Jev agreed with the current tier. |
85
- | `continuation` | The prompt continues the task. |
86
- | `upgrade-pending` | One vote for a higher tier. The next vote decides. |
87
- | `downgrade-pending` | One vote for a lower tier. The next vote decides. |
88
- | `hold` | The route stays up for two turns after an escalation. |
89
- | `uncertain` | Jev did not select a tier. |
90
- | `no-advice` | No Jev answer: no key, an error, a pause, or a prompt without text. |
91
-
92
- `forced` means that the gateway was started with `--force-tier`.
93
-
94
- ## Read `/router:status`
95
-
96
- `/router:status` shows the gateway, the routes and the last turn. For a
97
- vote, it also shows the numbers:
98
-
99
- ```text
100
- Router v0.7.0, gateway: http://127.0.0.1:43170, alias `jev-router`.
101
- Jev routing: active.
102
- Default tier: low.
103
- …
104
- Last turn: low → claude-sonnet-5 at high, reason upgrade-pending, context 84210 tokens, cache reads 83904.
105
- Why: Jev asked for a higher tier; the route stays until the votes and the mass are enough.
106
- Estimate: upgrade mass 0.78 against a bar of 0.84, switching tax $0.66 at list prices, 1 vote(s) in a row, cache: candidate unknown, current warm.
107
- ```
18
+ In Claude Code:
108
19
 
109
- - **Upgrade mass** is the Jev confidence in a higher tier. It must reach the
110
- bar.
111
- - **The bar** grows with the switching tax: the cost to write the context
112
- into a cold cache. Here Opus has no warm cache.
113
- - **Cache** is `warm`, `expired` or `unknown`. `unknown` means no response
114
- for that cache since the session started or the conversation got shorter.
115
- - **Dollars** are list prices. On a subscription plan, they show the relative
116
- cost only.
20
+ 1. Run `/plugin configure router`.
21
+ 2. Select the Jev API key option, enter the key, and save it.
22
+ 3. Run `/router auto`.
117
23
 
118
- ## Pin a tier
24
+ The key is stored as a sensitive plugin option. Do not paste it into a model conversation. The [configuration guide](configuration.md) covers optional settings and the old v0.8 migration.
119
25
 
120
- To run one turn on a fixed tier, type the tier skill before the prompt:
26
+ ## Read the status band
121
27
 
122
- ```text
123
- /router:high redesign the auth flow
124
- /router:micro rename foo to bar in this file
125
- ```
28
+ The Mod adds a band above the prompt and a **Router** button. It reports whether routing is ready, choosing a route, in Manual mode, pinned, degraded, or unavailable. After a reply, it shows the actual model, effort, and reason.
126
29
 
127
- The status line shows the reason `pinned`. Tool calls in that turn stay on the
128
- tier; the next prompt goes back to Jev.
30
+ | Status | Meaning |
31
+ | ----------------------------------------------- | ----------------------------------------------------------------------- |
32
+ | `Auto · ready` | Auto mode is ready for a new turn. |
33
+ | `choosing for this turn…` | Jev advice and local policy are in progress. |
34
+ | `key not set · keeping …` | No Jev key is available. The current model stays active. |
35
+ | `Jev timeout`, `Jev auth`, or `Jev unreachable` | Jev failed. The current model stays active. |
36
+ | `Jev paused until …` | Three launched failures opened a 60-second breaker. |
37
+ | `context unknown · keeping native model` | The router could not verify that a smaller window has enough room. |
38
+ | `native fallback` | Claude Code substituted another available model for the selected route. |
39
+ | `requires Claude Code 2.1.289 or newer` | This version cannot run the router controls. |
129
40
 
130
- `/model <name>` also works, but it stops the routing for the rest of the
131
- session.
41
+ Tool continuations do not trigger another classification. Subagent choices remain unchanged.
132
42
 
133
- ## Read the decision log
43
+ ## Open the router pane
134
44
 
135
- The gateway writes one JSON line for each routed request to
136
- `~/.claude/plugins/data/router-alexei-led-claude-router/decisions.jsonl`. The
137
- log has no prompt text.
45
+ Run `/router` or select **Router** above the prompt. In a terminal without a UI surface, `/router` prints a short status instead. `/router status` always prints the short status.
138
46
 
139
- | Field | Content |
140
- | -------------- | ---------------------------------------------------------------------------------- |
141
- | `tier` | The tier of the request. |
142
- | `model`, `effort` | The model id and the effort that the gateway sent. `effort` is `null` for a model without effort. |
143
- | `reason` | The rule that decided. Tool calls show `tool-continuation`. `error`: routing failed and the default tier served. |
144
- | `advice` | The Jev probabilities for each tier, and for "continues the task". |
145
- | `estimate` | The numbers of a vote: confidence, bar, switching tax, cache state. |
146
- | `shadow` | The cost of the Jev choice against the current route. The downgrade tax uses the same arithmetic. |
147
- | `observed` | The usage of the response: model, effort, context tokens, cache reads, output. |
148
- | `failed` | Anthropic answered a routed turn with an error: status, tier, model, effort. |
149
- | `historyBreak` | A compaction or a rewind. The votes and the cache estimates reset. |
150
- | `cacheReset` | The context shrank by more than 20%. The cache estimates reset. |
47
+ The pane groups information by purpose:
151
48
 
152
- Two useful queries:
49
+ | Pane section | What it shows |
50
+ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
51
+ | Model routing | Auto or Manual, last actual reply, requested model, effort, route reason, and any next-turn pin. |
52
+ | Usage | Claude-reported API cost, context bar, observed and estimated input, cache read/write, output, and a ten-response input trend. |
53
+ | Jev and switch estimate | Jev status and last classification time, suggested tier, policy support, and estimated switch cost. |
54
+ | Controls | Auto, Manual, tier pins, and secure key configuration. |
55
+ | Tuning | Jev deadline, votes before downgrade, and payback horizon. Save applies changes to future turns. |
153
56
 
154
- ```sh
155
- LOG=~/.claude/plugins/data/router-alexei-led-claude-router/decisions.jsonl
156
- jq -r 'select(.observed) | .observed.model' $LOG | sort | uniq -c # requests by model
157
- jq -r 'select(.reason) | .reason' $LOG | sort | uniq -c | sort -rn # decisions by reason
158
- jq -c 'select(.failed) | .failed' $LOG # failed turns
159
- ```
57
+ ### Understand usage and estimates
58
+
59
+ - **API cost reported by Claude** 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.
60
+ - **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.
61
+ - **Cache read / written** and **Output** are observed response counters. The cache reuse bar uses cache-read tokens divided by that response's input counters.
62
+ - **Input trend** shows up to ten observed main-conversation response sizes. It is a scale comparison, not a forecast.
63
+ - **Cache read benefit** is a configured-price estimate for cached reads before write costs. It is not a measured saving.
64
+ - **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.
65
+ - **Conservative 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.
66
+
67
+ There is no router-side spend or savings ledger. The pane does not include Jev charges. Claude's native `/cost` is the source for its reported API cost.
68
+
69
+ ## Change routing
70
+
71
+ | Command or action | Result |
72
+ | ---------------------------------------- | --------------------------------------------------------------------------- |
73
+ | `/router auto` | Resume automatic routing. |
74
+ | `/router off` | Enter Manual mode and preserve Claude's selected model. |
75
+ | `/model <name>` | Select a model and enter Manual mode. Use `/router auto` to resume. |
76
+ | `/router pin <micro\|low\|medium\|high>` | Pin the next turn and its tool continuations. Auto must already be enabled. |
77
+ | **Auto routing** button | Resume automatic routing. |
78
+ | **Manual model** button | Preserve Claude's selected model. |
79
+ | A tier button in the pane | Pin the next turn. Auto must already be enabled. |
80
+
81
+ 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. Resuming a saved session restores its saved Auto or Manual mode.
82
+
83
+ ## Tune future decisions
84
+
85
+ Select the tuning values in the pane, then select **Save tuning**. The three controls are:
86
+
87
+ - **Jev deadline:** 500, 1,000, 1,500, or 3,000 ms for the total advice attempt, including any retry.
88
+ - **Votes before cheaper tier:** 1, 2, or 3 consecutive votes.
89
+ - **Payback horizon:** 1, 3, 5, or 10 later turns used by the downgrade estimate.
90
+
91
+ The current turn keeps the settings it started with. A saved tuning change applies to later turns. The pane preserves unrelated `router.json` keys and refuses to write through a symlink. For other supported settings, see [Configuration](configuration.md).
92
+
93
+ ## Move from v0.8 gateway setup
94
+
95
+ The v1 plugin has the same plugin ID, `router@alexei-led-claude-router`, but it does not start the v0.8 local gateway. Marketplace installs with auto-update receive v1 at the next start. Before the first v1 session:
96
+
97
+ 1. Update the plugin: `claude plugin marketplace update alexei-led-claude-router`, then `claude plugin update router@alexei-led-claude-router`.
98
+ 2. Remove the settings that v0.8 `/router:setup` wrote. The [migration checklist](configuration.md#convert-a-v08-configuration) lists them: the `jev-router[1m]` model and picker row, the loopback `ANTHROPIC_BASE_URL`, the hint header, and the router status line.
99
+ 3. Convert `router.json` if you created one.
100
+ 4. Restart Claude Code with a full baseline model, such as `claude-sonnet-5-5`.
160
101
 
161
- `scripts/transcript-models.sh <transcript.jsonl>` shows the model of each
162
- assistant message in a Claude Code transcript.
102
+ Keep the plugin enabled: in v1 it is the Mod. The Jev key option keeps its saved value. If the band reads `v0.8 gateway settings remain`, step 2 is incomplete.
163
103
 
164
- ## Update
104
+ ## Update or stop
165
105
 
166
- 1. Update the marketplace and the plugin:
106
+ Marketplace installs update with `claude plugin update router@alexei-led-claude-router`. For a local checkout, update the files and restart Claude Code with the same `--plugin-dir`.
167
107
 
168
- ```sh
169
- claude plugin marketplace update alexei-led-claude-router
170
- claude plugin update router@alexei-led-claude-router
171
- ```
108
+ 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.
172
109
 
173
- 2. Restart Claude Code. The next prompt replaces the running gateway.
174
- 3. Run `/router:setup` once. The status line command contains the plugin
175
- version.
110
+ ## Roll back to v0.8.0
176
111
 
177
- ## Stop using the router
112
+ v0.8.0 stays available as the signed git tag `v0.8.0` and as `@alexeiled/claude-router@0.8.0` on npm.
178
113
 
179
- 1. In `~/.claude/settings.json`, remove `model`, `env.ANTHROPIC_BASE_URL`,
180
- `env.ENABLE_TOOL_SEARCH`, `env.CLAUDE_CODE_GATEWAY_HINT_HEADERS` and the
181
- `jev-router[1m]` row of `modelPicker.options`.
182
- 2. If setup changed your status line, restore the old command.
183
- 3. Restart Claude Code.
184
- 4. To remove the plugin, run
185
- `claude plugin uninstall router@alexei-led-claude-router`.
114
+ 1. Disable the v1 plugin: `claude plugin disable router@alexei-led-claude-router`.
115
+ 2. Check out the tag: `git clone --branch v0.8.0 https://github.com/alexei-led/claude-router ~/claude-router-0.8.0`.
116
+ 3. If you converted `router.json`, restore the original: `mv ~/.claude/router.json.v0.8.backup ~/.claude/router.json`. v0.8.0 rejects the converted file.
117
+ 4. Start Claude Code with `--plugin-dir ~/claude-router-0.8.0` and run `/router:setup`. It writes the gateway settings again. Restart.
186
118
 
187
- The gateway stops by itself after two hours without requests.
119
+ Launch with that `--plugin-dir` each time. Do not enable v1 and v0.8 together.
188
120
 
189
121
  ## Troubleshooting
190
122
 
191
- | Symptom | Cause | Fix |
192
- | ----------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------ |
193
- | "There's an issue with the selected model (jev-router[1m])" | The session started before the restart. | Restart Claude Code. |
194
- | Claude Code rejects `jev-router` | The session does not use the gateway. | Run `/router:setup`, then restart Claude Code. |
195
- | The status line shows `gateway off` after the next prompt | The gateway cannot start, for example because `router.json` has an unknown key. | Run `/router:status` to see the error. Read `gateway.log` next to `decisions.jsonl`. |
196
- | Every turn has the reason `no-advice` | No Jev key, or Jev fails. | Run `/router:status`. Read the `router:` lines in `gateway.log`. |
197
- | The effort is not the effort that you set | The model does not accept that effort. | The gateway uses the nearest lower level. Haiku has no effort and no thinking. |
198
- | 429 or 529 errors | Anthropic rate limits or overload. | Claude Code waits and tries again. The gateway sends these errors through unchanged. |
199
- | A `router.json` change has no effect | The gateway reads the configuration at start. | Run `pkill -f scripts/gateway.mjs`. The next prompt starts a new gateway. |
200
-
201
- To see if the gateway runs, open `http://127.0.0.1:43170/v1/models`. The list
202
- shows the alias.
123
+ | Symptom | Cause | Fix |
124
+ | --------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
125
+ | Status says the Jev key is missing | The plugin option is unset or unavailable to this process. | Run `/plugin configure router`, save the option, and start a new turn. |
126
+ | Route stays on the current model | Jev timed out, failed, is paused, or network policy refused the request. | Read the status band and `/router status`. Network policy refusal is not bypassed. |
127
+ | `/model` changed but routing stopped | Choosing a model enters Manual mode. | Run `/router auto` to resume automatic routing. |
128
+ | 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-a-v08-configuration). |
129
+ | Router says old settings need migration | `router.json` still contains v0.8 gateway keys. | Run the [migration command](configuration.md#convert-a-v08-configuration). |
130
+ | Router controls are unavailable | Claude Code is older than 2.1.289, or a gateway alias or loopback base URL is still active. | Update Claude Code and remove the old gateway model/base URL from the launcher. |
131
+ | 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. |
132
+
133
+ For the internal event flow and network deadline behavior, see [Architecture](architecture.md). For what the test traces do and do not show, see [Evaluation](evaluation.md).
package/hooks/hooks.json CHANGED
@@ -1,28 +1,3 @@
1
1
  {
2
- "hooks": {
3
- "SessionStart": [
4
- {
5
- "hooks": [
6
- {
7
- "type": "command",
8
- "command": "node",
9
- "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/ensure-gateway.mjs"],
10
- "timeout": 10
11
- }
12
- ]
13
- }
14
- ],
15
- "UserPromptSubmit": [
16
- {
17
- "hooks": [
18
- {
19
- "type": "command",
20
- "command": "node",
21
- "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/ensure-gateway.mjs", "--quiet"],
22
- "timeout": 10
23
- }
24
- ]
25
- }
26
- ]
27
- }
2
+ "modules": ["./native-router.mjs"]
28
3
  }