@alexeiled/claude-router 0.6.1 → 0.7.1

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.1",
4
+ "version": "0.7.1",
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,102 @@
1
+ # Changelog
2
+
3
+ ## 0.7.1 (2026-09-24)
4
+
5
+ ### Fixed
6
+
7
+ - A downgrade paid no attention to its own cost. The switching policy
8
+ checked confidence and vote count for a lower tier, never the price of
9
+ getting there: a candidate whose cache was cold next to a warm incumbent
10
+ could downgrade into a full cache write bigger than what the smaller
11
+ model saved. The downgrade bar now grows with the switching tax the same
12
+ way the upgrade bar does: `0.90 + 0.08 × tax / (tax + $0.50)`, up to
13
+ 0.98. A downgrade to an already-warm candidate is unaffected.
14
+
15
+ ## 0.7.0 (2026-09-24)
16
+
17
+ ### Upgrade requirements
18
+
19
+ - **Jev advises again.** Current Claude Code (2.1.x) sends hook output as a
20
+ `system` message after your prompt. The router read only the last message,
21
+ found no prompt, and never asked Jev: each new turn logged `no-advice` and
22
+ stayed on its route. Now Jev sees each prompt, so routes change again:
23
+ expect `upgrade`, `downgrade` and `continuation` reasons in the status line.
24
+ - **The gateway adapts the history for Sonnet and Haiku.** Claude Code builds
25
+ each request for Opus. For a model without a request feature, the gateway
26
+ now removes it, as Claude Code does after a 400: Sonnet and Haiku lose
27
+ `tool_addition`/`tool_removal` blocks and per-turn control (the beta and the
28
+ `output_config` on messages); Haiku also gets each `system` message as a
29
+ `<system-reminder>` in the user message. A model that you add in
30
+ `router.json` without `features` gets all three removed.
31
+ - **`high` runs at `xhigh` again.** On Opus, the per-turn effort that Claude
32
+ Code puts on messages overrides the request's effort, so `medium` and `high`
33
+ both ran at your session effort. A route with its own effort now sets it on
34
+ the messages too.
35
+ - **`/router:micro` pins again.** Claude Code 2.1.x ignores `model: haiku` in the
36
+ skill and sends the turn to the alias; the gateway now reads the command and
37
+ serves the turn on `micro`, reason `pinned`. The next prompt goes back to Jev
38
+ from the route before the pin.
39
+ - **`router.json` is strict.** An unknown key (for example a typo such as
40
+ `routs`), a forbidden key (`__proto__`, `constructor`, `prototype`), a
41
+ section that is not an object, or a number out of range now stops a new
42
+ gateway from starting. The error names the file and the field, never the
43
+ value. A gateway that already runs keeps serving. If no gateway runs, every
44
+ request fails to connect until you fix the file. The SessionStart hook
45
+ prints the error; the prompt hook is quiet. `/router:status` shows it too.
46
+ - **`ROUTER_CONFIG` counts only under `~/.claude/`.** The home directory comes
47
+ from your OS user account, not from `$HOME`. A user with no account entry
48
+ (some containers) has no trusted home: the gateway then ignores
49
+ `router.json` and runs on the defaults, with a warning. A path elsewhere is
50
+ ignored, with a warning. Move the file under `~/.claude/`: the hooks and the
51
+ status line pass no flags, so `--config` works only for a gateway that you
52
+ start by hand.
53
+ - **`ROUTER_FORCE_TIER` is gone.** Use `scripts/gateway.mjs --force-tier <tier>`.
54
+ - **A request with an `Origin` header gets 403.** Claude Code sends none. A
55
+ browser page, also one on another loopback port, cannot use the gateway.
56
+ - **Jev receives less text.** The prompt is capped at `context.maxTextChars`
57
+ (1,200 by default), like each earlier turn. A longer text keeps its start
58
+ and its end. The current message is no longer also the last earlier turn.
59
+
60
+ ### Added
61
+
62
+ - `--config <path>` on `scripts/gateway.mjs`, `scripts/ensure-gateway.mjs` and
63
+ `scripts/status.mjs`, and `--force-tier <tier>` on `scripts/gateway.mjs`.
64
+ - `decisions.jsonl`: `model` and `effort` on each decision line, `effort` on
65
+ each `observed` line, a `failed` line for a routed turn that Anthropic
66
+ answered with an error, and a `reason: error` line when routing fails.
67
+ - `test/fixtures/effort-support.json`: the effort levels each default model
68
+ accepts, from a probe against the real API. A test pins the defaults to it.
69
+ - `models.<alias>.features` and `test/fixtures/model-features.json`: the request
70
+ features each model accepts, from a live probe; a test pins the defaults.
71
+
72
+ ### Changed
73
+
74
+ - The hook sends a stop signal only to a pid that runs `scripts/gateway.mjs`.
75
+ - `Retry-After` from Jev is also read as an HTTP date.
76
+ - The status line keeps working when `router.json` fails to load, and
77
+ `/router:status` names the error in one line.
78
+
79
+ ### Fixed
80
+
81
+ - A `system` message after the prompt (hook output, tool additions) hid the
82
+ prompt, a tool result and a resent request from the router. Jev was not
83
+ asked, a tool continuation looked like a new turn, and a request that Claude
84
+ Code resent after a 400 was decided again.
85
+ - The first Haiku turn of a session failed with `400 role 'system' is not
86
+ supported on this model`, and a later one made Claude Code flatten the
87
+ history for the rest of the session: Opus then lost its features, and the
88
+ router saw a shorter history and reset its votes. Sonnet answered the first
89
+ turn with two 400s before Claude Code retried without the features.
90
+ - `/router:micro` did not switch the model with Claude Code 2.1.x.
91
+ - A project's `.claude/settings.json` could point the shared gateway at its own
92
+ `router.json` (and so its own Jev endpoint) through `ROUTER_CONFIG`, while
93
+ the hook passed the real Jev key to that gateway.
94
+ - `routes.<tier>.model: "constructor"` passed the model check; a merge key such
95
+ as `constructor` reached the prototype chain.
96
+ - `policy.upgradePivotUsd: 0` silently stopped upgrades, and an infinite
97
+ `policy.cashCapUsd` turned off the cold-write guard.
98
+ - A side request (title, classifier, compaction) on a session cleared its
99
+ pending tool wait, so the gateway could exit under an open permission
100
+ prompt. This needs the request-class header that `/router:setup` turns on
101
+ (`CLAUDE_CODE_GATEWAY_HINT_HEADERS`); without it the gateway cannot tell a
102
+ side request from a turn and keeps the old behavior.
package/README.md CHANGED
@@ -5,53 +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
- **Status: experimental.** I built this to dogfood Jev, TypeSafe's routing
11
- model, inside Claude Code. It works for me; I don't know yet if it holds up
12
- outside my setup. Try it and open an issue with what you find.
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
13
 
