@alexeiled/claude-router 0.2.2 → 0.4.0

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "router",
   "displayName": "Router",
-  "version": "0.2.2",
-  "description": "Local gateway that selects a model and an effort level for each user turn with a TypeSafe Jev Choice.",
+  "version": "0.4.0",
+  "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.",
   "author": { "name": "Alexei Ledenev", "url": "https://github.com/alexei-led" },
   "repository": "https://github.com/alexei-led/claude-router",
   "license": "MIT",
@@ -10,8 +10,8 @@
   "userConfig": {
     "typesafe_api_key": {
       "type": "string",
-      "title": "TypeSafe API key",
-      "description": "Jev key for the routing decision. Stored in the Keychain. Leave empty to run on the baseline tier.",
+      "title": "Jev API key (typesafe.ai)",
+      "description": "API key from typesafe.ai. Jev reads each prompt and picks the right model tier. Without a key every turn runs on Sonnet.",
       "sensitive": true
     }
   }

package/README.md

@@ -1,10 +1,15 @@
 # claude-router
 
-A Claude Code plugin that selects a model and an effort level for each user turn.
+[![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)
+[![npm](https://img.shields.io/npm/v/@alexeiled/claude-router)](https://www.npmjs.com/package/@alexeiled/claude-router)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js ≥22](https://img.shields.io/node/v/@alexeiled/claude-router.svg)](https://nodejs.org/)
+
+A Claude Code plugin that auto-picks the right model and effort for each turn.
 
 A local gateway on `127.0.0.1` receives each request from Claude Code. For a
-new user turn, the gateway asks TypeSafe Jev which tier the turn needs. Then
-the gateway changes `model`, `effort` and `thinking` in the request and sends
+new user turn, the gateway asks Jev (TypeSafe) which tier the turn needs. Then
+the gateway rewrites `model`, `effort` and `thinking` in the request and sends
 it to Anthropic. All other data goes through unchanged. The gateway has no
 runtime dependencies and needs Node 22 or later.
 
@@ -21,14 +26,14 @@ Claude Code  --model router  ──▶  gateway 127.0.0.1:43170  ──▶  api.
    responses go through unchanged; the gateway reads `usage` (context size, cache TTL)
 ```
 
-The tiers are `micro` (haiku), `low` (sonnet, the baseline), `medium` (opus at
-high effort) and `high` (opus at xhigh effort).
+The tiers are `micro` (Haiku), `low` (Sonnet, the baseline), `medium` (Opus at
+high effort) and `high` (Opus at xhigh effort). The exact model IDs are in
+`~/.claude/router.json` and default to the current generation of each family.
 
-A tool continuation is a request whose last message is a `tool_result`. It
-keeps the route of the turn, and the gateway does not ask Jev. Side requests,
-for example session titles, get the baseline tier. A request for any other
-model goes through unchanged. This is how `/router:<tier>` pins and subagents
-with their own `model` work.
+A tool continuation keeps the route of its turn — the gateway does not ask Jev.
+Side requests, for example session titles, get the baseline tier. A request for
+any other model goes through unchanged. This is how `/router:<tier>` pins and
+subagents with their own `model` work.
 
 Module dependencies point in one direction: `gateway.mjs` (HTTP) →
 `router.mjs` (orchestration) → `facts`, `jev`, `policy` → `cost`, `rewrite`,
@@ -44,16 +49,37 @@ Only `store` writes files. The Jev transport is injected.
    claude plugin install router@alexei-led-claude-router
    ```
 
-2. When Claude Code asks, enter the TypeSafe API key. The key goes to the
-   macOS Keychain.
+2. When Claude Code asks, enter the Jev API key from [typesafe.ai](https://typesafe.ai).
+   The key goes to the macOS Keychain and persists across updates.
 3. In Claude Code, run `/router:setup`. It writes `model`,
    `env.ANTHROPIC_BASE_URL` and the `/model` picker row to
    `~/.claude/settings.json`, and offers a status line segment.
 4. Restart Claude Code. `/router:status` shows the routes and the last turn.
 
-The `SessionStart` hook of the plugin starts the gateway when the port does not
-answer. A claude.ai login continues to work: the gateway sends the
-authorization header and the OAuth value of `anthropic-beta` unchanged.
+One gateway serves all Claude Code sessions on the machine. The plugin hooks
+start it at session start and before each prompt when it does not answer, so a
+stopped or crashed gateway comes back on the next prompt. After two hours
+without requests it exits by itself.
+
+A claude.ai login continues to work: the gateway forwards the authorization
+header and the `anthropic-beta` OAuth value unchanged.
+
+## Update
+
+```sh
+claude plugin marketplace update alexei-led-claude-router
+claude plugin update router@alexei-led-claude-router
+```
+
+Then restart Claude Code or run `/reload-plugins`. The next prompt replaces the
+running gateway with the new version: the old gateway releases the port at once
+and finishes the responses it is streaming. A session that still runs an older
+plugin never replaces a newer gateway. The Jev API key stays in the macOS
+Keychain. Run `/router:setup` once after an update: the status line command
+path contains the plugin version.
+
+Updating from 0.3.0 or earlier: these gateways cannot hand over, so stop the
+old one once with `pkill -f scripts/gateway.mjs`.
 
 ## Documentation
 

package/docs/configuration.md

@@ -11,7 +11,7 @@
 
 The gateway ignores project files. To use another file, set
 `ROUTER_CONFIG=/path/to/file.json`. The gateway reads the file at start. After
-an edit, stop the gateway with `pkill -f scripts/gateway.mjs`. The next session
+an edit, stop the gateway with `pkill -f scripts/gateway.mjs`. The next prompt
 starts it again.
 
 ## Claude Code settings
@@ -23,9 +23,10 @@ starts it again.
   "model": "router",
   "env": {
     "ANTHROPIC_BASE_URL": "http://127.0.0.1:43170",
+    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "1000000",
     "ANTHROPIC_CUSTOM_MODEL_OPTION": "router",
     "ANTHROPIC_CUSTOM_MODEL_OPTION_NAME": "Router (auto)",
-    "ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION": "Picks Opus 5.5 / Sonnet 4.6 / Haiku 4.5 and the effort for each turn"
+    "ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION": "Picks Opus 5.5 / Sonnet 5 / Haiku 4.5 and the effort for each turn"
   }
 }
 ```
@@ -33,6 +34,13 @@ starts it again.
 The three `ANTHROPIC_CUSTOM_MODEL_OPTION*` keys add a `Router (auto)` row to
 the `/model` picker.
 
+Claude Code does not know the model `router`, so it assumes a 200K window.
+`CLAUDE_CODE_MAX_CONTEXT_TOKENS` declares the real window: the largest
+`contextWindow` of the routed models, 1M by default. The gateway sends a turn
+only to a model whose window holds the context with room to spare (80%). A
+large session skips Haiku (200K) and goes to Sonnet or Opus. The
+`/router:status` reason for such a turn is `context-fit`.
+
 If you agree, it also wraps the status line command:
 
 ```json
@@ -45,7 +53,7 @@ If you agree, it also wraps the status line command:
 ```
 
 The wrapper runs the command after it, then adds one line for a routed
-session, for example `router ▸ opus-5-5 · xhigh (high)`. Without a command
+session, for example `router ▸ opus-5-5 · xhigh`. Without a command
 after it, it prints only that line. The path contains the plugin version, so
 run `/router:setup` again after a plugin update.
 
@@ -69,7 +77,8 @@ path. Nested objects merge.
     "port": 43170,
     "alias": "router",
     "baselineTier": "low",
-    "auxiliaryTier": "low"
+    "auxiliaryTier": "low",
+    "idleShutdownMs": 7200000
   },
   "routes": {
     "high": { "model": "opus", "effort": "xhigh" },
@@ -79,12 +88,12 @@ path. Nested objects merge.
   },
   "models": {
     "sonnet": {
-      "id": "claude-sonnet-4-6",
-      "input": 3,
-      "cacheRead": 0.3,
+      "id": "claude-sonnet-5",
+      "input": 2,
+      "cacheRead": 0.2,
       "contextWindow": 1000000,
       "billing": "plan",
-      "efforts": ["low", "medium", "high", "max"]
+      "efforts": ["low", "medium", "high", "xhigh", "max"]
     }
   },
   "policy": {
@@ -114,11 +123,11 @@ frontmatter of `skills/<tier>/SKILL.md`. A test makes sure that they agree.
 
 ### models
 
-| Alias    | ID                  | Input | Cache Read | Window | Billing | Efforts |
-| -------- | ------------------- | ----- | ---------- | ------ | ------- | ------- |
-| `opus`   | `claude-opus-5-5`   | $4    | $0.2       | 1M     | plan    | all     |
-| `sonnet` | `claude-sonnet-4-6` | $3    | $0.3       | 1M     | plan    | low–max |
-| `haiku`  | `claude-haiku-4-5`  | $1    | $0.1       | 200k   | plan    | none    |
+| Alias    | ID                 | Input | Cache Read | Window | Billing | Efforts       |
+| -------- | ------------------ | ----- | ---------- | ------ | ------- | ------------- |
+| `opus`   | `claude-opus-5-5`  | $4    | $0.2       | 1M     | plan    | all           |
+| `sonnet` | `claude-sonnet-5`  | $2    | $0.2       | 1M     | plan    | low–xhigh–max |
+| `haiku`  | `claude-haiku-4-5` | $1    | $0.1       | 200k   | plan    | none          |
 
 `id` is the model id that the gateway sends to Anthropic. `input` and
 `cacheRead` are list prices in USD per million tokens. `contextWindow` is the
@@ -134,6 +143,7 @@ effort and thinking from the request.
 | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
 | `gateway.baselineTier`                           | The tier when nothing else decides: Jev abstains, Jev fails, or the session is new.                                                          |
 | `gateway.auxiliaryTier`                          | The tier for side requests, for example session titles.                                                                                      |
+| `gateway.idleShutdownMs`                         | The gateway exits after this long without requests, when no turn waits for a tool result. Two hours by default; `0` keeps it running.        |
 | `upgradeVotes`                                   | The number of consecutive votes above the current tier before an upgrade of one tier.                                                        |
 | `upgradeBase`, `upgradeSlope`, `upgradePivotUsd` | The required probability mass: `base + slope * tax / (tax + pivot)`. The `tax` is the extra input cost to read the context on the new model. |
 | `jumpConfidence`                                 | The mass that lets a jump of two tiers skip the vote delay.                                                                                  |
@@ -150,3 +160,8 @@ effort and thinking from the request.
 | `ROUTER_CONFIG`      | The path of the configuration file.                                                                     |
 | `ROUTER_FORCE_TIER`  | `micro`, `low`, `medium` or `high`. Skips Jev and the policy and always routes to that tier. For tests. |
 | `CLAUDE_PLUGIN_DATA` | Set by Claude Code for hooks. The directory holds `sessions/`, `decisions.jsonl` and `gateway.log`.     |
+
+The gateway keeps the directory bounded. Above 20 MB, `decisions.jsonl` moves
+to `decisions.jsonl.1` (checked every hour), and `gateway.log` moves to
+`gateway.log.1` when a gateway starts. One previous generation is kept. Session
+files unused for 30 days are removed.

package/docs/design.md

@@ -61,7 +61,7 @@ keeps its route. The baseline is a configuration value.
 | ------ | ------ | ------- | -------------------- |
 | high   | opus   | xhigh   | claude-opus-5-5      |
 | medium | opus   | high    | claude-opus-5-5      |
-| low    | sonnet | as sent | claude-sonnet-4-6    |
+| low    | sonnet | as sent | claude-sonnet-5      |
 | micro  | haiku  | none    | claude-haiku-4-5     |
 
 The gateway lowers the effort to a level that the model family accepts. Sonnet
@@ -79,6 +79,46 @@ account.
   `format` is a side request.
 - Any other `model`: unchanged. This covers `/router:<tier>` pins,
   `/model` changes and subagents with their own model.
+- A resent request (the same history length and the same last message): the
+  route of the turn, without a Jev call or a vote. Claude Code resends after a
+  429, a 529 or a dropped connection.
+- A side endpoint with the alias, such as `/v1/messages/count_tokens`: the
+  model of the session's last route. Only `POST /v1/messages` is a turn.
+
+## Failure handling
+
+One gateway serves every Claude Code session on the machine, so a failure in one
+request must not reach the others.
+
+- Anthropic errors (429, 529, 5xx) pass through unchanged, with `Retry-After`.
+  Claude Code owns retries and backoff; a second retry layer in the gateway
+  would multiply attempts and cannot replay a stream that has started.
+- The response is relayed with `pipeline()`. An upstream reset destroys the
+  client response, so Claude Code sees a reset and retries at once. A client
+  that leaves (Esc) destroys the upstream request, so the model stops
+  generating an answer that nobody reads.
+- Disk errors while the gateway saves session memory or the decision log are
+  logged. The routing decision stands.
+- Jev: one retry on a network error or a transient status, after
+  `Retry-After` when it fits the 1.5 s budget. After three failures in a row,
+  new turns skip Jev for a minute, then try once.
+- The daemon logs a stray exception instead of exiting. On `SIGTERM` it
+  releases the port at once and finishes open streams for up to 10 minutes.
+  A second daemon on a busy port exits quietly.
+- The `SessionStart` and `UserPromptSubmit` hooks start the gateway when the
+  port does not answer, and replace a gateway older than the plugin. They never
+  replace a newer one.
+- The gateway exits after `gateway.idleShutdownMs` (two hours) without
+  requests. Claude Code holds no connection open between requests, so the
+  gateway cannot tell a closed session from an idle one; time is the signal.
+  Two cases keep it running: a request in flight, and a turn whose last
+  response asked for a tool (`stop_reason: tool_use`), such as an unanswered
+  permission prompt. The answer to that prompt reaches the gateway without a
+  new prompt, so without the hook that would start it again. A session that
+  died mid-turn stops counting after a day. Two hours outlast `/loop` wakeups
+  and Monitor waits, which also arrive without a prompt.
+- The gateway refuses requests with a non-loopback `Host` (DNS rebinding) or a
+  web `Origin` (cross-site requests from a browser).
 
 ## Cache and cost inputs
 
@@ -141,7 +181,7 @@ Agreed with Codex on 2026-09-22. The thresholds are start values.
 ## Test results (2026-09-22, Max plan, Claude Code 2.1.278)
 
 - Easy prompt: Jev gave `micro` at confidence 1. It was the first vote, so
-  `low` served (`claude-sonnet-4-6`, 103,799 context tokens on the first
+  `low` served (`claude-sonnet-5`, 103,799 context tokens on the first
   request).
 - Hard prompt: Jev gave `high` at 0.66. A cold Fable write cost $1.30 against
   the cap of $0.50 at that time, so `medium` served (`claude-opus-5`). Four

package/docs/user-guide.md

@@ -4,8 +4,11 @@
 
 After the install steps in the README, run `claude` as usual. Claude Code shows
 `Router (auto)` as the model. The transcript records the model that answered
-each message. The first session starts the gateway. The gateway continues to
-run after the session ends.
+each message. The first session starts the gateway, and all sessions share it.
+The gateway continues to run after a session ends. After two hours without
+requests it exits, unless a turn waits for a tool result, for example a
+permission prompt that you have not answered. The next prompt starts it again
+(`gateway.idleShutdownMs` in [configuration](configuration.md)).
 
 To try the gateway in one session without a change to the configuration:
 
@@ -34,7 +37,12 @@ ANTHROPIC_BASE_URL=http://127.0.0.1:43170 claude --plugin-dir . --model router
   prompt for these credits, so the cap is the only guard. No default model
   bills credits; this applies once you add one in `router.json`.
 - When Jev fails or times out, or when there is no key, the baseline tier
-  serves the turn.
+  serves the turn. After three failures in a row, new turns skip Jev for one
+  minute and then try it once, so an outage costs one slow turn a minute, not
+  a second on every turn. `/router:status` shows the pause.
+- When Claude Code sends the same request again (after a 429, a 529 or a
+  dropped connection), the gateway keeps the route of that turn. A retry is
+  not a new vote and makes no Jev call.
 - Jev receives the prompt and the last six turns of text. Tool results are not
   sent. No other data leaves the machine, except the usual Anthropic request.
 
@@ -61,10 +69,10 @@ reason of the last turn in this session.
 The status line wrapper from `/router:setup` adds one line to your status line
 while the session uses the router:
 
-- `router ▸ opus-5-5 · xhigh (high)`: the model, the effort and the tier of the
-  last turn.
+- `router ▸ opus-5-5 · xhigh`: the model and the effort of the last turn.
 - `router: no turn yet`: the session has no routed turn.
-- `router: gateway down`: the gateway does not answer.
+- `router: gateway off, the next prompt starts it`: the gateway stopped after
+  idle time, or it crashed. Either way the next prompt starts it.
 
 The line updates when Claude Code redraws the status line, after each message.
 
@@ -94,10 +102,16 @@ assistant message in a Claude Code transcript.
   `curl http://127.0.0.1:43170/v1/models` lists the alias.
 - If Claude Code reports that it does not use the gateway, run
   `/router:setup` and restart Claude Code.
-- If each turn runs on Sonnet, make sure that the key is set. Read the
-  `router:` lines in `gateway.log` next to `decisions.jsonl`.
+- If each turn runs on the default tier, make sure that the key is set, and
+  read `/router:status`: it shows when Jev is paused after failures. The
+  timestamped `router:` lines in `gateway.log` next to `decisions.jsonl` give
+  the reason, for example `jev http 401` for a rejected key.
 - If the effort is not what you set, read the `efforts` list of the model. The
-  gateway lowers the effort to a level that the model accepts. Sonnet 4.6 has
-  no `xhigh`. Haiku has no effort and no thinking.
-- To stop the gateway, run `pkill -f scripts/gateway.mjs`. The next session
-  starts it again.
+  gateway lowers the effort to a level that the model accepts. Haiku has no
+  effort and no thinking.
+- To stop the gateway, run `pkill -f scripts/gateway.mjs`. It releases the port
+  at once and finishes the responses it is streaming. The next prompt starts it
+  again.
+- Rate limits and overload errors from Anthropic (429, 529) reach Claude Code
+  unchanged. Claude Code waits and retries; the gateway does not add a second
+  layer of retries.

package/hooks/hooks.json

@@ -11,6 +11,18 @@
           }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/ensure-gateway.mjs", "--quiet"],
+            "timeout": 10
+          }
+        ]
+      }
     ]
   }
 }

