@alexeiled/claude-router 0.8.0 → 1.1.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 +11 -7
- package/CHANGELOG.md +43 -0
- package/README.md +55 -98
- package/docs/architecture.md +55 -419
- package/docs/configuration.md +88 -182
- package/docs/evaluation.md +62 -81
- package/docs/native-router.md +80 -0
- package/docs/router-band.svg +119 -0
- package/docs/router-pane-now.svg +85 -0
- package/docs/router-pane-tiers.svg +62 -0
- package/docs/user-guide.md +127 -172
- package/hooks/hooks.json +1 -26
- package/hooks/native-router.mjs +701 -0
- package/lib/config.mjs +97 -63
- package/lib/{facts.mjs → facts-pure.mjs} +2 -23
- package/lib/{jev.mjs → jev-contract.mjs} +17 -38
- package/lib/native-band.mjs +206 -0
- package/lib/native-cost.mjs +88 -0
- package/lib/native-display.mjs +122 -0
- package/lib/native-jev.mjs +125 -0
- package/lib/native-panel.mjs +492 -0
- package/lib/native-router.mjs +221 -0
- package/lib/policy.mjs +17 -21
- package/package.json +10 -8
- package/scripts/migrate-config.mjs +57 -0
- package/types/index.d.ts +112 -0
- package/lib/cost.mjs +0 -93
- package/lib/gateway.mjs +0 -221
- package/lib/idle.mjs +0 -41
- package/lib/rewrite.mjs +0 -130
- package/lib/router.mjs +0 -276
- package/lib/runtime.mjs +0 -78
- package/lib/sse.mjs +0 -57
- package/lib/status.mjs +0 -152
- package/lib/store.mjs +0 -76
- package/scripts/ensure-gateway.mjs +0 -143
- package/scripts/gateway.mjs +0 -81
- package/scripts/git-hooks/pre-commit +0 -41
- package/scripts/git-hooks/pre-push +0 -34
- package/scripts/status.mjs +0 -20
- package/scripts/statusline.mjs +0 -45
- package/scripts/transcript-models.sh +0 -4
- package/skills/high/SKILL.md +0 -9
- package/skills/low/SKILL.md +0 -7
- package/skills/medium/SKILL.md +0 -8
- package/skills/micro/SKILL.md +0 -7
- package/skills/setup/SKILL.md +0 -31
- package/skills/status/SKILL.md +0 -12
|
@@ -1,18 +1,22 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "router",
|
|
3
|
-
"displayName": "
|
|
4
|
-
"version": "
|
|
5
|
-
"description": "
|
|
6
|
-
"author": {
|
|
3
|
+
"displayName": "Router",
|
|
4
|
+
"version": "1.1.0",
|
|
5
|
+
"description": "Model and effort routing for the main conversation, advised by a prompt classifier (Jev). Preserves subagent model choices.",
|
|
6
|
+
"author": {
|
|
7
|
+
"name": "Alexei Ledenev",
|
|
8
|
+
"url": "https://github.com/alexei-led"
|
|
9
|
+
},
|
|
7
10
|
"repository": "https://github.com/alexei-led/claude-router",
|
|
8
11
|
"license": "MIT",
|
|
9
|
-
"keywords": ["router", "jev", "typesafe", "effort", "
|
|
12
|
+
"keywords": ["router", "jev", "typesafe", "effort", "mods"],
|
|
10
13
|
"userConfig": {
|
|
11
14
|
"typesafe_api_key": {
|
|
12
15
|
"type": "string",
|
|
13
16
|
"title": "Jev API key (typesafe.ai)",
|
|
14
|
-
"description": "API key from typesafe.ai. Jev
|
|
17
|
+
"description": "Jev API key from typesafe.ai. Jev classifies prompt context; without a key the current model is kept.",
|
|
15
18
|
"sensitive": true
|
|
16
19
|
}
|
|
17
|
-
}
|
|
20
|
+
},
|
|
21
|
+
"types": "./types/index.d.ts"
|
|
18
22
|
}
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,48 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.1.0 (2026-10-05)
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- The status band is redrawn as **Router**: a tier meter, the route, a one-word reason, classifier support, and context and cache, fitted to the band's width. It offers **Auto**, **Set key**, and pin cancel in place. Hover reveals tier pins, Manual, and an optional second row with recent replies by tier.
|
|
8
|
+
- A model change between turns raises a toast; a pin or an effort-only change does not. The spinner says `Choosing model` while the classifier runs. The prompt footer shows `router off` in Manual mode.
|
|
9
|
+
- The router pane has four tabs: Now, Tiers, Tuning, and Usage. Now shows the classifier's support for each tier next to its pin button, and the last 30 replies colored by tier.
|
|
10
|
+
- The Tiers tab edits each tier's model and effort and the baseline tier. It shows the `router.json` diff and how the policy prices each step up before you save. A route can set `"effort": null` to keep the session effort.
|
|
11
|
+
- The Tuning tab adds the credits cap.
|
|
12
|
+
- The user guide and README show the band and pane, drawn from the render code with `npm run docs:images`.
|
|
13
|
+
|
|
14
|
+
### Changed
|
|
15
|
+
|
|
16
|
+
- The `medium` tier defaults to Opus 5.5 at `medium` effort (was Sonnet 5.5 at `xhigh`), for a speed and cost balance. A `routes.medium` entry in `router.json` still overrides it.
|
|
17
|
+
- The plugin is named Router. Jev is named only where it explains a reading or a failure, so other classifiers can follow. The plugin ID is unchanged.
|
|
18
|
+
- `/router` takes `auto`, `off`, or `pin <tier>`. `status` and `setup` are removed: without a UI surface, `/router` prints the status, and **Set key** in the band or pane opens the secure key dialog.
|
|
19
|
+
- A failed save in the pane names the invalid setting instead of a generic error.
|
|
20
|
+
|
|
21
|
+
### Fixed
|
|
22
|
+
|
|
23
|
+
- `/router setup` failed with "no command.run hook answered it". Claude Code refuses `$.command.run` inside a `command.run` hook, so the key dialog now opens from a timer.
|
|
24
|
+
- The input trend scales from the lowest to the highest reading. Before, similar large readings drew as one solid bar.
|
|
25
|
+
- The band yields to surveys and no longer shows the main conversation's tier in a subagent transcript.
|
|
26
|
+
- Leftover v0.8 gateway settings are listed in the pane, not only in text status.
|
|
27
|
+
|
|
28
|
+
## 1.0.0 (2026-10-05)
|
|
29
|
+
|
|
30
|
+
### Changed
|
|
31
|
+
|
|
32
|
+
- Model routing now runs as a Claude Code Mod. It changes only `model` and `effort` on the main conversation. Claude Code sends Anthropic requests and handles streaming, tools, credentials, and usage. Subagent model choices pass through unchanged.
|
|
33
|
+
- Removed the gateway process, local proxy endpoint, gateway launcher hooks, status-line script, and gateway-only skills from the plugin package. The Mod needs no Node runtime service or router-specific Claude settings.
|
|
34
|
+
- Added an integrated status band and `/router` pane. It shows response usage, route reasons, configured-price comparisons, controls, one-turn pins, secure Jev key setup, and three tuning controls.
|
|
35
|
+
- Replaced gateway configuration with optional profile `router.json` settings. Added a backup-first migration command for v0.8 configuration files.
|
|
36
|
+
- The UI reports Claude's native cost reading and labels model-price comparisons as estimates. It does not claim measured savings or keep a second cost ledger.
|
|
37
|
+
|
|
38
|
+
### Migration
|
|
39
|
+
|
|
40
|
+
- The plugin ID stays `router@alexei-led-claude-router`. Marketplace installs with auto-update receive 1.0.0 at the next start; `claude plugin update router@alexei-led-claude-router` updates now. Keep the plugin enabled.
|
|
41
|
+
- Before the first 1.0.0 session, remove what 0.8 `/router:setup` wrote to `settings.json`: `model: "jev-router[1m]"`, the `jev-router[1m]` row in `modelPicker.options`, `env.ANTHROPIC_BASE_URL` set to `http://127.0.0.1:43170`, `env.CLAUDE_CODE_GATEWAY_HINT_HEADERS`, `env.ENABLE_TOOL_SEARCH` if setup added it, and a `statusLine` that runs the router's `scripts/statusline.mjs`. Until then, requests go to a gateway that 1.0.0 no longer starts, and the band reads `v0.8 gateway settings remain`.
|
|
42
|
+
- Run `node scripts/migrate-config.mjs /path/to/router.json` from the plugin directory for an existing 0.8 `router.json`. It keeps an exact-byte `.v0.8.backup` and converts supported route, model, cache and policy settings.
|
|
43
|
+
- Start Claude Code on the full baseline model, for example `claude-sonnet-5-5`. A `/model` choice enters Manual mode; `/router auto` resumes routing. Manual mode follows the session: `/clear` starts Auto, `/resume` restores the resumed session's mode.
|
|
44
|
+
- The Mod requires Claude Code 2.1.289 or newer.
|
|
45
|
+
|
|
3
46
|
## 0.8.0 (2026-10-01)
|
|
4
47
|
|
|
5
48
|
### Changed
|
package/README.md
CHANGED
|
@@ -1,127 +1,84 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Claude Model Router
|
|
2
2
|
|
|
3
3
|
[](https://github.com/alexei-led/claude-router/actions/workflows/ci.yml)
|
|
4
|
-
[](https://www.npmjs.com/package/@alexeiled/claude-router)
|
|
5
4
|
[](https://opensource.org/licenses/MIT)
|
|
6
|
-
[](https://nodejs.org/)
|
|
7
5
|
|
|
8
|
-
**
|
|
6
|
+
**A Claude Code Mod that chooses a model and effort for each main-conversation turn, advised by a prompt classifier (Jev).**
|
|
9
7
|
|
|
10
|
-
|
|
11
|
-
models by hand. [Jev](https://typesafe.ai), a small routing model from
|
|
12
|
-
TypeSafe, reads each new prompt and advises the tier.
|
|
8
|
+
The Mod changes only the model and effort in Claude Code's turn hook. Claude Code sends the request, streams the reply, runs tools, and reports usage. The router does not proxy Anthropic traffic or start a local server. Subagent model choices pass through unchanged.
|
|
13
9
|
|
|
14
|
-
|
|
15
|
-
> and open an issue with your results.
|
|
10
|
+

|
|
16
11
|
|
|
17
|
-
|
|
12
|
+
The band above the prompt shows the tier, model, and reason for each turn. `/router` opens a pane to pin a tier, edit the model and effort of each tier, and tune the policy. See the [user guide](docs/user-guide.md#read-the-status-band).
|
|
18
13
|
|
|
19
|
-
|
|
20
|
-
on Sonnet or Haiku. Opus served the hard 13.5%.
|
|
21
|
-
- **15% less than Opus for everything.** The same work at list prices cost
|
|
22
|
-
$141 with the router and $166 with Opus at xhigh effort for each request.
|
|
23
|
-
- **Less than the best manual choice.** A user who knows the strongest model
|
|
24
|
-
that each session needs pays $147. The router pays $141.
|
|
25
|
-
- **No switches by hand.** You work in Claude Code as usual. When you want a
|
|
26
|
-
fixed tier, pin it: `/router:high`.
|
|
27
|
-
|
|
28
|
-

|
|
29
|
-
|
|
30
|
-
The baselines use the same tokens as the router. They get the cache reads of
|
|
31
|
-
the sessions, and a full cache hit where the router changed models. The
|
|
32
|
-
savings are a lower bound, because the baselines keep the output of the
|
|
33
|
-
router, and a stronger model writes more. [Evaluation](docs/evaluation.md)
|
|
34
|
-
gives the method and the table.
|
|
14
|
+
The router needs Claude Code 2.1.289 or newer. Current savings are not measured. The panel shows Claude's reported usage and configured-price scenarios, not a savings total. See the [evaluation](docs/evaluation.md).
|
|
35
15
|
|
|
36
16
|
## How it works
|
|
37
17
|
|
|
38
18
|
```mermaid
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
19
|
+
sequenceDiagram
|
|
20
|
+
actor Dev as Developer
|
|
21
|
+
participant Code as Claude Code
|
|
22
|
+
participant Mod as Router Mod
|
|
23
|
+
participant Jev
|
|
24
|
+
participant API as Anthropic
|
|
25
|
+
Dev->>Code: Prompt
|
|
26
|
+
Code->>Mod: Main or subagent step
|
|
27
|
+
alt Main conversation in Auto
|
|
28
|
+
Mod->>Jev: Bounded prompt and dialogue
|
|
29
|
+
Jev-->>Mod: Tier advice
|
|
30
|
+
Mod-->>Code: Selected model and effort
|
|
31
|
+
else Manual or subagent
|
|
32
|
+
Mod-->>Code: Original model and effort
|
|
33
|
+
end
|
|
34
|
+
Code->>API: Native request and tools
|
|
35
|
+
API-->>Code: Response stream and usage
|
|
36
|
+
Mod-->>Dev: Status band and router pane
|
|
53
37
|
```
|
|
54
38
|
|
|
55
|
-
A local
|
|
56
|
-
the effort and the thinking setting. For Haiku, it also limits the output
|
|
57
|
-
size. It does not change your prompt or your tools. Haiku does not accept all
|
|
58
|
-
the request features that Claude Code uses for Opus, so the gateway adapts
|
|
59
|
-
those parts of the history for it, as Claude Code itself does. Prompt
|
|
60
|
-
caching and a claude.ai login work as usual.
|
|
39
|
+
Jev classifies a new logical turn once. Tool continuations keep that choice. A local policy applies vote, context, failure, and cache-cost rules before the Mod changes the next step. Claude Code owns request construction, model credentials, tools, streaming, and the API cost ledger.
|
|
61
40
|
|
|
62
|
-
|
|
41
|
+
| Tier | Default model | Effort |
|
|
42
|
+
| -------- | ------------- | ------------------------ |
|
|
43
|
+
| `micro` | Haiku 4.5 | No effort setting |
|
|
44
|
+
| `low` | Sonnet 5.5 | Keeps the session effort |
|
|
45
|
+
| `medium` | Opus 5.5 | `medium` |
|
|
46
|
+
| `high` | Opus 5.5 | `xhigh` |
|
|
63
47
|
|
|
64
|
-
|
|
65
|
-
flowchart LR
|
|
66
|
-
P["New prompt<br/>+ last 6 turns"] --> J{{"Jev"}}
|
|
67
|
-
J --> T["<b>Tier probabilities</b> (example)<br/>high ▇▇▇▇▇▇▇ 0.70<br/>medium ▇▇ 0.20<br/>low ▇ 0.08<br/>micro ▏0.02"]
|
|
68
|
-
J --> C["Does the prompt<br/>continue the task?"]
|
|
69
|
-
T --> POL["Router policy<br/>votes · cache cost · repeated errors"]
|
|
70
|
-
C --> POL
|
|
71
|
-
POL --> R(["Model and effort<br/>for this turn"])
|
|
72
|
-
|
|
73
|
-
classDef jev fill:#fef3c7,stroke:#d97706,color:#451a03
|
|
74
|
-
classDef out fill:#ecfdf5,stroke:#059669,color:#064e3b
|
|
75
|
-
class J jev
|
|
76
|
-
class R out
|
|
77
|
-
```
|
|
48
|
+
These are routing defaults. They do not claim equal model quality.
|
|
78
49
|
|
|
79
|
-
|
|
80
|
-
| -------- | -------------------------- | --------------------------------------------------------------------- |
|
|
81
|
-
| `micro` | Haiku 4.5, no thinking | Lookups, trivial edits, one-step mechanical work |
|
|
82
|
-
| `low` | Sonnet 5.5, your effort | Clear, low-risk coding steps with one obvious approach |
|
|
83
|
-
| `medium` | Sonnet 5.5, `xhigh` effort | Features, bug fixes and refactors with interacting constraints |
|
|
84
|
-
| `high` | Opus 5.5, `xhigh` effort | Architecture, unclear bugs, security, work where correctness is vital |
|
|
50
|
+
## Install
|
|
85
51
|
|
|
86
|
-
|
|
87
|
-
length, language or single topic words. The router then keeps the choice
|
|
88
|
-
stable:
|
|
52
|
+
You need Claude Code 2.1.289 or newer and a Jev API key from [typesafe.ai](https://typesafe.ai).
|
|
89
53
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
- If Jev fails or is slow, the current route stays.
|
|
54
|
+
```sh
|
|
55
|
+
claude plugin marketplace add alexei-led/claude-router
|
|
56
|
+
claude plugin install router@alexei-led-claude-router
|
|
57
|
+
```
|
|
95
58
|
|
|
96
|
-
|
|
97
|
-
characters each: the start and the end of a longer text. It does not receive
|
|
98
|
-
tool results or your system prompt.
|
|
59
|
+
Start Claude Code on the full baseline model, for example `claude --model claude-sonnet-5-5`. Run `/plugin configure router` and save the Jev API key. A session on the baseline model starts in Auto; on another model it starts in Manual, and `/router auto` turns routing on.
|
|
99
60
|
|
|
100
|
-
|
|
61
|
+
Claude Code updates the plugin at startup when auto-update is on for this marketplace. Otherwise run `claude plugin marketplace update alexei-led-claude-router`, then `claude plugin update router@alexei-led-claude-router`.
|
|
101
62
|
|
|
102
|
-
|
|
103
|
-
[typesafe.ai](https://typesafe.ai).
|
|
63
|
+
Upgrading from 0.8? Remove the gateway settings that 0.8 `/router:setup` wrote before the first 1.0 session, or requests go to a gateway that 1.0 no longer starts. Follow the [migration steps](docs/user-guide.md#move-from-v08-gateway-setup).
|
|
104
64
|
|
|
105
|
-
|
|
65
|
+
## Run from a checkout
|
|
106
66
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
67
|
+
Start Claude Code with this directory as a local plugin and the full Sonnet baseline model:
|
|
68
|
+
|
|
69
|
+
```sh
|
|
70
|
+
claude --plugin-dir "$PWD" --model claude-sonnet-5-5
|
|
71
|
+
```
|
|
111
72
|
|
|
112
|
-
|
|
113
|
-
Keychain.
|
|
114
|
-
3. In Claude Code, run `/router:setup`. It sets the model and the gateway
|
|
115
|
-
address, and it can add the route to your status line.
|
|
116
|
-
4. Restart Claude Code.
|
|
73
|
+
In Claude Code, run `/plugin configure router` and save your Jev API key in the sensitive plugin option. The Mod adds its status band and `/router` pane. No status-line setup or gateway environment variables are needed.
|
|
117
74
|
|
|
118
|
-
|
|
119
|
-
`jev-router ▸ opus-5-5 · xhigh · upgrade`. For more detail, run
|
|
120
|
-
`/router:status`.
|
|
75
|
+
Run `/router` to open the pane: route status, per-tier controls, tuning, and usage. Run `/model` to select a model and enter Manual mode, and `/router auto` to resume. For controls, metrics, tuning, and troubleshooting, see the [user guide](docs/user-guide.md).
|
|
121
76
|
|
|
122
77
|
## Documentation
|
|
123
78
|
|
|
124
|
-
- [User guide](docs/user-guide.md):
|
|
125
|
-
- [Configuration](docs/configuration.md):
|
|
126
|
-
- [Architecture](docs/architecture.md):
|
|
127
|
-
- [
|
|
79
|
+
- [User guide](docs/user-guide.md): install, use the controls, read the panel, and troubleshoot.
|
|
80
|
+
- [Configuration](docs/configuration.md): the optional profile `router.json`, defaults, and v0.8 migration.
|
|
81
|
+
- [Architecture](docs/architecture.md): Mod event flow, state, safeguards, and runtime boundaries.
|
|
82
|
+
- [Native router details](docs/native-router.md): panel semantics, tuning, and accepted limits.
|
|
83
|
+
- [Evaluation](docs/evaluation.md): historical gateway results and the native shadow replay.
|
|
84
|
+
- [Changelog](CHANGELOG.md): user-visible changes by version.
|