14
- ## Why
14
+ > **Status: experimental.** The data below comes from one developer. Try it,
15
+ > and open an issue with your results.
15
16
 
16
- One model for every turn is a compromise: strong enough for the hard turns
17
- and it burns your limits on "rename this variable"; cheap enough for the easy
18
- turns and it struggles on the hard ones. Switching models by hand works, but
19
- it is friction you pay on every message. This plugin asks a small router
20
- model which tier a turn needs and switches for you, automatically.
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.
21
35
 
22
36
  ## How it works
23
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
24
53
  ```
25
- Claude Code --model jev-router ──▶ gateway 127.0.0.1:43170 ──▶ api.anthropic.com
26
- │
27
- only requests for `jev-router`: ├─ facts.mjs prompt, continuation, failures
28
- ├─ jev.mjs one Choice (tier) + one Noul (continuation?)
29
- ├─ policy.mjs stickiness, escalation, cost-gated votes
30
- ├─ rewrite.mjs model, effort, thinking per model family
31
- └─ store.mjs session memory, decisions.jsonl
32
- 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
33
77
  ```
34
78
 
35
- A local gateway on `127.0.0.1` receives each request from Claude Code. For a
36
- new user turn, the gateway asks Jev which tier the turn needs, then rewrites
37
- `model`, `effort` and `thinking` and sends the request to Anthropic. All other
38
- data goes through unchanged. No runtime dependencies; Node 22 or later.
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 |
39
85
 
