@alexeiled/claude-router 0.8.0 → 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.
- package/.claude-plugin/plugin.json +10 -6
- package/CHANGELOG.md +19 -0
- package/README.md +51 -100
- package/docs/architecture.md +55 -419
- package/docs/configuration.md +86 -182
- package/docs/evaluation.md +62 -81
- package/docs/native-router.md +79 -0
- package/docs/user-guide.md +103 -172
- package/hooks/hooks.json +1 -26
- package/hooks/native-router.mjs +635 -0
- package/lib/config.mjs +20 -58
- package/lib/{facts.mjs → facts-pure.mjs} +2 -23
- package/lib/{jev.mjs → jev-contract.mjs} +17 -38
- package/lib/native-cost.mjs +88 -0
- package/lib/native-display.mjs +75 -0
- package/lib/native-jev.mjs +125 -0
- package/lib/native-panel.mjs +150 -0
- package/lib/native-router.mjs +216 -0
- package/lib/policy.mjs +17 -21
- package/package.json +9 -8
- package/scripts/migrate-config.mjs +57 -0
- package/types/index.d.ts +95 -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
3
|
"displayName": "jev-router",
|
|
4
|
-
"version": "0.
|
|
5
|
-
"description": "
|
|
6
|
-
"author": {
|
|
4
|
+
"version": "1.0.0",
|
|
5
|
+
"description": "Native Jev model and effort routing for the main conversation. 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,24 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.0.0 (2026-10-05)
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
|
|
7
|
+
- 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.
|
|
8
|
+
- 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.
|
|
9
|
+
- 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.
|
|
10
|
+
- Replaced gateway configuration with optional profile `router.json` settings. Added a backup-first migration command for v0.8 configuration files.
|
|
11
|
+
- 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.
|
|
12
|
+
|
|
13
|
+
### Migration
|
|
14
|
+
|
|
15
|
+
- 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.
|
|
16
|
+
- 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`.
|
|
17
|
+
- 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.
|
|
18
|
+
- 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.
|
|
19
|
+
- The Mod requires Claude Code 2.1.289 or newer.
|
|
20
|
+
- Roll back by disabling the 1.0.0 plugin, restoring `router.json.v0.8.backup` if you converted the file, and loading the signed `v0.8.0` tag with `--plugin-dir`, then running its `/router:setup`. See the [user guide](https://github.com/alexei-led/claude-router/blob/main/docs/user-guide.md#roll-back-to-v080).
|
|
21
|
+
|
|
3
22
|
## 0.8.0 (2026-10-01)
|
|
4
23
|
|
|
5
24
|
### Changed
|
package/README.md
CHANGED
|
@@ -1,127 +1,78 @@
|
|
|
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 asks Jev to choose a model and effort for each main-conversation turn.**
|
|
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.
|
|
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.
|
|
10
|
+
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
11
|
|
|
36
12
|
## How it works
|
|
37
13
|
|
|
38
14
|
```mermaid
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
15
|
+
sequenceDiagram
|
|
16
|
+
actor Dev as Developer
|
|
17
|
+
participant Code as Claude Code
|
|
18
|
+
participant Mod as Router Mod
|
|
19
|
+
participant Jev
|
|
20
|
+
participant API as Anthropic
|
|
21
|
+
Dev->>Code: Prompt
|
|
22
|
+
Code->>Mod: Main or subagent step
|
|
23
|
+
alt Main conversation in Auto
|
|
24
|
+
Mod->>Jev: Bounded prompt and dialogue
|
|
25
|
+
Jev-->>Mod: Tier advice
|
|
26
|
+
Mod-->>Code: Selected model and effort
|
|
27
|
+
else Manual or subagent
|
|
28
|
+
Mod-->>Code: Original model and effort
|
|
29
|
+
end
|
|
30
|
+
Code->>API: Native request and tools
|
|
31
|
+
API-->>Code: Response stream and usage
|
|
32
|
+
Mod-->>Dev: Status band and router pane
|
|
53
33
|
```
|
|
54
34
|
|
|
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.
|
|
35
|
+
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
36
|
|
|
62
|
-
|
|
37
|
+
| Tier | Default model | Effort |
|
|
38
|
+
| -------- | ------------- | ------------------------ |
|
|
39
|
+
| `micro` | Haiku 4.5 | No effort setting |
|
|
40
|
+
| `low` | Sonnet 5.5 | Keeps the session effort |
|
|
41
|
+
| `medium` | Sonnet 5.5 | `xhigh` |
|
|
42
|
+
| `high` | Opus 5.5 | `xhigh` |
|
|
63
43
|
|
|
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
|
-
```
|
|
44
|
+
These are routing defaults. They do not claim equal model quality.
|
|
78
45
|
|
|
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 |
|
|
46
|
+
## Install
|
|
85
47
|
|
|
86
|
-
|
|
87
|
-
length, language or single topic words. The router then keeps the choice
|
|
88
|
-
stable:
|
|
48
|
+
You need Claude Code 2.1.289 or newer and a Jev API key from [typesafe.ai](https://typesafe.ai).
|
|
89
49
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
- If Jev fails or is slow, the current route stays.
|
|
50
|
+
```sh
|
|
51
|
+
claude plugin marketplace add alexei-led/claude-router
|
|
52
|
+
claude plugin install router@alexei-led-claude-router
|
|
53
|
+
```
|
|
95
54
|
|
|
96
|
-
|
|
97
|
-
characters each: the start and the end of a longer text. It does not receive
|
|
98
|
-
tool results or your system prompt.
|
|
55
|
+
Start Claude Code on the full baseline model, for example `claude --model claude-sonnet-5-5`. Then run `/plugin configure router`, save the Jev API key, and run `/router auto`.
|
|
99
56
|
|
|
100
|
-
|
|
57
|
+
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).
|
|
101
58
|
|
|
102
|
-
|
|
103
|
-
[typesafe.ai](https://typesafe.ai).
|
|
59
|
+
## Run from a checkout
|
|
104
60
|
|
|
105
|
-
|
|
61
|
+
Start Claude Code with this directory as a local plugin and the full Sonnet baseline model:
|
|
106
62
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
```
|
|
63
|
+
```sh
|
|
64
|
+
claude --plugin-dir "$PWD" --model claude-sonnet-5-5
|
|
65
|
+
```
|
|
111
66
|
|
|
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.
|
|
67
|
+
In Claude Code, run `/plugin configure router` and save your Jev API key in the sensitive plugin option. Then run `/router auto`. The Mod adds its status band and `/router` pane. No status-line setup or gateway environment variables are needed.
|
|
117
68
|
|
|
118
|
-
|
|
119
|
-
`jev-router ▸ opus-5-5 · xhigh · upgrade`. For more detail, run
|
|
120
|
-
`/router:status`.
|
|
69
|
+
Run `/model` to select a model and enter Manual mode. Run `/router auto` to resume. For controls, metrics, tuning, and troubleshooting, see the [user guide](docs/user-guide.md).
|
|
121
70
|
|
|
122
71
|
## Documentation
|
|
123
72
|
|
|
124
|
-
- [User guide](docs/user-guide.md):
|
|
125
|
-
- [Configuration](docs/configuration.md):
|
|
126
|
-
- [Architecture](docs/architecture.md):
|
|
127
|
-
- [
|
|
73
|
+
- [User guide](docs/user-guide.md): install, use the controls, read the panel, and troubleshoot.
|
|
74
|
+
- [Configuration](docs/configuration.md): the optional profile `router.json`, defaults, and v0.8 migration.
|
|
75
|
+
- [Architecture](docs/architecture.md): Mod event flow, state, safeguards, and runtime boundaries.
|
|
76
|
+
- [Native router details](docs/native-router.md): panel semantics, tuning, and accepted limits.
|
|
77
|
+
- [Evaluation](docs/evaluation.md): historical gateway results and the native shadow replay.
|
|
78
|
+
- [Changelog](CHANGELOG.md): user-visible changes by version.
|