@alexeiled/claude-router 0.8.0 → 1.1.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.
Files changed (48) hide show
  1. package/.claude-plugin/plugin.json +11 -7
  2. package/CHANGELOG.md +43 -0
  3. package/README.md +55 -98
  4. package/docs/architecture.md +55 -419
  5. package/docs/configuration.md +88 -182
  6. package/docs/evaluation.md +62 -81
  7. package/docs/native-router.md +80 -0
  8. package/docs/router-band.svg +119 -0
  9. package/docs/router-pane-now.svg +85 -0
  10. package/docs/router-pane-tiers.svg +62 -0
  11. package/docs/user-guide.md +127 -172
  12. package/hooks/hooks.json +1 -26
  13. package/hooks/native-router.mjs +701 -0
  14. package/lib/config.mjs +97 -63
  15. package/lib/{facts.mjs → facts-pure.mjs} +2 -23
  16. package/lib/{jev.mjs → jev-contract.mjs} +17 -38
  17. package/lib/native-band.mjs +206 -0
  18. package/lib/native-cost.mjs +88 -0
  19. package/lib/native-display.mjs +122 -0
  20. package/lib/native-jev.mjs +125 -0
  21. package/lib/native-panel.mjs +492 -0
  22. package/lib/native-router.mjs +221 -0
  23. package/lib/policy.mjs +17 -21
  24. package/package.json +10 -8
  25. package/scripts/migrate-config.mjs +57 -0
  26. package/types/index.d.ts +112 -0
  27. package/lib/cost.mjs +0 -93
  28. package/lib/gateway.mjs +0 -221
  29. package/lib/idle.mjs +0 -41
  30. package/lib/rewrite.mjs +0 -130
  31. package/lib/router.mjs +0 -276
  32. package/lib/runtime.mjs +0 -78
  33. package/lib/sse.mjs +0 -57
  34. package/lib/status.mjs +0 -152
  35. package/lib/store.mjs +0 -76
  36. package/scripts/ensure-gateway.mjs +0 -143
  37. package/scripts/gateway.mjs +0 -81
  38. package/scripts/git-hooks/pre-commit +0 -41
  39. package/scripts/git-hooks/pre-push +0 -34
  40. package/scripts/status.mjs +0 -20
  41. package/scripts/statusline.mjs +0 -45
  42. package/scripts/transcript-models.sh +0 -4
  43. package/skills/high/SKILL.md +0 -9
  44. package/skills/low/SKILL.md +0 -7
  45. package/skills/medium/SKILL.md +0 -8
  46. package/skills/micro/SKILL.md +0 -7
  47. package/skills/setup/SKILL.md +0 -31
  48. package/skills/status/SKILL.md +0 -12
@@ -1,202 +1,157 @@
1
1
  # User guide
2
2
 
