@alexeiled/claude-router 0.4.0 → 0.4.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "router",
   "displayName": "Router",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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",

package/README.md

@@ -16,13 +16,13 @@ runtime dependencies and needs Node 22 or later.
 ## How it works
 
 ```
-Claude Code  --model router  ──▶  gateway 127.0.0.1:43170  ──▶  api.anthropic.com
-                                   │
-   only requests for `router`:     ├─ facts.mjs    prompt, continuation, failures
-                                   ├─ jev.mjs      one Choice (tier) + one Noul (continuation?)
-                                   ├─ policy.mjs   stickiness, escalation, cost-gated votes
-                                   ├─ rewrite.mjs  model, effort, thinking per model family
-                                   └─ store.mjs    session memory, decisions.jsonl
+Claude Code  --model jev-router  ──▶  gateway 127.0.0.1:43170  ──▶  api.anthropic.com
+                                       │
+only requests for `jev-router`:        ├─ facts.mjs    prompt, continuation, failures
+                                       ├─ jev.mjs      one Choice (tier) + one Noul (continuation?)
+                                       ├─ policy.mjs   stickiness, escalation, cost-gated votes
+                                       ├─ rewrite.mjs  model, effort, thinking per model family
+                                       └─ store.mjs    session memory, decisions.jsonl
    responses go through unchanged; the gateway reads `usage` (context size, cache TTL)
 ```
 
@@ -95,7 +95,7 @@ git config --local core.hooksPath scripts/git-hooks   # pre-commit: biome + gitl
 npm test          # node:test
 npm run check     # biome lint and format
 npm run validate  # claude plugin validate
-claude --plugin-dir . --model router   # with ANTHROPIC_BASE_URL and TYPESAFE_API_KEY set
+claude --plugin-dir . --model jev-router   # with ANTHROPIC_BASE_URL and TYPESAFE_API_KEY set
 ```
 
 Releases: push a signed tag `v<version>` that matches `package.json`. The

package/docs/configuration.md

@@ -6,7 +6,7 @@
 | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
 | TypeSafe API key                | `TYPESAFE_API_KEY` in the environment of the gateway                                                                                                                                                 | One name in all places. The key is never in a file.                                                      |
 | The key for an installed plugin | The plugin option `typesafe_api_key`. Claude Code asks for it when you enable the plugin and stores it in the macOS Keychain. The `SessionStart` hook gives it to the gateway as `TYPESAFE_API_KEY`. | Claude Code exports plugin options as `CLAUDE_PLUGIN_OPTION_<KEY>`. The gateway does not read that name. |
-| Claude Code settings            | `~/.claude/settings.json`: `model`, `env.ANTHROPIC_BASE_URL`, the picker row, the status line. `/router:setup` writes them.                                                                          | Claude Code reads the base URL at start. A plugin cannot set it.                                         |
+| Claude Code settings            | `~/.claude/settings.json`: `model`, `env.ANTHROPIC_BASE_URL`, the `modelPicker` row, the status line. `/router:setup` writes them.                                                                   | Claude Code reads the base URL at start. A plugin cannot set it.                                         |
 | Routing configuration           | `~/.claude/router.json`, user scope only                                                                                                                                                             | A cloned repository must not change your routing or your spend.                                          |
 
 The gateway ignores project files. To use another file, set
@@ -20,21 +20,36 @@ starts it again.
 
 ```json
 {
-  "model": "router",
+  "model": "jev-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 5 / Haiku 4.5 and the effort for each turn"
+    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "1000000"
+  },
+  "modelPicker": {
+    "options": [
+      {
+        "model": "jev-router",
+        "label": "Jev Router (auto)",
+        "description": "Auto-selects the model and effort for each turn",
+        "behavesAs": "claude-opus-5-5"
+      }
+    ]
   }
 }
 ```
 
-The three `ANTHROPIC_CUSTOM_MODEL_OPTION*` keys add a `Router (auto)` row to
-the `/model` picker.
+The `modelPicker` row adds `Jev Router (auto)` to the `/model` picker, next to the
+built-in rows. `behavesAs` maps `jev-router` to a model that Claude Code knows.
+Without it, Claude Code rejects `jev-router` because the model is not in its
+catalog. Setup also removes the `ANTHROPIC_CUSTOM_MODEL_OPTION*` keys that
+older versions wrote. Before 0.4.2 the alias was `router`; the gateway still
+routes it, and setup replaces that row.
+
+Setup writes the file as its last step. Restart Claude Code after it. Until
+the restart, the session sends `jev-router` to Anthropic and shows "There's an
+issue with the selected model (jev-router)".
 
-Claude Code does not know the model `router`, so it assumes a 200K window.
+Claude Code does not know the model `jev-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
@@ -53,7 +68,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`. Without a command
+session, for example `jev-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.
 
