@alexeiled/claude-router 0.6.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +90 -0
- package/README.md +97 -75
- package/docs/architecture.md +435 -0
- package/docs/configuration.md +151 -153
- package/docs/evaluation.md +83 -0
- package/docs/tier-share.svg +73 -0
- package/docs/user-guide.md +177 -92
- package/lib/config.mjs +105 -14
- package/lib/cost.mjs +53 -8
- package/lib/facts.mjs +37 -6
- package/lib/gateway.mjs +33 -30
- package/lib/jev.mjs +7 -4
- package/lib/policy.mjs +16 -12
- package/lib/rewrite.mjs +93 -3
- package/lib/router.mjs +92 -29
- package/lib/runtime.mjs +72 -7
- package/lib/status.mjs +45 -3
- package/lib/store.mjs +2 -1
- package/package.json +3 -2
- package/scripts/ensure-gateway.mjs +34 -8
- package/scripts/gateway.mjs +12 -2
- package/scripts/status.mjs +16 -3
- package/scripts/statusline.mjs +6 -2
- package/docs/design.md +0 -254
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "router",
|
|
3
3
|
"displayName": "jev-router",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.7.0",
|
|
5
5
|
"description": "Auto-picks the right Claude model for each turn — small models for quick edits, mid-tier for code, frontier for hard problems. Uses Jev to classify each request.",
|
|
6
6
|
"author": { "name": "Alexei Ledenev", "url": "https://github.com/alexei-led" },
|
|
7
7
|
"repository": "https://github.com/alexei-led/claude-router",
|
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.7.0 (2026-09-24)
|
|
4
|
+
|
|
5
|
+
### Upgrade requirements
|
|
6
|
+
|
|
7
|
+
- **Jev advises again.** Current Claude Code (2.1.x) sends hook output as a
|
|
8
|
+
`system` message after your prompt. The router read only the last message,
|
|
9
|
+
found no prompt, and never asked Jev: each new turn logged `no-advice` and
|
|
10
|
+
stayed on its route. Now Jev sees each prompt, so routes change again:
|
|
11
|
+
expect `upgrade`, `downgrade` and `continuation` reasons in the status line.
|
|
12
|
+
- **The gateway adapts the history for Sonnet and Haiku.** Claude Code builds
|
|
13
|
+
each request for Opus. For a model without a request feature, the gateway
|
|
14
|
+
now removes it, as Claude Code does after a 400: Sonnet and Haiku lose
|
|
15
|
+
`tool_addition`/`tool_removal` blocks and per-turn control (the beta and the
|
|
16
|
+
`output_config` on messages); Haiku also gets each `system` message as a
|
|
17
|
+
`<system-reminder>` in the user message. A model that you add in
|
|
18
|
+
`router.json` without `features` gets all three removed.
|
|
19
|
+
- **`high` runs at `xhigh` again.** On Opus, the per-turn effort that Claude
|
|
20
|
+
Code puts on messages overrides the request's effort, so `medium` and `high`
|
|
21
|
+
both ran at your session effort. A route with its own effort now sets it on
|
|
22
|
+
the messages too.
|
|
23
|
+
- **`/router:micro` pins again.** Claude Code 2.1.x ignores `model: haiku` in the
|
|
24
|
+
skill and sends the turn to the alias; the gateway now reads the command and
|
|
25
|
+
serves the turn on `micro`, reason `pinned`. The next prompt goes back to Jev
|
|
26
|
+
from the route before the pin.
|
|
27
|
+
- **`router.json` is strict.** An unknown key (for example a typo such as
|
|
28
|
+
`routs`), a forbidden key (`__proto__`, `constructor`, `prototype`), a
|
|
29
|
+
section that is not an object, or a number out of range now stops a new
|
|
30
|
+
gateway from starting. The error names the file and the field, never the
|
|
31
|
+
value. A gateway that already runs keeps serving. If no gateway runs, every
|
|
32
|
+
request fails to connect until you fix the file. The SessionStart hook
|
|
33
|
+
prints the error; the prompt hook is quiet. `/router:status` shows it too.
|
|
34
|
+
- **`ROUTER_CONFIG` counts only under `~/.claude/`.** The home directory comes
|
|
35
|
+
from your OS user account, not from `$HOME`. A user with no account entry
|
|
36
|
+
(some containers) has no trusted home: the gateway then ignores
|
|
37
|
+
`router.json` and runs on the defaults, with a warning. A path elsewhere is
|
|
38
|
+
ignored, with a warning. Move the file under `~/.claude/`: the hooks and the
|
|
39
|
+
status line pass no flags, so `--config` works only for a gateway that you
|
|
40
|
+
start by hand.
|
|
41
|
+
- **`ROUTER_FORCE_TIER` is gone.** Use `scripts/gateway.mjs --force-tier <tier>`.
|
|
42
|
+
- **A request with an `Origin` header gets 403.** Claude Code sends none. A
|
|
43
|
+
browser page, also one on another loopback port, cannot use the gateway.
|
|
44
|
+
- **Jev receives less text.** The prompt is capped at `context.maxTextChars`
|
|
45
|
+
(1,200 by default), like each earlier turn. A longer text keeps its start
|
|
46
|
+
and its end. The current message is no longer also the last earlier turn.
|
|
47
|
+
|
|
48
|
+
### Added
|
|
49
|
+
|
|
50
|
+
- `--config <path>` on `scripts/gateway.mjs`, `scripts/ensure-gateway.mjs` and
|
|
51
|
+
`scripts/status.mjs`, and `--force-tier <tier>` on `scripts/gateway.mjs`.
|
|
52
|
+
- `decisions.jsonl`: `model` and `effort` on each decision line, `effort` on
|
|
53
|
+
each `observed` line, a `failed` line for a routed turn that Anthropic
|
|
54
|
+
answered with an error, and a `reason: error` line when routing fails.
|
|
55
|
+
- `test/fixtures/effort-support.json`: the effort levels each default model
|
|
56
|
+
accepts, from a probe against the real API. A test pins the defaults to it.
|
|
57
|
+
- `models.<alias>.features` and `test/fixtures/model-features.json`: the request
|
|
58
|
+
features each model accepts, from a live probe; a test pins the defaults.
|
|
59
|
+
|
|
60
|
+
### Changed
|
|
61
|
+
|
|
62
|
+
- The hook sends a stop signal only to a pid that runs `scripts/gateway.mjs`.
|
|
63
|
+
- `Retry-After` from Jev is also read as an HTTP date.
|
|
64
|
+
- The status line keeps working when `router.json` fails to load, and
|
|
65
|
+
`/router:status` names the error in one line.
|
|
66
|
+
|
|
67
|
+
### Fixed
|
|
68
|
+
|
|
69
|
+
- A `system` message after the prompt (hook output, tool additions) hid the
|
|
70
|
+
prompt, a tool result and a resent request from the router. Jev was not
|
|
71
|
+
asked, a tool continuation looked like a new turn, and a request that Claude
|
|
72
|
+
Code resent after a 400 was decided again.
|
|
73
|
+
- The first Haiku turn of a session failed with `400 role 'system' is not
|
|
74
|
+
supported on this model`, and a later one made Claude Code flatten the
|
|
75
|
+
history for the rest of the session: Opus then lost its features, and the
|
|
76
|
+
router saw a shorter history and reset its votes. Sonnet answered the first
|
|
77
|
+
turn with two 400s before Claude Code retried without the features.
|
|
78
|
+
- `/router:micro` did not switch the model with Claude Code 2.1.x.
|
|
79
|
+
- A project's `.claude/settings.json` could point the shared gateway at its own
|
|
80
|
+
`router.json` (and so its own Jev endpoint) through `ROUTER_CONFIG`, while
|
|
81
|
+
the hook passed the real Jev key to that gateway.
|
|
82
|
+
- `routes.<tier>.model: "constructor"` passed the model check; a merge key such
|
|
83
|
+
as `constructor` reached the prototype chain.
|
|
84
|
+
- `policy.upgradePivotUsd: 0` silently stopped upgrades, and an infinite
|
|
85
|
+
`policy.cashCapUsd` turned off the cold-write guard.
|
|
86
|
+
- A side request (title, classifier, compaction) on a session cleared its
|
|
87
|
+
pending tool wait, so the gateway could exit under an open permission
|
|
88
|
+
prompt. This needs the request-class header that `/router:setup` turns on
|
|
89
|
+
(`CLAUDE_CODE_GATEWAY_HINT_HEADERS`); without it the gateway cannot tell a
|
|
90
|
+
side request from a turn and keeps the old behavior.
|
package/README.md
CHANGED
|
@@ -5,44 +5,103 @@
|
|
|
5
5
|
[](https://opensource.org/licenses/MIT)
|
|
6
6
|
[](https://nodejs.org/)
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
**jev-router for Claude Code: the right model and effort for each turn.**
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
10
|
+
Easy work goes to Sonnet or Haiku. Hard work goes to Opus. You do not change
|
|
11
|
+
models by hand. [Jev](https://typesafe.ai), a small routing model from
|
|
12
|
+
TypeSafe, reads each new prompt and advises the tier.
|
|
13
|
+
|
|
14
|
+
> **Status: experimental.** The data below comes from one developer. Try it,
|
|
15
|
+
> and open an issue with your results.
|
|
16
|
+
|
|
17
|
+
## Why use it
|
|
18
|
+
|
|
19
|
+
- **Opus where it matters.** In a day of real work, 86.5% of the requests ran
|
|
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.
|
|
15
35
|
|
|
16
36
|
## How it works
|
|
17
37
|
|
|
38
|
+
```mermaid
|
|
39
|
+
flowchart LR
|
|
40
|
+
YOU["You"] --> CC["Claude Code<br/>model: jev-router"]
|
|
41
|
+
CC --> GW["Local gateway<br/>127.0.0.1"]
|
|
42
|
+
GW -->|"prompt and<br/>recent turns"| JEV{{"Jev"}}
|
|
43
|
+
JEV -->|"tier"| GW
|
|
44
|
+
GW -->|"model, effort"| API["Anthropic API"]
|
|
45
|
+
API -->|"response, unchanged"| CC
|
|
46
|
+
|
|
47
|
+
classDef jev fill:#fef3c7,stroke:#d97706,color:#451a03
|
|
48
|
+
classDef gw fill:#ecfdf5,stroke:#059669,color:#064e3b
|
|
49
|
+
classDef ext fill:#eef2ff,stroke:#6366f1,color:#1e1b4b
|
|
50
|
+
class JEV jev
|
|
51
|
+
class GW gw
|
|
52
|
+
class API ext
|
|
18
53
|
```
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
54
|
+
|
|
55
|
+
A local gateway receives each request from Claude Code. It changes the model,
|
|
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. Sonnet and Haiku do not
|
|
58
|
+
accept all the request features that Claude Code uses for Opus, so the gateway
|
|
59
|
+
adapts those parts of the history for them, as Claude Code itself does. Prompt
|
|
60
|
+
caching and a claude.ai login work as usual.
|
|
61
|
+
|
|
62
|
+
## How Jev selects a tier
|
|
63
|
+
|
|
64
|
+
```mermaid
|
|
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
|
|
27
77
|
```
|
|
28
78
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
79
|
+
| Tier | Model and effort | Jev selects it for |
|
|
80
|
+
| -------- | ------------------------- | --------------------------------------------------------------------- |
|
|
81
|
+
| `micro` | Haiku 4.5, no thinking | Lookups, trivial edits, one-step mechanical work |
|
|
82
|
+
| `low` | Sonnet 5, your effort | Clear, low-risk coding steps with one obvious approach |
|
|
83
|
+
| `medium` | Opus 5.5, `high` 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 |
|
|
85
|
+
|
|
86
|
+
The router tells Jev to put correctness before cost, and not to judge by prompt
|
|
87
|
+
length, language or single topic words. The router then keeps the choice
|
|
88
|
+
stable:
|
|
32
89
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
90
|
+
- Tool calls in a turn keep the model of the turn, so the cache stays warm.
|
|
91
|
+
- A switch up needs two votes, or one confident vote for a jump of two tiers.
|
|
92
|
+
A larger cache write needs more confidence.
|
|
93
|
+
- If the same error comes back after a fix, the route goes one tier up.
|
|
94
|
+
- If Jev fails or is slow, the current route stays.
|
|
38
95
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
Only `store` writes files. The Jev transport is injected.
|
|
96
|
+
Jev receives the prompt and the text of the six turns before it, up to 1,200
|
|
97
|
+
characters each: the start and the end of a longer text. It does not receive
|
|
98
|
+
tool results or your system prompt.
|
|
43
99
|
|
|
44
100
|
## Install
|
|
45
101
|
|
|
102
|
+
You need Claude Code, Node.js 22 or later, and a Jev API key from
|
|
103
|
+
[typesafe.ai](https://typesafe.ai).
|
|
104
|
+
|
|
46
105
|
1. Add the marketplace and install the plugin:
|
|
47
106
|
|
|
48
107
|
```sh
|
|
@@ -50,56 +109,19 @@ Only `store` writes files. The Jev transport is injected.
|
|
|
50
109
|
claude plugin install router@alexei-led-claude-router
|
|
51
110
|
```
|
|
52
111
|
|
|
53
|
-
2. When Claude Code asks, enter the Jev API key
|
|
54
|
-
|
|
55
|
-
3. In Claude Code, run `/router:setup`. It
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
4. Restart Claude Code. `/router:status` shows the routes and the last turn.
|
|
59
|
-
|
|
60
|
-
One gateway serves all Claude Code sessions on the machine. The plugin hooks
|
|
61
|
-
start it at session start and before each prompt when it does not answer, so a
|
|
62
|
-
stopped or crashed gateway comes back on the next prompt. After two hours
|
|
63
|
-
without requests it exits by itself.
|
|
112
|
+
2. When Claude Code asks, enter the Jev API key. The key goes to the macOS
|
|
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.
|
|
64
117
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
## Update
|
|
69
|
-
|
|
70
|
-
```sh
|
|
71
|
-
claude plugin marketplace update alexei-led-claude-router
|
|
72
|
-
claude plugin update router@alexei-led-claude-router
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
Then restart Claude Code or run `/reload-plugins`. The next prompt replaces the
|
|
76
|
-
running gateway with the new version: the old gateway releases the port at once
|
|
77
|
-
and finishes the responses it is streaming. A session that still runs an older
|
|
78
|
-
plugin never replaces a newer gateway. The Jev API key stays in the macOS
|
|
79
|
-
Keychain. Run `/router:setup` once after an update: the status line command
|
|
80
|
-
path contains the plugin version.
|
|
81
|
-
|
|
82
|
-
Updating from 0.3.0 or earlier: these gateways cannot hand over, so stop the
|
|
83
|
-
old one once with `pkill -f scripts/gateway.mjs`.
|
|
118
|
+
The status line shows the route of each turn, for example
|
|
119
|
+
`jev-router ▸ opus-5-5 · xhigh · upgrade`. For more detail, run
|
|
120
|
+
`/router:status`.
|
|
84
121
|
|
|
85
122
|
## Documentation
|
|
86
123
|
|
|
87
|
-
- [User guide](docs/user-guide.md): daily use, pins, decision log, troubleshooting.
|
|
88
|
-
- [Configuration](docs/configuration.md):
|
|
89
|
-
- [
|
|
90
|
-
|
|
91
|
-
## Develop
|
|
92
|
-
|
|
93
|
-
```sh
|
|
94
|
-
npm install
|
|
95
|
-
git config --local core.hooksPath scripts/git-hooks # pre-commit: biome + gitleaks; pre-push: check, test, pack, gitleaks
|
|
96
|
-
npm test # node:test
|
|
97
|
-
npm run check # biome lint and format
|
|
98
|
-
npm run validate # claude plugin validate
|
|
99
|
-
claude --plugin-dir . --model jev-router # with ANTHROPIC_BASE_URL and TYPESAFE_API_KEY set
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
Releases: push a signed tag `v<version>` that matches `package.json`. The
|
|
103
|
-
release workflow publishes `@alexeiled/claude-router` to npm with trusted
|
|
104
|
-
publishing and creates the GitHub release. See
|
|
105
|
-
[docs/design.md](docs/design.md#release).
|
|
124
|
+
- [User guide](docs/user-guide.md): daily use, pins, the decision log, troubleshooting, updates.
|
|
125
|
+
- [Configuration](docs/configuration.md): models, tiers and policy settings.
|
|
126
|
+
- [Architecture](docs/architecture.md): the gateway, the switching policy, the cache and cost model.
|
|
127
|
+
- [Evaluation](docs/evaluation.md): the method and the numbers behind the chart.
|