@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,18 +1,22 @@
1
1
  {
2
2
  "name": "router",
3
3
  "displayName": "jev-router",
4
- "version": "0.7.2",
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
- "author": { "name": "Alexei Ledenev", "url": "https://github.com/alexei-led" },
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", "gateway"],
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 reads each prompt and picks the right model tier. Without a key every turn runs on Sonnet.",
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.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
+
22
+ ## 0.8.0 (2026-10-01)
23
+
24
+ ### Changed
25
+
26
+ - **Sonnet 5.5 replaces Sonnet 5.** The `sonnet` model is now
27
+ `claude-sonnet-5-5`, at the same prices. A live probe through Claude Code
28
+ 2.1.286 shows it takes all five effort levels and all three request
29
+ features, so the gateway no longer adapts its history.
30
+ - **`medium` runs on Sonnet 5.5 at `xhigh`**, not on Opus 5.5 at `high`.
31
+ `/router:medium` changes with it. `high` stays Opus 5.5 at `xhigh`. From
32
+ 2026-09-23 to 2026-10-01, 15 of 16 escalations from Sonnet moved the
33
+ session onto Opus for good, at about $31.6 of cold cache writes; most were
34
+ triggered by environment or hook errors, not by the model. An escalation
35
+ from `low` now stays on Sonnet.
36
+
37
+ ### Upgrade
38
+
39
+ - If your `router.json` sets `models.sonnet.id` to `claude-sonnet-5`, also
40
+ set `"features": ["mid-conversation-system"]`. The new default lists all
41
+ three features, and Sonnet 5 answers the other two with 400.
42
+ - To keep the old `medium`, set
43
+ `"routes": { "medium": { "model": "opus", "effort": "high" } }` and change
44
+ `skills/medium/SKILL.md` to match.
45
+
3
46
  ## 0.7.2 (2026-09-25)
4
47
 
5
48
  ### Fixed
package/README.md CHANGED
@@ -1,127 +1,78 @@
1
- # claude-router
1
+ # Claude Model Router
2
2
 
3
3
  [![CI](https://github.com/alexei-led/claude-router/actions/workflows/ci.yml/badge.svg)](https://github.com/alexei-led/claude-router/actions/workflows/ci.yml)
4
- [![npm](https://img.shields.io/npm/v/@alexeiled/claude-router)](https://www.npmjs.com/package/@alexeiled/claude-router)
5
4
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
- [![Node.js ≥22](https://img.shields.io/node/v/@alexeiled/claude-router.svg)](https://nodejs.org/)
7
5
 
8
- **jev-router for Claude Code: the right model and effort for each turn.**
6
+ **A Claude Code Mod that asks Jev to choose a model and effort for each main-conversation turn.**
9
7
 
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.
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
- > **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
- ![jev-router in Claude Code: where the requests went, and what the work cost](docs/tier-share.svg)
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
- 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
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 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.
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
- ## How Jev selects a tier
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
- ```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
77
- ```
44
+ These are routing defaults. They do not claim equal model quality.
78
45
 
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 |
46
+ ## Install
85
47
 
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:
48
+ You need Claude Code 2.1.289 or newer and a Jev API key from [typesafe.ai](https://typesafe.ai).
89
49
 
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.
50
+ ```sh
51
+ claude plugin marketplace add alexei-led/claude-router
52
+ claude plugin install router@alexei-led-claude-router
53
+ ```
95
54
 
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.
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
- ## Install
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
- You need Claude Code, Node.js 22 or later, and a Jev API key from
103
- [typesafe.ai](https://typesafe.ai).
59
+ ## Run from a checkout
104
60
 
105
- 1. Add the marketplace and install the plugin:
61
+ Start Claude Code with this directory as a local plugin and the full Sonnet baseline model:
106
62
 
107
- ```sh
108
- claude plugin marketplace add alexei-led/claude-router
109
- claude plugin install router@alexei-led-claude-router
110
- ```
63
+ ```sh
64
+ claude --plugin-dir "$PWD" --model claude-sonnet-5-5
65
+ ```
111
66
 
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.
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
- 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`.
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): 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.
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.