@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.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "router",
3
3
  "displayName": "jev-router",
4
- "version": "0.6.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
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
6
  [![Node.js ≥22](https://img.shields.io/node/v/@alexeiled/claude-router.svg)](https://nodejs.org/)
7
7
 
8
- A Claude Code plugin that auto-picks the right model and effort for each turn.
8
+ **jev-router for Claude Code: the right model and effort for each turn.**
9
9
 
10
- A local gateway on `127.0.0.1` receives each request from Claude Code. For a
11
- new user turn, the gateway asks Jev (TypeSafe) which tier the turn needs. Then
12
- the gateway rewrites `model`, `effort` and `thinking` in the request and sends
13
- it to Anthropic. All other data goes through unchanged. The gateway has no
14
- runtime dependencies and needs Node 22 or later.
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
+ ![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.
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
- Claude Code --model jev-router ──▶ gateway 127.0.0.1:43170 ──▶ api.anthropic.com
20
- │
21
- only requests for `jev-router`: ├─ facts.mjs prompt, continuation, failures
22
- ├─ jev.mjs one Choice (tier) + one Noul (continuation?)
23
- ├─ policy.mjs stickiness, escalation, cost-gated votes
24
- ├─ rewrite.mjs model, effort, thinking per model family
25
- └─ store.mjs session memory, decisions.jsonl
26
- responses go through unchanged; the gateway reads `usage` (context size, cache TTL)
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
- The tiers are `micro` (Haiku), `low` (Sonnet, the baseline), `medium` (Opus at
30
- high effort) and `high` (Opus at xhigh effort). The exact model IDs are in
31
- `~/.claude/router.json` and default to the current generation of each family.
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
- A tool continuation keeps the route of its turn — the gateway does not ask Jev.
34
- Side requests, for example session titles, get the baseline tier. A subagent
35
- that inherits the model gets routing with its own memory. A request for
36
- any other model goes through unchanged. This is how `/router:<tier>` pins and
37
- subagents with their own `model` work.
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
- Module dependencies point in one direction: `gateway.mjs` (HTTP) →
40
- `router.mjs` (orchestration) → `facts`, `jev`, `policy` → `cost`, `rewrite`,
41
- `store`. The modules `facts`, `cost`, `rewrite`, `sse` and `policy` are pure.
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 from [typesafe.ai](https://typesafe.ai).
54
- The key goes to the macOS Keychain and persists across updates.
55
- 3. In Claude Code, run `/router:setup`. It writes `model`,
56
- `env.ANTHROPIC_BASE_URL` and the `/model` picker row to
57
- `~/.claude/settings.json`, and offers a status line segment.
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
- A claude.ai login continues to work: the gateway forwards the authorization
66
- header and the `anthropic-beta` OAuth value unchanged.
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): each key, and where the API key and the configuration file are.
89
- - [Design](docs/design.md): decisions, the switching policy, test results.
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.