@@ -75,7 +90,7 @@ path. Nested objects merge.
 {
   "gateway": {
     "port": 43170,
-    "alias": "router",
+    "alias": "jev-router",
     "baselineTier": "low",
     "auxiliaryTier": "low",
     "idleShutdownMs": 7200000

package/docs/design.md

@@ -10,7 +10,7 @@ terminal interface.
 
 ## Mechanism: local gateway (2026-09-22)
 
-Claude Code runs with `--model router`. `ANTHROPIC_BASE_URL` points at a
+Claude Code runs with `--model jev-router`. `ANTHROPIC_BASE_URL` points at a
 gateway on `127.0.0.1`. The gateway sends each request to `api.anthropic.com`
 unchanged, except a request whose `model` is the alias. For that request, the
 gateway reads facts from the body, asks Jev once for each new user turn, runs

package/docs/user-guide.md

@@ -3,7 +3,7 @@
 ## Start a session
 
 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
+`Jev Router (auto)` as the model. The transcript records the model that answered
 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
@@ -14,7 +14,7 @@ To try the gateway in one session without a change to the configuration:
 
 ```sh
 TYPESAFE_API_KEY=… node scripts/gateway.mjs &
-ANTHROPIC_BASE_URL=http://127.0.0.1:43170 claude --plugin-dir . --model router
+ANTHROPIC_BASE_URL=http://127.0.0.1:43170 claude --plugin-dir . --model jev-router
 ```
 
 ## What happens at each prompt
@@ -69,7 +69,7 @@ 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`: the model and the effort of the last turn.
+- `jev-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 off, the next prompt starts it`: the gateway stopped after
   idle time, or it crashed. Either way the next prompt starts it.
@@ -97,7 +97,7 @@ assistant message in a Claude Code transcript.
 
 ## Troubleshooting
 
-- If Claude Code does not accept `router` as a model, make sure that the
+- If Claude Code does not accept `jev-router` as a model, make sure that the
   gateway runs and that `ANTHROPIC_BASE_URL` is set. The command
   `curl http://127.0.0.1:43170/v1/models` lists the alias.
 - If Claude Code reports that it does not use the gateway, run

package/lib/config.mjs

@@ -3,11 +3,14 @@
 export const TIERS = ['micro', 'low', 'medium', 'high'];
 export const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'];
 
+// The alias before 0.4.2. Settings written by an older /router:setup still send it; drop it once they are rare.
+export const LEGACY_ALIAS = 'router';
+
 export const DEFAULTS = {
   // `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 },
+  gateway: { port: 43170, alias: 'jev-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: {

package/lib/router.mjs

@@ -1,4 +1,5 @@
 // Per-request orchestration: facts -> advice -> policy -> rewritten body. Knows nothing about HTTP.
+import { LEGACY_ALIAS } from './config.mjs';
 import { nextContextTokens } from './cost.mjs';
 import { factsFromRequest } from './facts.mjs';
 import { askJev } from './jev.mjs';
@@ -38,7 +39,7 @@ export class Router {
   }
 
   isRouted(body) {
-    return body?.model === this.config.gateway.alias;
+    return body?.model === this.config.gateway.alias || body?.model === LEGACY_ALIAS;
   }
 
   // Returns { body, tier, reason, auxiliary }. The caller forwards `body` and records the response

package/lib/status.mjs

@@ -17,7 +17,7 @@ export function isOlderVersion(running, current) {
 
 export const STATUS_PATH = '/router/status';
 // The name of the alias in the /model picker and in discovery.
-export const ROUTER_DISPLAY_NAME = 'Router (auto)';
+export const ROUTER_DISPLAY_NAME = 'Jev Router (auto)';
 const FETCH_TIMEOUT_MS = 300;
 
 export function statusSnapshot(config, memory) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexeiled/claude-router",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Claude Code plugin: auto-picks the right model and effort for each turn using Jev routing.",
   "license": "MIT",
   "author": "Alexei Ledenev",

package/scripts/statusline.mjs

@@ -4,6 +4,7 @@
 // A wrapped command (for example claude-powerline) gets the same stdin; its output comes first.
 import { spawn } from 'node:child_process';
 import { text } from 'node:stream/consumers';
+import { LEGACY_ALIAS } from '../lib/config.mjs';
 import { loadRuntime } from '../lib/runtime.mjs';
 import { fetchStatus, ROUTER_DISPLAY_NAME, statusSegment } from '../lib/status.mjs';
 
@@ -15,7 +16,7 @@ try {
   payload = JSON.parse(input);
 } catch {}
 
-const names = [config.gateway.alias, ROUTER_DISPLAY_NAME];
+const names = [config.gateway.alias, LEGACY_ALIAS, ROUTER_DISPLAY_NAME];
 const routed = [payload.model?.id, payload.model?.display_name].some((name) => names.includes(name));
 const [status] = await Promise.all([
   routed ? fetchStatus(config.gateway.port, payload.session_id) : null,

package/skills/setup/SKILL.md

@@ -5,21 +5,25 @@ disable-model-invocation: true
 allowed-tools: Read, Edit, Write
 ---
 
-Configure Claude Code for the router gateway. Do these steps:
+Configure Claude Code for the router gateway. This session does not use the gateway until Claude Code restarts. When the file has `model: "jev-router"`, this session can fail its next request. So ask all questions first, write the file once, and write it last.
 
-1. Read `~/.claude/settings.json`. If the file does not exist, start from `{}`.
-2. Set the key `model` to `"router"`.
-3. Set the key `env.ANTHROPIC_BASE_URL` to `"http://127.0.0.1:43170"`. If `~/.claude/router.json` sets `gateway.port`, use that port.
-4. Set these keys in `env`, for the `/model` picker row:
-   - `ANTHROPIC_CUSTOM_MODEL_OPTION`: `"router"`
-   - `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME`: `"Router (auto)"`
-   - `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION`: `"Auto-selects the model and effort for each turn"`
-5. Set the key `env.CLAUDE_CODE_MAX_CONTEXT_TOKENS` to `"1000000"`. Claude Code does not know the model `router` and assumes a 200K window without this key. If `~/.claude/router.json` changes `routes` or `models`, use the largest `contextWindow` of the models that the routes use. The gateway sends a turn only to a model whose window holds the context.
-6. Keep every other key unchanged. Write the file.
-7. The status line can show the model and effort of the last routed turn. The command is `node ${CLAUDE_PLUGIN_ROOT}/scripts/statusline.mjs`, followed by the current status line command if there is one (for example `node ${CLAUDE_PLUGIN_ROOT}/scripts/statusline.mjs claude-powerline`). Show the user the current `statusLine` value and the new one, and ask. Change `statusLine.command` only if the user agrees. Keep the other `statusLine` keys.
-8. Tell the user:
-   - Restart Claude Code. Then the router serves each turn, and `/router:status` shows the routes and the last turn.
+1. Read `~/.claude/settings.json`. If the file does not exist, start from `{}`. Read `~/.claude/router.json` if it exists.
+2. The status line can show the model and effort of the last routed turn. The command is `node ${CLAUDE_PLUGIN_ROOT}/scripts/statusline.mjs`, followed by the current status line command if there is one (for example `node ${CLAUDE_PLUGIN_ROOT}/scripts/statusline.mjs claude-powerline`). Show the user the current `statusLine` value and the new one, and ask. Change `statusLine.command` only if the user agrees. Keep the other `statusLine` keys.
+3. Prepare the new settings object in memory:
+   - `model`: `"jev-router"`.
+   - `env.ANTHROPIC_BASE_URL`: `"http://127.0.0.1:43170"`. If `router.json` sets `gateway.port`, use that port.
+   - `env.CLAUDE_CODE_MAX_CONTEXT_TOKENS`: `"1000000"`. Claude Code does not know the model `jev-router` and assumes a 200K window without this key. If `router.json` changes `routes` or `models`, use the largest `contextWindow` of the models that the routes use. The gateway sends a turn only to a model whose window holds the context.
+   - The `/model` picker row. In `modelPicker.options`, replace the row whose `model` is `"jev-router"` or `"router"` (the name before 0.4.2), or append it if there is none:
+     `{ "model": "jev-router", "label": "Jev Router (auto)", "description": "Auto-selects the model and effort for each turn", "behavesAs": "claude-opus-5-5" }`.
+     If `modelPicker` does not exist, set it to `{ "options": [<the row>] }`. Keep the other rows and `replaceBuiltInOptions`. `behavesAs` names a model that Claude Code knows; without it, Claude Code rejects `jev-router` as a model that is not in its catalog. If `router.json` changes the `high` route, use the `id` of its model.
+   - Remove `env.ANTHROPIC_CUSTOM_MODEL_OPTION`, `env.ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` and `env.ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION`. Older versions of this setup wrote them; the `modelPicker` row replaces them.
+   - The `statusLine` change from step 2, if the user agreed.
+   - Keep every other key unchanged.
+4. Tell the user, before you write the file:
+   - Restart Claude Code now. Until the restart, this session can show "There's an issue with the selected model (jev-router)", because it still sends requests to Anthropic and not to the gateway.
+   - After the restart, the router serves each turn, and `/router:status` shows the routes and the last turn.
    - The status line path contains the plugin version. After a plugin update, run `/router:setup` again.
-   - To stop the routing, remove `model`, `env.ANTHROPIC_BASE_URL`, `env.CLAUDE_CODE_MAX_CONTEXT_TOKENS` and the three `ANTHROPIC_CUSTOM_MODEL_OPTION*` keys, and restore the status line command.
+   - To stop the routing, remove `model`, `env.ANTHROPIC_BASE_URL`, `env.CLAUDE_CODE_MAX_CONTEXT_TOKENS` and the `jev-router` row of `modelPicker.options`, and restore the status line command.
+5. Write the whole object to `~/.claude/settings.json` with one Write call. Do not use a sequence of edits. Do nothing after this step.
 
 Do not change any other file.