3
- After the [install](../README.md#install), work in Claude Code as usual. The
4
- router selects the model and the effort for each turn. This guide shows how
5
- to read what it does, and how to control it.
6
-
7
- - [Check the setup](#check-the-setup)
8
- - [A session, step by step](#a-session-step-by-step)
9
- - [Read the status line](#read-the-status-line)
10
- - [Read `/router:status`](#read-routerstatus)
11
- - [Pin a tier](#pin-a-tier)
12
- - [Read the decision log](#read-the-decision-log)
13
- - [Update](#update)
14
- - [Stop using the router](#stop-using-the-router)
15
- - [Troubleshooting](#troubleshooting)
16
-
17
- ## Check the setup
18
-
19
- 1. Start Claude Code. `/model` shows `Jev Router (auto)` as the model.
20
- 2. Send a prompt. If setup added the status line, it shows the route, for
21
- example `jev-router ▸ sonnet-5-5 · high · same-tier`.
22
- 3. Run `/router:status`. It shows `Jev routing: active.`
23
-
24
- If a step fails, read [Troubleshooting](#troubleshooting).
25
-
26
- ## A session, step by step
27
-
28
- An example of four turns. Each box is one prompt with its route and reason.
29
-
30
- ```mermaid
31
- flowchart LR
32
- T1["<b>1</b> · design a cache layer<br/>Opus · xhigh<br/><i>jump</i>"]
33
- T2["<b>2</b> · yes, go on<br/>Opus · xhigh<br/><i>continuation</i>"]
34
- T3["<b>3</b> · rename foo to bar<br/>Opus · xhigh<br/><i>downgrade-pending</i>"]
35
- T4["<b>4</b> · fix the typo<br/>Sonnet<br/><i>downgrade</i>"]
36
- T1 --> T2 --> T3 --> T4
37
-
38
- classDef opus fill:#0d366b,stroke:#0d366b,color:#ffffff
39
- classDef sonnet fill:#cde2fb,stroke:#2a78d6,color:#0b0b0b
40
- class T1,T2,T3 opus
41
- class T4 sonnet
42
- ```
3
+ ## Start a session
43
4
 
44
- 1. A confident vote for hard work goes up two tiers at once.
45
- 2. A prompt that continues the task keeps the route.
46
- 3. One vote for a lower tier is not enough. The route stays.
47
- 4. The second vote in a row moves the route down.
5
+ Install the plugin from its marketplace, or load a checkout with `--plugin-dir /path/to/claude-router`:
48
6
 
49
- The tool calls in a turn keep the route of the turn, so the cache stays warm.
50
- The [README](../README.md#how-jev-selects-a-tier) gives all the rules.
7
+ ```sh
8
+ claude plugin marketplace add alexei-led/claude-router
9
+ claude plugin install router@alexei-led-claude-router
10
+ ```
51
11
 
52
- ## Read the status line
12
+ Start with the full baseline model so Auto mode has a known starting point:
53
13
 
54
- ```text
55
- jev-router ▸ opus-5-5 · xhigh · upgrade
56
- │ │ └─ reason for the route
57
- │ └─ effort
58
- └─ model of the last turn
14
+ ```sh
15
+ claude --model claude-sonnet-5-5
59
16
  ```
60
17
 
61
- | Line | Meaning |
62
- | ------------------------------------------------ | --------------------------------------------------- |
63
- | `jev-router ▸ …` | The route of the last turn in this session. |
64
- | `jev-router: no turn yet` | This session has no routed turn. |
65
- | `router: gateway off, the next prompt starts it` | The gateway stopped after idle time, or it crashed. |
66
-
67
- The line changes after each message.
68
-
69
- **The route changed:**
70
-
71
- | Reason | Meaning |
72
- | ------------- | ---------------------------------------------------------------------------- |
73
- | `upgrade` | Two votes in a row for a higher tier, with enough confidence. |
74
- | `jump` | One vote confident enough to go up two tiers. |
75
- | `downgrade` | Two votes in a row for a lower tier, with enough confidence. |
76
- | `escalation` | The same error came back after an edit. The route went up one tier. |
77
- | `context-fit` | The selected model cannot hold the context. A larger window serves the turn. |
78
- | `cash-gate` | The cold-write guard stopped a switch to a `credits` model. |
79
-
80
- **The route stayed:**
81
-
82
- | Reason | Meaning |
83
- | ------------------- | ------------------------------------------------------------------- |
84
- | `same-tier` | Jev agreed with the current tier. |
85
- | `continuation` | The prompt continues the task. |
86
- | `upgrade-pending` | One vote for a higher tier. The next vote decides. |
87
- | `downgrade-pending` | One vote for a lower tier. The next vote decides. |
88
- | `hold` | The route stays up for two turns after an escalation. |
89
- | `uncertain` | Jev did not select a tier. |
90
- | `no-advice` | No Jev answer: no key, an error, a pause, or a prompt without text. |
91
-
92
- `forced` means that the gateway was started with `--force-tier`.
93
-
94
- ## Read `/router:status`
95
-
96
- `/router:status` shows the gateway, the routes and the last turn. For a
97
- vote, it also shows the numbers:
98
-
99
- ```text
100
- Router v0.7.0, gateway: http://127.0.0.1:43170, alias `jev-router`.
101
- Jev routing: active.
102
- Default tier: low.
103
- …
104
- Last turn: low → claude-sonnet-5-5 at high, reason upgrade-pending, context 84210 tokens, cache reads 83904.
105
- Why: Jev asked for a higher tier; the route stays until the votes and the mass are enough.
106
- Estimate: upgrade mass 0.78 against a bar of 0.84, switching tax $0.66 at list prices, 1 vote(s) in a row, cache: candidate unknown, current warm.
107
- ```
18
+ In Claude Code:
108
19
 
109
- - **Upgrade mass** is the Jev confidence in a higher tier. It must reach the
110
- bar.
111
- - **The bar** grows with the switching tax: the cost to write the context
112
- into a cold cache. Here Opus has no warm cache.
113
- - **Cache** is `warm`, `expired` or `unknown`. `unknown` means no response
114
- for that cache since the session started or the conversation got shorter.
115
- - **Dollars** are list prices. On a subscription plan, they show the relative
116
- cost only.
20
+ 1. Run `/plugin configure router`.
21
+ 2. Select the Jev API key option, enter the key, and save it.
22
+ 3. Check the band above the prompt: `▂▄▆█ Auto · ready`. On another model the session starts in Manual; run `/router auto` to route.
117
23
 
118
- ## Pin a tier
24
+ The key is stored as a sensitive plugin option. Do not paste it into a model conversation. The [configuration guide](configuration.md) covers optional settings and the old v0.8 migration.
119
25
 
120
- To run one turn on a fixed tier, type the tier skill before the prompt:
26
+ ## Read the status band
121
27
 
122
- ```text
123
- /router:high redesign the auth flow
124
- /router:micro rename foo to bar in this file
125
- ```
28
+ Router draws one line above the prompt. The line ends with a **Router** button that opens the pane. When the band is narrow, the less important parts drop first: classifier figures, then context and cache, then the reason. The tier and model always stay.
126
29
 
127
- The status line shows the reason `pinned`. Tool calls in that turn stay on the
128
- tier; the next prompt goes back to Jev.
30
+ ![Five band states: routed to high, two rows with the hover row, a pending pin, a missing classifier key, and Manual mode](router-band.svg)
129
31
 
130
- `/model <name>` also works, but it stops the routing for the rest of the
131
- session.
32
+ Read the first line of the picture from left to right:
132
33
 
133
- ## Read the decision log
34
+ - **Tier meter** `▂▄▆█`: one bar per tier, lit up to the current tier in its color, like signal strength.
35
+ - **Tier and model**: the route for this turn. **fallback** means Claude Code answered with another model.
36
+ - **Reason**: one or two words with a direction, such as `↑ jump`, `↓ downgrade`, `= fits`, or `… waiting to go down`.
37
+ - **Classifier support**: what Jev gave the switch against the bar the policy required.
38
+ - **ctx** and **cache**: context use and cache reuse on the last reply. They turn yellow at 60% context and red at 80%.
134
39
 
135
- The gateway writes one JSON line for each routed request to
136
- `~/.claude/plugins/data/router-alexei-led-claude-router/decisions.jsonl`. The
137
- log has no prompt text.
40
+ | Band shows | Meaning |
41
+ | ------------------------------------------- | ------------------------------------------------------------------------------------- |
42
+ | `Auto · ready` | Auto mode is ready for a new turn. |
43
+ | `choosing for this turn…` | The classifier and local policy are running. The spinner says `Choosing model`. |
44
+ | `⏵ next turn: high ✕` | A pin is set. **✕** cancels it. |
45
+ | `⚠ Jev key not set · keeping model` | No key is available. **Set key** opens the secure plugin dialog. |
46
+ | `⚠ Jev timed out · keeping model` | The classifier failed: timed out, unreachable, rejected the key, or paused. |
47
+ | `○ Router off · keeping …` | Manual mode. **Auto** resumes routing. The footer also shows `router off`. |
48
+ | `✕ Router unavailable` | Nothing routes: an old Claude Code or leftover v0.8 settings. **Fix** opens the pane. |
49
+ | `○ Router · subagents keep their own model` | You are viewing a subagent's transcript, which Router does not route. |
138
50
 
139
- | Field | Content |
140
- | -------------- | ---------------------------------------------------------------------------------- |
141
- | `tier` | The tier of the request. |
142
- | `model`, `effort` | The model id and the effort that the gateway sent. `effort` is `null` for a model without effort. |
143
- | `reason` | The rule that decided. Tool calls show `tool-continuation`. `error`: routing failed and the default tier served. |
144
- | `advice` | The Jev probabilities for each tier, and for "continues the task". |
145
- | `estimate` | The numbers of a vote: confidence, bar, switching tax, cache state. |
146
- | `shadow` | The cost of the Jev choice against the current route. The downgrade tax uses the same arithmetic. |
147
- | `observed` | The usage of the response: model, effort, context tokens, cache reads, output. |
148
- | `failed` | Anthropic answered a routed turn with an error: status, tier, model, effort. |
149
- | `historyBreak` | A compaction or a rewind. The votes and the cache estimates reset. |
150
- | `cacheReset` | The context shrank by more than 20%. The cache estimates reset. |
51
+ Hover over the band for a second row: pin a tier for the next turn, switch to Manual, or show two rows. The two-row band adds a strip of recent replies colored by tier, the switch count, the switch tax, and the cache saving. Router remembers that choice across sessions. When Router changes the model between turns, a toast shows the old and new model and the reason. A pin does not raise one, and neither does a change of effort alone.
151
52
 
152
- Two useful queries:
53
+ The band steps aside while a survey needs the space.
153
54
 
154
- ```sh
155
- LOG=~/.claude/plugins/data/router-alexei-led-claude-router/decisions.jsonl
156
- jq -r 'select(.observed) | .observed.model' $LOG | sort | uniq -c # requests by model
157
- jq -r 'select(.reason) | .reason' $LOG | sort | uniq -c | sort -rn # decisions by reason
158
- jq -c 'select(.failed) | .failed' $LOG # failed turns
159
- ```
55
+ Tool continuations do not trigger another classification. Subagent choices remain unchanged.
56
+
57
+ ## Open the router pane
58
+
59
+ Run `/router` or select **Router** above the prompt. Without a UI surface, as in `claude -p`, `/router` prints a short status instead. The pane has four tabs. Select a tab or press its digit while the pane has focus.
60
+
61
+ ![The Now tab: the route and reason, classifier support per tier with pin buttons, recent replies by tier, and context, cache and cost](router-pane-now.svg)
62
+
63
+ The **Now** tab answers "what runs next turn, and why". The ladder lists the tiers from strongest to cheapest with the route each one uses. The bar is the support the classifier gave that tier on the last turn. The line under the ladder compares the support for a switch with the bar the policy required and shows the estimated switch tax. **pin** forces that tier for the next turn only.
64
+
65
+ ![The Tiers tab: model and effort per tier, the baseline tier, how each step up is priced, and the router.json change to save](router-pane-tiers.svg)
66
+
67
+ The **Tiers** tab edits the routes. In the picture, `medium` was changed to Sonnet 5.5 at `xhigh`: the tier shows **●**, the switch-cost lines now price `medium → high` as a model change, and the diff lists the one `router.json` line that **Save routes** will write. [Edit tiers](#edit-tiers) explains the controls.
68
+
69
+ | Tab | What it shows |
70
+ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------- |
71
+ | 1 Now | The current tier, model, and reason; Jev's support for each tier with a **pin** button; the last 30 replies by tier; context and cache. |
72
+ | 2 Tiers | The model and effort for each tier, the baseline tier, the cache cost of each step up, and the `router.json` change to save. |
73
+ | 3 Tuning | Jev deadline, downgrade votes, payback horizon, credits cap, the Jev key, and the `router.json` path. |
74
+ | 4 Usage | Claude-reported cost, context and cache detail, input per reply, quota, and configured-price estimates. |
75
+
76
+ **Auto** and **Manual: keep /model** stay at the top of every tab. **?** shows what the estimates leave out.
77
+
78
+ ### Understand usage and estimates
79
+
80
+ - **Cost** comes from Claude Code's native usage API. If the account is on a plan, a configured list-price estimate is not the subscription cash charge.
81
+ - **Context** compares the larger available context reading with the routed model's configured window. The router reserves 20% of that window. Values can be unknown when Claude does not provide the needed estimate.
82
+ - **Cache** reuse is cache-read tokens divided by the last response's input counters.
83
+ - **Jev support** is the probability Jev gave each tier on the last classified turn. The line under it compares the support for a switch with the bar the policy required, and shows the estimated switch tax.
84
+ - **Replies** colors each of the last 30 main-conversation replies by the tier that served it. A dot marks a reply the router did not choose, such as one in Manual mode.
85
+ - **Input per reply** scales the last 30 input sizes from the lowest to the highest reading. It is a scale comparison, not a forecast.
86
+ - **Cache read benefit** is a configured-price estimate for cached reads before write costs. It is not a measured saving.
87
+ - **Next-turn difference** compares the candidate with the current model under five-minute and one-hour cache-write scenarios. A negative number means the candidate is estimated to cost less for that request.
88
+ - **Payback** estimates later turns to recover an initial difference under assumed future cache reads and the last observed output size. It does not guarantee savings.
89
+
90
+ There is no router-side spend or savings ledger. The pane does not include Jev charges. Claude's native `/cost` is the source for its reported API cost.
91
+
92
+ ## Change routing
93
+
94
+ | Command or action | Result |
95
+ | ---------------------------------------- | --------------------------------------------------------------------------- |
96
+ | `/router` | Open the pane. |
97
+ | `/router auto` | Resume automatic routing. |
98
+ | `/router off` | Enter Manual mode and preserve Claude's selected model. |
99
+ | `/router pin <micro\|low\|medium\|high>` | Pin the next turn and its tool continuations. Auto must already be enabled. |
100
+ | `/model <name>` | Select a model and enter Manual mode. Use `/router auto` to resume. |
101
+ | **Auto** / **Manual: keep /model** | The same as `/router auto` and `/router off`. |
102
+ | **pin** on the Now tab | Pin that tier for the next turn. Auto must already be enabled. |
103
+
104
+ A pin does not change the next turn after the pinned turn finishes. A fresh session on the baseline model starts in Auto. A fresh session on another model starts in Manual. `/clear` starts the new session in Auto. Resuming a saved session restores its saved Auto or Manual mode.
105
+
106
+ ## Edit tiers
107
+
108
+ On the **Tiers** tab, pick a model and an effort for any tier. The model list comes from the aliases in `router.json` `models`, limited by the `availableModels` setting. `session` keeps the effort Claude Code sends. A model without effort levels, such as Haiku, shows `none`.
109
+
110
+ Changed tiers show **●**. The tab lists the `router.json` lines that **Save routes** will write. **Discard** drops the draft. **Reset to defaults** loads the built-in routes; saving then removes your route overrides from `router.json`. A saved change applies from the next turn.
111
+
112
+ **Switch cost** reads the draft from the bottom tier up and shows how the policy prices each step. A model change is priced as a cold cache write. An effort change on the same model is also priced as a new messages cache; whether the API actually keeps the cache across an effort change is not measured. Two identical tiers make that step change nothing.
113
+
114
+ A new model ID needs an entry in `router.json` `models` with its price, context window, and effort levels. See [Configuration](configuration.md).
115
+
116
+ ## Tune future decisions
117
+
118
+ On the **Tuning** tab, pick the values, then select **Save tuning**:
119
+
120
+ - **Jev deadline:** 500, 1,000, 1,500, or 3,000 ms for the total advice attempt, including any retry.
121
+ - **Votes to go down:** 1, 2, or 3 consecutive votes before a cheaper tier.
122
+ - **Payback horizon:** 1, 3, 5, or 10 later turns used by the downgrade estimate.
123
+ - **Credits cap:** $0.50, $1, $2, or $5 for an estimated cold cache write on a `credits` model.
160
124
 
161
- `scripts/transcript-models.sh <transcript.jsonl>` shows the model of each
162
- assistant message in a Claude Code transcript.
125
+ The current turn keeps the settings it started with. A save preserves unrelated `router.json` keys and refuses to write through a symlink. When validation fails, the pane names the setting and leaves the file unchanged. **Set Jev key** or **Edit key** opens Claude Code's secure plugin configuration.
163
126
 
164
- ## Update
127
+ ## Move from v0.8 gateway setup
165
128
 
166
- 1. Update the marketplace and the plugin:
129
+ The v1 plugin has the same plugin ID, `router@alexei-led-claude-router`, but it does not start the v0.8 local gateway. With auto-update on, Claude Code installs v1 at the next start. Before the first v1 session:
167
130
 
168
- ```sh
169
- claude plugin marketplace update alexei-led-claude-router
170
- claude plugin update router@alexei-led-claude-router
171
- ```
131
+ 1. Update the plugin: `claude plugin marketplace update alexei-led-claude-router`, then `claude plugin update router@alexei-led-claude-router`.
132
+ 2. Remove the settings that v0.8 `/router:setup` wrote. The [migration checklist](configuration.md#convert-a-v08-configuration) lists them: the `jev-router[1m]` model and picker row, the loopback `ANTHROPIC_BASE_URL`, the hint header, and the router status line.
133
+ 3. Convert `router.json` if you created one.
134
+ 4. Restart Claude Code with a full baseline model, such as `claude-sonnet-5-5`.
172
135
 
173
- 2. Restart Claude Code. The next prompt replaces the running gateway.
174
- 3. Run `/router:setup` once. The status line command contains the plugin
175
- version.
136
+ Keep the plugin enabled: in v1 it is the Mod. The Jev key option keeps its saved value. If the band reads `v0.8 gateway settings remain`, step 2 is incomplete.
176
137
 
177
- ## Stop using the router
138
+ ## Update or stop
178
139
 
179
- 1. In `~/.claude/settings.json`, remove `model`, `env.ANTHROPIC_BASE_URL`,
180
- `env.ENABLE_TOOL_SEARCH`, `env.CLAUDE_CODE_GATEWAY_HINT_HEADERS` and the
181
- `jev-router[1m]` row of `modelPicker.options`.
182
- 2. If setup changed your status line, restore the old command.
183
- 3. Restart Claude Code.
184
- 4. To remove the plugin, run
185
- `claude plugin uninstall router@alexei-led-claude-router`.
140
+ Claude Code updates a marketplace install at startup when auto-update is on for the marketplace. To update now, run `claude plugin marketplace update alexei-led-claude-router`, then `claude plugin update router@alexei-led-claude-router`, and restart. For a local checkout, update the files and restart Claude Code with the same `--plugin-dir`.
186
141
 
187
- The gateway stops by itself after two hours without requests.
142
+ To stop routing for a session, run `/router off`. To stop loading the Mod, run `claude plugin disable router@alexei-led-claude-router`, or restart without `--plugin-dir` for a checkout. The Mod keeps no session ledger and starts no process.
188
143
 
189
144
  ## Troubleshooting
190
145
 
191
- | Symptom | Cause | Fix |
192
- | ----------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------ |
193
- | "There's an issue with the selected model (jev-router[1m])" | The session started before the restart. | Restart Claude Code. |
194
- | Claude Code rejects `jev-router` | The session does not use the gateway. | Run `/router:setup`, then restart Claude Code. |
195
- | The status line shows `gateway off` after the next prompt | The gateway cannot start, for example because `router.json` has an unknown key. | Run `/router:status` to see the error. Read `gateway.log` next to `decisions.jsonl`. |
196
- | Every turn has the reason `no-advice` | No Jev key, or Jev fails. | Run `/router:status`. Read the `router:` lines in `gateway.log`. |
197
- | The effort is not the effort that you set | The model does not accept that effort. | The gateway uses the nearest lower level. Haiku has no effort and no thinking. |
198
- | 429 or 529 errors | Anthropic rate limits or overload. | Claude Code waits and tries again. The gateway sends these errors through unchanged. |
199
- | A `router.json` change has no effect | The gateway reads the configuration at start. | Run `pkill -f scripts/gateway.mjs`. The next prompt starts a new gateway. |
200
-
201
- To see if the gateway runs, open `http://127.0.0.1:43170/v1/models`. The list
202
- shows the alias.
146
+ | Symptom | Cause | Fix |
147
+ | ----------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
148
+ | Status says the Jev key is missing | The plugin option is unset or unavailable to this process. | Select **Set Jev key** in the pane, or run `/plugin configure router`. Save the option and start a new turn. |
149
+ | Route stays on the current model | Jev timed out, failed, is paused, or network policy refused the request. | Read the status band and the pane header. Network policy refusal is not bypassed. |
150
+ | `/model` changed but routing stopped | Choosing a model enters Manual mode. | Run `/router auto` to resume automatic routing. |
151
+ | Router reports invalid configuration | `router.json` is invalid, or project/local settings redirect the router profile. | Inspect `router.json`, remove project/local `HOME` or `CLAUDE_CONFIG_DIR` overrides, or run the [migration command](configuration.md#convert-a-v08-configuration). |
152
+ | Router says old settings need migration | `router.json` still contains v0.8 gateway keys. | Run the [migration command](configuration.md#convert-a-v08-configuration). |
153
+ | Band reads `v0.8 gateway settings remain` | The `jev-router[1m]` model or the `127.0.0.1:43170` base URL is still set. | Run `/router`: it lists the keys. Remove them as in the [migration checklist](configuration.md#convert-a-v08-configuration) and restart. |
154
+ | Router controls are unavailable | Claude Code is older than 2.1.289. | Update Claude Code. |
155
+ | Context reads as unknown | The router lacks a reliable local estimate or current-history measurement. | Keep using the current model, or start a new history with a supported context estimate. |
156
+
157
+ For the internal event flow and network deadline behavior, see [Architecture](architecture.md). For what the test traces do and do not show, see [Evaluation](evaluation.md).
package/hooks/hooks.json CHANGED
@@ -1,28 +1,3 @@
1
1
  {
2
- "hooks": {
3
- "SessionStart": [
4
- {
5
- "hooks": [
6
- {
7
- "type": "command",
8
- "command": "node",
9
- "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/ensure-gateway.mjs"],
10
- "timeout": 10
11
- }
12
- ]
13
- }
14
- ],
15
- "UserPromptSubmit": [
16
- {
17
- "hooks": [
18
- {
19
- "type": "command",
20
- "command": "node",
21
- "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/ensure-gateway.mjs", "--quiet"],
22
- "timeout": 10
23
- }
24
- ]
25
- }
26
- ]
27
- }
2
+ "modules": ["./native-router.mjs"]
28
3
  }