@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.
package/lib/runtime.mjs CHANGED
@@ -1,13 +1,78 @@
1
- // Process bootstrap shared by the daemon and the SessionStart hook: configuration and data directory from the environment.
2
- import { homedir, tmpdir } from 'node:os';
3
- import { join } from 'node:path';
4
- import { loadConfig } from './config.mjs';
1
+ // Process bootstrap shared by the daemon and the hooks: configuration and data directory from the environment.
2
+ // A project's `.claude/settings.json` can set process env for a plugin hook (ROUTER_CONFIG, HOME, ...). `home`
3
+ // comes from the OS user database (`os.userInfo().homedir`), never from `$HOME`, so a project cannot redirect it.
4
+ // A `ROUTER_CONFIG` env value is honored only when it resolves inside `<home>/.claude/`; anywhere else it is
5
+ // ignored (with a warning that names the variable, never the rejected path) and the default file is used instead.
6
+ import { execFileSync } from 'node:child_process';
7
+ import { tmpdir, userInfo } from 'node:os';
8
+ import { isAbsolute, join, relative, resolve } from 'node:path';
9
+ import { loadConfig, TIERS } from './config.mjs';
5
10
  import { readJsonFile } from './store.mjs';
6
11
 
7
- export function loadRuntime(env) {
8
- const configPath = env.ROUTER_CONFIG ?? join(homedir(), '.claude', 'router.json');
12
+ // null for a UID without a passwd entry (`docker run --user <uid>`, devcontainers), where userInfo() throws. There
13
+ // the only home is $HOME, which a project can set, so there is no trusted home at all.
14
+ export function userHome(info = userInfo) {
15
+ try {
16
+ return info().homedir;
17
+ } catch {
18
+ return null;
19
+ }
20
+ }
21
+
22
+ // Pure path resolution: no file access. `configPath` is an explicit `--config` value (unrestricted: it comes
23
+ // from a hook's own argv, which a project's settings cannot change) and wins over `env.ROUTER_CONFIG`.
24
+ // Without a trusted home the gateway runs on the defaults: starting beats an outage, and a project chooses nothing.
25
+ export function resolveConfigPath(env, { home = userHome(), configPath = null } = {}) {
26
+ if (configPath) return { path: resolve(configPath), warning: null };
27
+ if (!home) return { path: null, warning: 'no OS user account entry: router.json ignored, defaults used' };
28
+ const fallback = join(home, '.claude', 'router.json');
29
+ const requested = env.ROUTER_CONFIG;
30
+ if (!requested) return { path: fallback, warning: null };
31
+ const resolved = resolve(requested);
32
+ const rel = relative(join(home, '.claude'), resolved);
33
+ const inside = rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
34
+ if (inside) return { path: resolved, warning: null };
35
+ return { path: fallback, warning: 'ROUTER_CONFIG ignored: not under ~/.claude' };
36
+ }
37
+
38
+ // Whatever answers on the gateway port reports a pid; the hook signals it only if that pid runs this plugin's daemon.
39
+ // pid 0 or -1 would signal a process group or every process of the user, so neither reaches `ps` or `kill`.
40
+ export function isRouterGateway(pid, run = execFileSync) {
41
+ if (!Number.isInteger(pid) || pid <= 1) return false;
42
+ try {
43
+ return /scripts\/gateway\.mjs\b/.test(run('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8' }));
44
+ } catch {
45
+ return false; // no such process, or no ps: do not signal
46
+ }
47
+ }
48
+
49
+ // `--flag value` from argv (e.g. `process.argv`). null when the flag is absent.
50
+ export function cliArg(argv, flag) {
51
+ const i = argv.indexOf(flag);
52
+ return i === -1 ? null : (argv[i + 1] ?? null);
53
+ }
54
+
55
+ // The --config for a gateway that a hook starts. spawn() turns null into "null", a path relative to the project the
56
+ // hook runs in, so no resolved path means no flag: the gateway then resolves the same way the hook did.
57
+ export function configArgs(configPath) {
58
+ return configPath ? ['--config', configPath] : [];
59
+ }
60
+
61
+ export function loadRuntime(env, { home = userHome(), configPath = null, forceTier = null } = {}) {
62
+ if (forceTier !== null && !TIERS.includes(forceTier))
63
+ throw new Error(`--force-tier must be one of ${TIERS.join(', ')}`);
64
+ const { path, warning } = resolveConfigPath(env, { home, configPath });
65
+ const userFile = path ? readJsonFile(path) : null; // its own errors name the file
66
+ let config;
67
+ try {
68
+ config = loadConfig({ env, userFile, forcedTier: forceTier });
69
+ } catch (error) {
70
+ throw new Error(`${path}: ${error.message}`);
71
+ }
9
72
  return {
10
- config: loadConfig({ env, userFile: readJsonFile(configPath) }),
73
+ config,
11
74
  dataDir: env.CLAUDE_PLUGIN_DATA || join(tmpdir(), 'router'),
75
+ configPath: path,
76
+ warning,
12
77
  };
13
78
  }
