@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/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +90 -0
- package/README.md +97 -75
- package/docs/architecture.md +435 -0
- package/docs/configuration.md +151 -153
- package/docs/evaluation.md +83 -0
- package/docs/tier-share.svg +73 -0
- package/docs/user-guide.md +177 -92
- package/lib/config.mjs +105 -14
- package/lib/cost.mjs +53 -8
- package/lib/facts.mjs +37 -6
- package/lib/gateway.mjs +33 -30
- package/lib/jev.mjs +7 -4
- package/lib/policy.mjs +16 -12
- package/lib/rewrite.mjs +93 -3
- package/lib/router.mjs +92 -29
- package/lib/runtime.mjs +72 -7
- package/lib/status.mjs +45 -3
- package/lib/store.mjs +2 -1
- package/package.json +3 -2
- package/scripts/ensure-gateway.mjs +34 -8
- package/scripts/gateway.mjs +12 -2
- package/scripts/status.mjs +16 -3
- package/scripts/statusline.mjs +6 -2
- package/docs/design.md +0 -254
package/lib/runtime.mjs
CHANGED
|
@@ -1,13 +1,78 @@
|
|
|
1
|
-
// Process bootstrap shared by the daemon and the
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
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
|
-
|
|
8
|
-
|
|
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
|
|
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
|
-
//
|
|
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
|
-
|
|
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.
|
|
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(
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
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) };
|
package/scripts/gateway.mjs
CHANGED
|
@@ -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
|
-
|
|
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();
|
package/scripts/status.mjs
CHANGED
|
@@ -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
|
-
|
|
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
|
|
7
|
-
|
|
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`);
|
package/scripts/statusline.mjs
CHANGED
|
@@ -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
|
-
|
|
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`.
|