40
- The tiers are `micro` (Haiku), `low` (Sonnet, the baseline), `medium` (Opus at
41
- high effort) and `high` (Opus at xhigh effort). The exact model IDs are in
42
- `~/.claude/router.json` and default to the current generation of each family.
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:
43
89
 
44
- A tool continuation keeps the route of its turn — the gateway does not ask Jev.
45
- Side requests, for example session titles, get the baseline tier. A subagent
46
- that inherits the model gets routing with its own memory. A request for any
47
- other model goes through unchanged; this is how `/router:<tier>` pins and
48
- 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.
49
95
 
50
- See [Architecture](docs/architecture.md) for the module map, the switching
51
- policy, and a real-usage evaluation.
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.
52
99
 
53
100
  ## Install
54
101
 
102
+ You need Claude Code, Node.js 22 or later, and a Jev API key from
103
+ [typesafe.ai](https://typesafe.ai).
104
+
55
105
  1. Add the marketplace and install the plugin:
56
106
 
57
107
  ```sh
@@ -59,53 +109,19 @@ policy, and a real-usage evaluation.
59
109
  claude plugin install router@alexei-led-claude-router
60
110
  ```
61
111
 
62
- 2. When Claude Code asks, enter the Jev API key from [typesafe.ai](https://typesafe.ai).
63
- The key goes to the macOS Keychain and persists across updates.
64
- 3. In Claude Code, run `/router:setup`. It writes `model`,
65
- `env.ANTHROPIC_BASE_URL` and the `/model` picker row to
66
- `~/.claude/settings.json`, and offers a status line segment.
67
- 4. Restart Claude Code. `/router:status` shows the routes and the last turn.
68
-
69
- One gateway serves all Claude Code sessions on the machine. The plugin hooks
70
- start it at session start and before each prompt when it does not answer, so a
71
- stopped or crashed gateway comes back on the next prompt. After two hours
72
- without requests it exits by itself.
73
-
74
- A claude.ai login continues to work: the gateway forwards the authorization
75
- header and the `anthropic-beta` OAuth value unchanged.
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.
76
117
 
77
- ## Update
78
-
79
- ```sh
80
- claude plugin marketplace update alexei-led-claude-router
81
- claude plugin update router@alexei-led-claude-router
82
- ```
83
-
84
- Then restart Claude Code or run `/reload-plugins`. The next prompt replaces the
85
- running gateway with the new version: the old gateway releases the port at once
86
- and finishes the responses it is streaming. A session that still runs an older
87
- plugin never replaces a newer gateway. The Jev API key stays in the macOS
88
- Keychain. Run `/router:setup` once after an update: the status line command
89
- path contains the plugin version.
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`.
90
121
 
91
122
  ## Documentation
92
123
 
93
- - [User guide](docs/user-guide.md): daily use, pins, decision log, troubleshooting.
94
- - [Configuration](docs/configuration.md): each key, and where the API key and the configuration file are.
95
- - [Architecture](docs/architecture.md): how the gateway works, the switching policy, a real-usage evaluation.
96
-
97
- ## Develop
98
-
99
- ```sh
100
- npm install
101
- git config --local core.hooksPath scripts/git-hooks # pre-commit: biome + gitleaks; pre-push: check, test, pack, gitleaks
102
- npm test # node:test
103
- npm run check # biome lint and format
104
- npm run validate # claude plugin validate
105
- claude --plugin-dir . --model jev-router # with ANTHROPIC_BASE_URL and TYPESAFE_API_KEY set
106
- ```
107
-
108
- Releases: push a signed tag `v<version>` that matches `package.json`. The
109
- release workflow publishes `@alexeiled/claude-router` to npm with trusted
110
- publishing and creates the GitHub release. See
111
- [docs/architecture.md](docs/architecture.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.