@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.
Files changed (48) hide show
  1. package/.claude-plugin/plugin.json +11 -7
  2. package/CHANGELOG.md +43 -0
  3. package/README.md +55 -98
  4. package/docs/architecture.md +55 -419
  5. package/docs/configuration.md +88 -182
  6. package/docs/evaluation.md +62 -81
  7. package/docs/native-router.md +80 -0
  8. package/docs/router-band.svg +119 -0
  9. package/docs/router-pane-now.svg +85 -0
  10. package/docs/router-pane-tiers.svg +62 -0
  11. package/docs/user-guide.md +127 -172
  12. package/hooks/hooks.json +1 -26
  13. package/hooks/native-router.mjs +701 -0
  14. package/lib/config.mjs +97 -63
  15. package/lib/{facts.mjs → facts-pure.mjs} +2 -23
  16. package/lib/{jev.mjs → jev-contract.mjs} +17 -38
  17. package/lib/native-band.mjs +206 -0
  18. package/lib/native-cost.mjs +88 -0
  19. package/lib/native-display.mjs +122 -0
  20. package/lib/native-jev.mjs +125 -0
  21. package/lib/native-panel.mjs +492 -0
  22. package/lib/native-router.mjs +221 -0
  23. package/lib/policy.mjs +17 -21
  24. package/package.json +10 -8
  25. package/scripts/migrate-config.mjs +57 -0
  26. package/types/index.d.ts +112 -0
  27. package/lib/cost.mjs +0 -93
  28. package/lib/gateway.mjs +0 -221
  29. package/lib/idle.mjs +0 -41
  30. package/lib/rewrite.mjs +0 -130
  31. package/lib/router.mjs +0 -276
  32. package/lib/runtime.mjs +0 -78
  33. package/lib/sse.mjs +0 -57
  34. package/lib/status.mjs +0 -152
  35. package/lib/store.mjs +0 -76
  36. package/scripts/ensure-gateway.mjs +0 -143
  37. package/scripts/gateway.mjs +0 -81
  38. package/scripts/git-hooks/pre-commit +0 -41
  39. package/scripts/git-hooks/pre-push +0 -34
  40. package/scripts/status.mjs +0 -20
  41. package/scripts/statusline.mjs +0 -45
  42. package/scripts/transcript-models.sh +0 -4
  43. package/skills/high/SKILL.md +0 -9
  44. package/skills/low/SKILL.md +0 -7
  45. package/skills/medium/SKILL.md +0 -8
  46. package/skills/micro/SKILL.md +0 -7
  47. package/skills/setup/SKILL.md +0 -31
  48. package/skills/status/SKILL.md +0 -12
@@ -1,18 +1,22 @@
1
1
  {
2
2
  "name": "router",
3
- "displayName": "jev-router",
4
- "version": "0.8.0",
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" },
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", "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.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
- # 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 chooses a model and effort for each main-conversation turn, advised by a prompt classifier (Jev).**
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.
10
+ ![The Router band above the Claude Code prompt in five states](docs/router-band.svg)
16
11
 
17
- ## Why use it
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
- - **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.
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
- 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
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 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. 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
- ## How Jev selects a tier
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
- ```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
- ```
48
+ These are routing defaults. They do not claim equal model quality.
78
49
 
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.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
- 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:
52
+ You need Claude Code 2.1.289 or newer and a Jev API key from [typesafe.ai](https://typesafe.ai).
89
53
 
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.
54
+ ```sh
55
+ claude plugin marketplace add alexei-led/claude-router
56
+ claude plugin install router@alexei-led-claude-router
57
+ ```
95
58
 
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.
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
- ## Install
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
- You need Claude Code, Node.js 22 or later, and a Jev API key from
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
- 1. Add the marketplace and install the plugin:
65
+ ## Run from a checkout
106
66
 
107
- ```sh
108
- claude plugin marketplace add alexei-led/claude-router
109
- claude plugin install router@alexei-led-claude-router
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
- 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.
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
- 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`.
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): 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.
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.