package/lib/config.mjs

@@ -4,7 +4,10 @@ export const TIERS = ['micro', 'low', 'medium', 'high'];
 export const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'];
 
 export const DEFAULTS = {
-  gateway: { port: 43170, alias: 'router', baselineTier: 'low', auxiliaryTier: 'low' },
+  // `idleShutdownMs`: the gateway exits after this long without requests while no turn waits for a tool result;
+  // the hooks start it again before the next prompt. Two hours outlast /loop wakeups and Monitor waits (up to one
+  // hour), which reach the gateway without a prompt. 0 keeps it running.
+  gateway: { port: 43170, alias: 'router', baselineTier: 'low', auxiliaryTier: 'low', idleShutdownMs: 7_200_000 },
   // `high` and `medium` share one model and differ by effort: Opus 5.5 at xhigh is the strongest
   // setting this router can ask for, and the tier ladder stays four wide for the policy.
   routes: {
@@ -26,12 +29,12 @@ export const DEFAULTS = {
       efforts: EFFORTS,
     },
     sonnet: {
-      id: 'claude-sonnet-4-6',
-      input: 3,
-      cacheRead: 0.3,
+      id: 'claude-sonnet-5',
+      input: 2,
+      cacheRead: 0.2,
       contextWindow: 1_000_000,
       billing: 'plan',
-      efforts: ['low', 'medium', 'high', 'max'],
+      efforts: EFFORTS,
     },
     haiku: { id: 'claude-haiku-4-5', input: 1, cacheRead: 0.1, contextWindow: 200_000, billing: 'plan', efforts: [] },
   },
@@ -113,6 +116,8 @@ function validate(config) {
   if (!Number.isInteger(config.gateway.port) || config.gateway.port < 1 || config.gateway.port > 65535)
     throw new Error('gateway.port must be a port number');
   if (typeof config.gateway.alias !== 'string' || !config.gateway.alias) throw new Error('gateway.alias is required');
+  if (!(Number.isFinite(config.gateway.idleShutdownMs) && config.gateway.idleShutdownMs >= 0))
+    throw new Error('gateway.idleShutdownMs must be a non-negative number (0 keeps the gateway running)');
   const p = config.policy;
   for (const field of ['upgradeBase', 'jumpConfidence', 'downgradeMass', 'continuationMass']) {
     if (!(p[field] >= 0 && p[field] <= 1)) throw new Error(`policy.${field} must be between 0 and 1`);

package/lib/facts.mjs

@@ -1,5 +1,6 @@
 // Facts the policy needs, derived from one Messages request body plus what the router remembers
 // about the conversation. Pure: body and memory in, plain object out.
+import { createHash } from 'node:crypto';
 
 const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'Bash']);
 const FAILURE_WINDOW = 40;
@@ -28,6 +29,8 @@ export function factsFromRequest(body, memory, { recentTurns, maxTextChars }) {
     turns: turns.slice(-recentTurns),
     prompt: last?.role === 'user' ? textOf(lastBlocks) : '',
     continuation: last?.role === 'user' && lastBlocks.some((b) => b.type === 'tool_result'),
+    // The same history length and the same last message: Claude Code resent the request (429, 529, a dropped stream).
+    turnKey: last?.role === 'user' ? `${messages.length}:${hash(JSON.stringify(last.content))}` : null,
     failure: repeatedFailure(errors, edits, messages.length - 1),
     lastRoute: memory.lastRoute,
     lastRequest: memory.lastRequest,
@@ -52,6 +55,10 @@ function signatureOf(block) {
   return textOf(blocks(block.content)).toLowerCase().replace(/\d+/g, '#').replace(/\s+/g, ' ').slice(0, 120);
 }
 
+function hash(text) {
+  return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+
 function blocks(content) {
   if (typeof content === 'string') return [{ type: 'text', text: content }];
   return Array.isArray(content) ? content : [];