package/lib/status.mjs CHANGED
@@ -34,6 +34,7 @@ export function statusSnapshot(config, memory) {
34
34
  ? {
35
35
  tier: memory.lastRoute,
36
36
  reason: memory.lastReason ?? null,
37
+ estimate: memory.lastEstimate ?? null,
37
38
  effort: memory.lastEffort ?? null,
38
39
  model: memory.lastRequest?.model ?? null,
39
40
  tokens: memory.lastRequest?.tokens ?? null,
@@ -51,14 +52,33 @@ function routeRow(config, tier) {
51
52
  return { tier, model: model.id, effort };
52
53
  }
53
54
 
54
- // One status-line segment, e.g. "router ▸ opus-5-5 · xhigh".
55
+ // Why the route of the last turn is what it is, for /router:status.
56
+ const REASONS = {
57
+ upgrade: 'Jev voted above the current tier often enough, with enough mass for the switching tax',
58
+ jump: 'Jev was confident enough to skip a tier and the vote delay',
59
+ downgrade: 'Jev voted for a lower tier often enough, with enough mass',
60
+ 'upgrade-pending': 'Jev asked for a higher tier; the route stays until the votes and the mass are enough',
61
+ 'downgrade-pending': 'Jev asked for a lower tier; the route stays until the votes and the mass are enough',
62
+ 'same-tier': 'Jev agreed with the current tier',
63
+ continuation: 'the prompt continues the task, so the route stays',
64
+ uncertain: 'Jev abstained, so the route stays',
65
+ 'no-advice': 'no Jev answer (no key, a failure or a pause), so the route stays',
66
+ escalation: 'the same error came back after an edit: one tier up',
67
+ hold: 'the tier stays up for a few turns after an escalation',
68
+ 'cash-gate':
69
+ 'cold-write guard: the first cache write on a credits model would cost more than policy.cashCapUsd, so the strongest plan tier served',
70
+ 'context-fit': "the chosen model's window does not hold the context",
71
+ forced: 'the gateway was started with --force-tier',
72
+ pinned: 'you pinned this turn with /router:<tier>',
73
+ };
74
+
75
+ // One status-line segment, e.g. "router ▸ opus-5-5 · xhigh · upgrade".
55
76
  export function statusSegment(status) {
56
77
  if (!status) return 'router: gateway off, the next prompt starts it';
57
78
  const last = status.session;
58
79
  if (!last) return `${status.alias}: no turn yet`;
59
80
  const model = shortModel(last.model ?? status.routes.find((r) => r.tier === last.tier)?.model);
60
- const effort = last.effort ? ` · ${last.effort}` : '';
61
- return `${status.alias} ▸ ${model}${effort}`;
81
+ return [`${status.alias} ▸ ${model}`, last.effort, last.reason].filter(Boolean).join(' · ');
62
82
  }
63
83
 
64
84
  // Markdown for /router:status.
@@ -82,10 +102,32 @@ export function statusReport(status) {
82
102
  const effort = last.effort ? ` at ${last.effort}` : '';
83
103
  const context = last.tokens ? `, context ${last.tokens} tokens, cache reads ${last.cacheReadTokens}` : '';
84
104
  lines.push(`Last turn: ${last.tier} → ${model}${effort}, reason ${last.reason ?? 'unknown'}${context}.`);
105
+ if (REASONS[last.reason]) lines.push(`Why: ${REASONS[last.reason]}.`);
106
+ const estimate = describeEstimate(last.estimate);
107
+ if (estimate) lines.push(`Estimate: ${estimate}.`);
85
108
  }
86
109
  return lines.join('\n');
87
110
  }
88
111
 
112
+ // Dollars are list prices: for `plan` models a list-price equivalent, not a charge. `unknown` cache: no response for
113
+ // that cache since the session started or its history broke.
114
+ function describeEstimate(e) {
115
+ if (!e) return null;
116
+ const usd = (n) => `$${n.toFixed(2)}`;
117
+ const parts = [];
118
+ if (e.upgradeMass !== undefined)
119
+ parts.push(
120
+ `upgrade mass ${e.upgradeMass.toFixed(2)} against a bar of ${e.threshold.toFixed(2)}`,
121
+ `switching tax ${usd(e.taxUsd)} at list prices`,
122
+ );
123
+ if (e.downgradeMass !== undefined) parts.push(`downgrade mass ${e.downgradeMass.toFixed(2)}`);
124
+ if (e.coldUsd !== undefined) parts.push(`cold write ${usd(e.coldUsd)} against the cap of ${usd(e.cap)}`);
125
+ if (e.streak !== undefined) parts.push(`${e.streak} vote(s) in a row`);
126
+ if (e.cache?.candidate) parts.push(`cache: candidate ${e.cache.candidate}, current ${e.cache.incumbent}`);
127
+ else if (typeof e.cache === 'string') parts.push(`cache ${e.cache}`);
128
+ return parts.join(', ');
129
+ }
130
+
89
131
  // null when the gateway does not answer in time.
90
132
  export async function fetchStatus(port, sessionId) {
91
133
  const query = sessionId ? `?session=${encodeURIComponent(sessionId)}` : '';
package/lib/store.mjs CHANGED
@@ -14,12 +14,13 @@ import { join } from 'node:path';
14
14
  export const LOG_LIMIT_BYTES = 20 * 1024 * 1024;
15
15
  const SESSION_TTL_MS = 30 * 24 * 3_600_000;
16
16
 
17
+ // A JSON syntax error says only that: V8's message quotes the text around the bad token, and the hook prints it.
17
18
  export function readJsonFile(path) {
18
19
  try {
19
20
  return JSON.parse(readFileSync(path, 'utf8'));
20
21
  } catch (error) {
21
22
  if (error.code === 'ENOENT') return null;
22
- throw new Error(`cannot read ${path}: ${error.message}`);
23
+ throw new Error(`cannot read ${path}: ${error instanceof SyntaxError ? 'not valid JSON' : error.message}`);
23
24
  }
24
25
  }
25
26
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alexeiled/claude-router",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
4
4
  "description": "Claude Code plugin: auto-picks the right model and effort for each turn using Jev routing.",
5
5
  "license": "MIT",
6
6
  "author": "Alexei Ledenev",
@@ -20,7 +20,8 @@
20
20
  "scripts",
21
21
  "skills",
22
22
  "docs",
23
- "README.md"
23
+ "README.md",
24
+ "CHANGELOG.md"
24
25
  ],
25
26
  "publishConfig": {
26
27
  "access": "public"
@@ -8,7 +8,7 @@ import { mkdirSync, openSync } from 'node:fs';
8
8
  import { connect } from 'node:net';
9
9
  import { dirname, join } from 'node:path';
10
10
  import { fileURLToPath } from 'node:url';
11
- import { loadRuntime } from '../lib/runtime.mjs';
11
+ import { cliArg, configArgs, isRouterGateway, loadRuntime } from '../lib/runtime.mjs';
12
12
  import { isOlderVersion, ROUTER_VERSION, STATUS_PATH } from '../lib/status.mjs';
13
13
  import { rotate } from '../lib/store.mjs';
14
14
 
@@ -18,13 +18,31 @@ const STATUS_TIMEOUT_MS = 500;
18
18
 
19
19
  const env = process.env;
20
20
  const quiet = process.argv.includes('--quiet');
21
- const { config, dataDir } = loadRuntime(env);
22
- const port = config.gateway.port;
23
21
 
24
22
  function say(message) {
25
23
  if (!quiet) process.stdout.write(`router: ${message}\n`);
26
24
  }
27
25
 
26
+ let config;
27
+ let dataDir;
28
+ let configPath;
29
+ let configWarning;
30
+ try {
31
+ ({
32
+ config,
33
+ dataDir,
34
+ configPath,
35
+ warning: configWarning,
36
+ } = loadRuntime(env, {
37
+ configPath: cliArg(process.argv, '--config'),
38
+ }));
39
+ } catch (error) {
40
+ say(`invalid configuration (${error.message}); the next prompt tries again`);
41
+ process.exit(0);
42
+ }
43
+ if (configWarning) say(configWarning);
44
+ const port = config.gateway.port;
45
+
28
46
  function probe() {
29
47
  return new Promise((resolve) => {
30
48
  const socket = connect({ host: '127.0.0.1', port });
@@ -66,6 +84,10 @@ async function retire(running) {
66
84
  );
67
85
  return false;
68
86
  }
87
+ if (!isRouterGateway(running.pid)) {
88
+ say(`port ${port} answers as gateway ${from}, but pid ${running.pid} is not a router gateway: left alone`);
89
+ return false;
90
+ }
69
91
  try {
70
92
  process.kill(running.pid, 'SIGTERM');
71
93
  } catch (error) {
@@ -91,11 +113,15 @@ async function start() {
91
113
  ...env,
92
114
  TYPESAFE_API_KEY: env.TYPESAFE_API_KEY || env.CLAUDE_PLUGIN_OPTION_TYPESAFE_API_KEY || '',
93
115
  };
94
- const child = spawn(process.execPath, [join(dirname(fileURLToPath(import.meta.url)), 'gateway.mjs')], {
95
- detached: true,
96
- stdio: ['ignore', log, log],
97
- env: childEnv,
98
- });
116
+ const child = spawn(
117
+ process.execPath,
118
+ [join(dirname(fileURLToPath(import.meta.url)), 'gateway.mjs'), ...configArgs(configPath)],
119
+ {
120
+ detached: true,
121
+ stdio: ['ignore', log, log],
122
+ env: childEnv,
123
+ },
124
+ );
99
125
  child.unref();
100
126
  // Wait for the listener so the session's first request finds it.
101
127
  return { pid: child.pid, up: await waitFor(true) };
@@ -3,7 +3,7 @@
3
3
  import { createGateway } from '../lib/gateway.mjs';
4
4
  import { IdleTracker } from '../lib/idle.mjs';
5
5
  import { Router } from '../lib/router.mjs';
6
- import { loadRuntime } from '../lib/runtime.mjs';
6
+ import { cliArg, loadRuntime } from '../lib/runtime.mjs';
7
7
  import { ROUTER_VERSION } from '../lib/status.mjs';
8
8
  import { housekeeping } from '../lib/store.mjs';
9
9
 
@@ -21,7 +21,17 @@ const onError = (error) => log(error.message);
21
21
  process.on('uncaughtException', (error) => log(`uncaught exception: ${error.stack ?? error.message}`));
22
22
  process.on('unhandledRejection', (reason) => log(`unhandled rejection: ${reason?.stack ?? reason}`));
23
23
 
24
- const { config, dataDir } = loadRuntime(process.env);
24
+ let config;
25
+ let dataDir;
26
+ try {
27
+ ({ config, dataDir } = loadRuntime(process.env, {
28
+ configPath: cliArg(process.argv, '--config'),
29
+ forceTier: cliArg(process.argv, '--force-tier'),
30
+ }));
31
+ } catch (error) {
32
+ log(`invalid configuration: ${error.message}`);
33
+ process.exit(1);
34
+ }
25
35
  const { port, alias, idleShutdownMs } = config.gateway;
26
36
  const router = new Router({ config, fetchFn: globalThis.fetch, dataDir, onError });
27
37
  const activity = new IdleTracker();
@@ -1,7 +1,20 @@
1
1
  #!/usr/bin/env node
2
2
  // /router:status: routes, key state and the last routed turn of a session, as markdown.
3
- import { loadRuntime } from '../lib/runtime.mjs';
3
+ // Usage: status.mjs [session id] [--config <path>]. It reads the configuration and starts nothing, so it is also
4
+ // the way to see why a router.json does not load.
5
+ import { cliArg, loadRuntime } from '../lib/runtime.mjs';
4
6
  import { fetchStatus, statusReport } from '../lib/status.mjs';
5
7
 
6
- const { config } = loadRuntime(process.env);
7
- process.stdout.write(`${statusReport(await fetchStatus(config.gateway.port, process.argv[2]))}\n`);
8
+ const argv = process.argv.slice(2);
9
+ const configPath = cliArg(argv, '--config');
10
+ const session = argv.find((arg, i) => !arg.startsWith('--') && argv[i - 1] !== '--config');
11
+
12
+ let config;
13
+ try {
14
+ ({ config } = loadRuntime(process.env, { configPath }));
15
+ } catch (error) {
16
+ // Exit 0: /router:status injects this output into a skill, and Claude Code drops a skill whose command fails.
17
+ process.stdout.write(`router: invalid configuration: ${error.message}\n`);
18
+ process.exit(0);
19
+ }
20
+ process.stdout.write(`${statusReport(await fetchStatus(config.gateway.port, session))}\n`);
@@ -10,13 +10,17 @@ import { fetchStatus, ROUTER_DISPLAY_NAME, statusSegment } from '../lib/status.m
10
10
 
11
11
  const input = await text(process.stdin);
12
12
  const [command, ...args] = process.argv.slice(2);
13
- const { config } = loadRuntime(process.env);
13
+ // A broken router.json must not break the status line: skip the router segment, still run a wrapped command.
14
+ let config = null;
15
+ try {
16
+ ({ config } = loadRuntime(process.env));
17
+ } catch {}
14
18
  let payload = {};
15
19
  try {
16
20
  payload = JSON.parse(input);
17
21
  } catch {}
18
22
 
19
- const names = [config.gateway.alias, LEGACY_ALIAS, ROUTER_DISPLAY_NAME];
23
+ const names = config ? [config.gateway.alias, LEGACY_ALIAS, ROUTER_DISPLAY_NAME] : [];
20
24
  // `jev-router[1m]`: the suffix only tells Claude Code the window size.
21
25
  const routed = [payload.model?.id, payload.model?.display_name].some((name) =>
22
26
  names.includes(name?.replace(/\[1m\]$/, '')),
package/docs/design.md DELETED
@@ -1,254 +0,0 @@
1
- # Design record
2
-
3
- Each decision has the date when the owner took it.
4
-
5
- ## Goal
6
-
7
- Select a model and an effort level for each user turn, from the models that
8
- Claude Code offers, with one TypeSafe Jev Choice. Stay inside the Claude Code
9
- terminal interface.
10
-
11
- ## Mechanism: local gateway (2026-09-22)
12
-
13
- Claude Code runs with `--model jev-router`. `ANTHROPIC_BASE_URL` points at a
14
- gateway on `127.0.0.1`. The gateway sends each request to `api.anthropic.com`
15
- unchanged, except a request whose `model` is the alias. For that request, the
16
- gateway reads facts from the body, asks Jev once for each new user turn, runs
17
- the policy, and changes `model`, `output_config.effort` and `thinking`.
18
- Responses go through unchanged. The gateway reads `usage` from the response to
19
- get the context size, the cache reads and the cache TTL.
20
-
21
- For a model without thinking (Haiku), the gateway also removes the
22
- `clear_thinking_*` edits from `context_management`, because the API rejects
23
- them without thinking. The gateway never changes `system`, `tools` or
24
- `messages`. Thus preserved
25
- thinking and prompt caching work as if Claude Code talked to Anthropic. Claude
26
- Code documents this gateway mode, including the OAuth value for a claude.ai
27
- login. See [llm-gateway](https://code.claude.com/docs/en/llm-gateway) and
28
- [protocol](https://code.claude.com/docs/en/llm-gateway-protocol).
29
-
30
- The `SessionStart` hook of the plugin starts the gateway when the port does not
31
- answer. `/router:setup` writes `model`, `ANTHROPIC_BASE_URL` and the picker row to
32
- the user settings once. A plugin cannot set them by itself.
33
-
34
- The gateway serves `GET /router/status?session=<id>`: the routes and the last
35
- turn of the session, never the key. `/router:status` and the status line
36
- wrapper read it. Claude Code shows only the alias as the model, so the wrapper
37
- is the only place where the real model of the turn is visible.
38
-
39
- ### Why not the native skill path
40
-
41
- The first design used a `UserPromptSubmit` hook. The hook asked Claude to call
42
- a tier skill. The frontmatter `model:` and `effort:` of the skill were to serve
43
- the rest of the turn.
44
-
45
- The test on Claude Code 2.1.278 gave this result. A skill that the user types
46
- (`/router:medium …`) changes the model for the turn. The same skill,
47
- called by Claude through the Skill tool, does not change the model. The
48
- transcript records `attributionSkill`, but the session model answers. The test
49
- ran in three sessions, in auto mode and in `acceptEdits` mode, with Opus and
50
- Fable targets. The documentation says "when this skill is active". The
51
- behavior is user invocation only. A feedback report is filed. The skills stay
52
- as manual pins.
53
-
54
- This result also removed the "Sonnet session model" argument from the peer
55
- review. The gateway has no bootstrap request and no cache drop for a turn that
56
- keeps its route. The baseline is a configuration value.
57
-
58
- ## Tiers
59
-
60
- | Tier | model | effort | id sent to Anthropic |
61
- | ------ | ------ | ------- | -------------------- |
62
- | high | opus | xhigh | claude-opus-5-5 |
63
- | medium | opus | high | claude-opus-5-5 |
64
- | low | sonnet | as sent | claude-sonnet-5 |
65
- | micro | haiku | none | claude-haiku-4-5 |
66
-
67
- The gateway lowers the effort to a level that the model family accepts. Sonnet
68
- 4.6 has no `xhigh`. Haiku gets no effort and no adaptive thinking. The ids are
69
- configuration. `sonnet` is 4.6 because the alias resolved to 4.6 on the test
70
- account.
71
-
72
- ## Request classes
73
-
74
- - New user turn (the last message has no `tool_result`): Jev and the policy.
75
- - Tool continuation: the route of the turn, without a Jev call.
76
- - The classes `auxiliary` and `compaction` from the header
77
- `x-claude-code-request-class`: `auxiliaryTier`, and the memory stays
78
- unchanged. `main`, `subagent` and `workflow` get routing. Without the header,
79
- a body with `thinking: disabled` and a `format` is a side request.
80
- - A subagent (header `x-claude-code-agent-id`): routing with its own memory,
81
- under the key `<session>.<agent id>`. The main conversation keeps its route.
82
- - Any other `model`: unchanged. This covers `/router:<tier>` pins,
83
- `/model` changes and subagents with their own model.
84
- - A resent request (the same history length and the same last message): the
85
- route of the turn, without a Jev call or a vote. Claude Code resends after a
86
- 429, a 529 or a dropped connection.
87
- - A side endpoint with the alias, such as `/v1/messages/count_tokens`: the
88
- model of the session's last route. Only `POST /v1/messages` is a turn.
89
-
90
- ## Failure handling
91
-
92
- One gateway serves every Claude Code session on the machine, so a failure in one
93
- request must not reach the others.
94
-
95
- - Anthropic errors (429, 529, 5xx) pass through unchanged, with `Retry-After`.
96
- Claude Code owns retries and backoff; a second retry layer in the gateway
97
- would multiply attempts and cannot replay a stream that has started.
98
- - The response is relayed with `pipeline()`. An upstream reset destroys the
99
- client response, so Claude Code sees a reset and retries at once. A client
100
- that leaves (Esc) destroys the upstream request, so the model stops
101
- generating an answer that nobody reads.
102
- - Disk errors while the gateway saves session memory or the decision log are
103
- logged. The routing decision stands.
104
- - Jev: one retry on a network error or a transient status, after
105
- `Retry-After` when it fits the 1.5 s budget. After three failures in a row,
106
- new turns skip Jev for a minute, then try once.
107
- - The daemon logs a stray exception instead of exiting. On `SIGTERM` it
108
- releases the port at once and finishes open streams for up to 10 minutes.
109
- A second daemon on a busy port exits quietly.
110
- - The `SessionStart` and `UserPromptSubmit` hooks start the gateway when the
111
- port does not answer, and replace a gateway older than the plugin. They never
112
- replace a newer one.
113
- - The gateway exits after `gateway.idleShutdownMs` (two hours) without
114
- requests. Claude Code holds no connection open between requests, so the
115
- gateway cannot tell a closed session from an idle one; time is the signal.
116
- Two cases keep it running: a request in flight, and a turn whose last
117
- response asked for a tool (`stop_reason: tool_use`), such as an unanswered
118
- permission prompt. The answer to that prompt reaches the gateway without a
119
- new prompt, so without the hook that would start it again. A session that
120
- died mid-turn stops counting after a day. Two hours outlast `/loop` wakeups
121
- and Monitor waits, which also arrive without a prompt.
122
- - The gateway refuses requests with a non-loopback `Host` (DNS rebinding) or a
123
- web `Origin` (cross-site requests from a browser).
124
-
125
- ## Cache and cost inputs
126
-
127
- All inputs come from the traffic of the gateway. The gateway does not read
128
- transcripts.
129
-
130
- | Input | Source |
131
- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
132
- | Context of the last request, cache reads, output | `usage` in the response (`message_start` and `message_delta`) |
133
- | Granted TTL | `usage.cache_creation.ephemeral_1h_input_tokens` or the `5m` field |
134
- | Cache warmth of a model | The time of the last response of that model, plus the TTL, minus 30 s |
135
- | Reusable prefix of a model | The context plus the output at the last response of that model. Cleared by `x-claude-code-context-compacted`, or when the context shrinks by more than 20% (compaction).|
136
- | Failure signal | Two `tool_result` blocks with `is_error` and the same signature, with an edit tool call between them |
137
- | Continuation | The last message contains a `tool_result`. For a new prompt, a Jev Noul answers "does this prompt continue the task". |
138
-
139
- Prices are a list-price table in the configuration. `modelPricing` is a
140
- managed setting and is not readable. The switching tax for a candidate `c`
141
- against the current route `i` is:
142
-
143
- ```
144
- input_cost(m) = P_read(m) * W_m + P_write(m) * (N - W_m)
145
- tax = max(0, input_cost(c) - input_cost(i))
146
- ```
147
-
148
- The subscription economics are not symmetric. Every default model uses the plan
149
- limits, and dollars give the order between them. A model with `billing:
150
- "credits"` bills cash, on the 5m TTL, and behind the gateway without the
151
- consent prompt of Claude Code. `policy.cashCapUsd` ($2 by default) caps the
152
- cold cache write that the gateway will pay for an automatic route to such a
153
- model. A Claude Code turn starts at about 100k tokens (system prompt and 159
154
- tool definitions), so the gate binds on the first switch, not later. No default
155
- model bills credits; the gate stays for configurations that add one.
156
-
157
- ## Switching policy v0
158
-
159
- Agreed with Codex on 2026-09-22. The thresholds are start values.
160
-
161
- 1. Pins win. A request for a real model id goes through unchanged.
162
- 2. To stay is a decision. The current route is the route that served the last
163
- turn. A prompt that continues the task keeps it and never votes for a
164
- downgrade.
165
- 3. Escalation floor. Two failed repairs of the same failure signature, with an
166
- edit between them, move the route one tier up. The route holds for two
167
- turns, once for each signature.
168
- 4. Votes keep the Jev probabilities. `U` is the mass above the current tier.
169
- `D` is the mass at or below the candidate. The `uncertain` mass supports
170
- neither. An upgrade needs two consecutive votes above the current tier and
171
- `U >= 0.75 + 0.15 * tax / (tax + 0.5)`. A jump of two tiers with
172
- `U >= 0.95` skips the delay. A downgrade needs `D >= 0.90` and two
173
- consecutive votes.
174
- 5. Cash gate. An automatic route to a `credits` model needs a warm cache, or a
175
- cold write below the cap. Otherwise the strongest `plan` tier serves.
176
- 6. No cooldown on upgrades. Plan, then execute, then hard again is sometimes
177
- the correct routing. The log separates reversals from real changes in the
178
- required capability.
179
- 7. Logs. The tier, the reason, the estimates, and the observed model, tokens
180
- and cache reads of each routed response. The memory changes only from
181
- responses that the gateway sent.
182
-
183
- ## Test results (2026-09-22, Max plan, Claude Code 2.1.278)
184
-
185
- - Easy prompt: Jev gave `micro` at confidence 1. It was the first vote, so
186
- `low` served (`claude-sonnet-5`, 103,799 context tokens on the first
187
- request).
188
- - Hard prompt: Jev gave `high` at 0.66. A cold Fable write cost $1.30 against
189
- the cap of $0.50 at that time, so `medium` served (`claude-opus-5`). Four
190
- tool continuations kept the route, with cache reads within 1% of the
191
- context.
192
- - Claude Code accepted `message_start.model` with the real model. The status
193
- line showed the alias at all times.
194
- - Cold start: the `SessionStart` hook started the gateway before the first
195
- request.
196
-
197
- ## Layout
198
-
199
- ```
200
- .claude-plugin/plugin.json userConfig.typesafe_api_key (Keychain)
201
- .claude-plugin/marketplace.json github source alexei-led/claude-router
202
- hooks/hooks.json SessionStart -> scripts/ensure-gateway.mjs
203
- scripts/gateway.mjs daemon entry
204
- scripts/ensure-gateway.mjs port probe, detached spawn
205
- scripts/statusline.mjs status line wrapper: wrapped command, then the route
206
- scripts/status.mjs report for /router:status
207
- scripts/transcript-models.sh model for each assistant line of a transcript
208
- lib/runtime.mjs configuration and data directory from the environment
209
- lib/config.mjs defaults, user file, validation
210
- lib/facts.mjs request body and memory -> facts (pure)
211
- lib/jev.mjs request, injected transport, parse
212
- lib/cost.mjs warmth, input cost, switching tax
213
- lib/policy.mjs switching policy v0
214
- lib/rewrite.mjs model, effort, thinking per model family
215
- lib/sse.mjs usage reader for SSE and JSON bodies
216
- lib/router.mjs orchestration for one request, session memory
217
- lib/gateway.mjs HTTP passthrough and rewrite
218
- lib/store.mjs files: configuration, memory, decisions.jsonl
219
- lib/status.mjs status snapshot, status line segment, report
220
- skills/<tier>/SKILL.md manual pins (model and effort frontmatter)
221
- skills/setup/SKILL.md writes model, base URL, picker row, status line
222
- skills/status/SKILL.md /router:status
223
- test/ node:test, builders in helpers.mjs
224
- ```
225
-
226
- ## Open questions
227
-
228
- - The exit from plan mode is not visible in the request body. The policy has
229
- no boundary rule.
230
- - The thresholds are not tuned. The estimated and the observed cache reads in
231
- `decisions.jsonl` are the input for the tuning.
232
- - The gateway reads the configuration once. A reload without a restart is not
233
- implemented.
234
- - Without `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1`, the gateway guesses side
235
- requests and compactions from the body; the guesses miss some.
236
- - `x-claude-code-agent-type` is logged, not used: no policy rule reads it yet.
237
-
238
- ## Release
239
-
240
- The repository root is the plugin and the npm package `@alexeiled/claude-router`.
241
- The marketplace `alexei-led-claude-router` in `.claude-plugin/marketplace.json`
242
- points at this GitHub repository (`"source": "github"`), so Claude Code installs the
243
- plugin from git and never calls npm. An npm source
244
- fails under npm 12: Claude Code fetches the tarball URL, and npm 12 refuses
245
- remote tarballs by default (`EALLOWREMOTE`). `claude plugin update` compares
246
- the `version` in `.claude-plugin/plugin.json`, so each release bumps it. Local
247
- development uses `claude --plugin-dir .`.
248
-
249
- A release is a signed annotated tag `v<version>` on `main`, where the version
250
- matches `package.json`. The `release.yml` workflow makes sure that the tag is
251
- signed and on `main`, runs the checks and the tests, publishes to npm with
252
- trusted publishing (`npm publish --provenance`, no token), and creates the
253
- GitHub release. The `ci.yml` workflow runs the checks and the tests for each
254
- push and pull request on `main`.