@alexeiled/claude-router 1.15.0 → 1.17.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.
@@ -0,0 +1,222 @@
1
+ # Providers
2
+
3
+ Claude Router routes models and effort within the provider that Claude Code already uses.
4
+ Set a provider name and give the router a matching JSON file. No provider-specific plugin or proxy is needed.
5
+
6
+ **Built-in profiles:** Anthropic, DeepSeek and z.ai.
7
+ **Custom profiles:** OpenRouter, Ollama, other local servers, and other hosted providers with a Claude Code-compatible Anthropic endpoint.
8
+ Custom profiles need their own model settings. They do not inherit Claude models.
9
+
10
+ This guide assumes Claude Code already works with your provider. Endpoint and credential setup are outside its scope.
11
+
12
+ ## Select a provider
13
+
14
+ For DeepSeek, create `deepseek-router.json` in your Claude Code profile directory with this content:
15
+
16
+ ```json
17
+ {}
18
+ ```
19
+
20
+ Then start Claude Code:
21
+
22
+ ```sh
23
+ CLAUDE_ROUTER_PROVIDER=deepseek claude --model 'deepseek-flash[1m]'
24
+ ```
25
+
26
+ The empty file enables DeepSeek's built-in defaults. Change only the settings you want to override.
27
+
28
+ If you prefer a command-line flag, use Claude Code's existing `--settings` flag:
29
+
30
+ ```sh
31
+ claude --settings '{"env":{"CLAUDE_ROUTER_PROVIDER":"deepseek"}}' --model 'deepseek-flash[1m]'
32
+ ```
33
+
34
+ There is no separate `--provider` flag. A launcher can set `CLAUDE_ROUTER_PROVIDER` for each launch.
35
+
36
+ ### Name-to-file mapping
37
+
38
+ The directory is `CLAUDE_CONFIG_DIR` when set, otherwise `~/.claude`.
39
+
40
+ | Provider name | Router file | Built-in model defaults |
41
+ | --- | --- | --- |
42
+ | Unset, empty, or `anthropic` | `router.json` | Haiku 5.5, Sonnet 5.5, Opus 5.5 |
43
+ | `deepseek` | `deepseek-router.json` | DeepSeek Flash |
44
+ | `zai` | `zai-router.json` | GLM-5.3-Flash, GLM-5.3 |
45
+ | `openrouter` | `openrouter-router.json` | None. Supply a complete profile. |
46
+ | `ollama` | `ollama-router.json` | None. Supply a complete profile. |
47
+ | Any other valid name | `<provider>-router.json` | None. Supply a complete profile. |
48
+
49
+ Names are local profile identifiers, not a provider registry or an endpoint lookup.
50
+ For example, `minimax`, `kimi`, `mimo`, or `local` can name a custom profile.
51
+ Names must start with a lowercase letter, contain only lowercase letters, digits and hyphens, and have at most 64 characters.
52
+
53
+ **Setting the name does not change Claude Code's endpoint, credentials or billing product.**
54
+ The router neither detects providers from URLs nor switches endpoints between turns.
55
+
56
+ ### File rules
57
+
58
+ - A non-Anthropic profile file must exist. Only the Anthropic profile can run without a file.
59
+ - Missing or invalid files produce a warning and leave Claude Code's model and effort unchanged.
60
+ - The router never falls back from a selected provider file to `router.json`.
61
+ - Profiles are independent. Classifier, policy and route overrides in `router.json` do not carry over.
62
+ - Selection is fixed for the session. The pane shows the selected file and writes Save/Undo changes there.
63
+ - Project and local settings cannot redirect the profile with `CLAUDE_ROUTER_PROVIDER`, `CLAUDE_CONFIG_DIR`, or `HOME`.
64
+
65
+ Select a classifier separately. Using Ollama to run your coding model does not also select Ollama as the classifier.
66
+ For an all-local setup, [configure the Ollama classifier](user-guide.md#use-ollama) in your local provider profile.
67
+
68
+ ## Built-in defaults
69
+
70
+ Anthropic is the default when no provider name is set.
71
+ DeepSeek and z.ai require their named files, even when you want only defaults.
72
+ A file containing `{}` is enough for either.
73
+
74
+ ### Model IDs
75
+
76
+ | Profile | Alias | Model ID |
77
+ | --- | --- | --- |
78
+ | Anthropic | `haiku` | `claude-haiku-5-5` |
79
+ | Anthropic | `sonnet` | `claude-sonnet-5-5` |
80
+ | Anthropic | `opus` | `claude-opus-5-5` |
81
+ | DeepSeek | `flash` | `deepseek-flash[1m]` |
82
+ | z.ai | `flash` | `glm-5.3-flash[1m]` |
83
+ | z.ai | `glm` | `glm-5.3[1m]` |
84
+
85
+ `[1m]` is a Claude Code context hint, not a different served model.
86
+ Changing Claude Code's model-slot environment variables does not update this catalog.
87
+ If you use different models, update their IDs and metadata in the selected router file.
88
+
89
+ ### Default routes
90
+
91
+ Each cell is `model alias · effort`. All profiles start at tier `low`.
92
+
93
+ | Profile | `micro` | `low` | `medium` | `high` |
94
+ | --- | --- | --- | --- | --- |
95
+ | Anthropic | haiku · medium | haiku · high | opus · medium | opus · xhigh |
96
+ | DeepSeek | flash · low | flash · high | flash · high | flash · max |
97
+ | z.ai | flash · low | flash · high | glm · high | glm · max |
98
+
99
+ A provider can use one model at several efforts. Two tiers can also share the same model and effort.
100
+
101
+ ### Activity overrides
102
+
103
+ With activity routing on, these cells replace the base route. Other cells keep the base route.
104
+
105
+ | Profile | Activities | Tier | Route |
106
+ | --- | --- | --- | --- |
107
+ | Anthropic | `code`, `debug`, `plan`, `review` | `low` | sonnet · high |
108
+ | Anthropic | `ops` | `medium` | haiku · high |
109
+ | DeepSeek | `code`, `debug`, `plan`, `review` | `medium` | flash · max |
110
+ | z.ai | `code`, `debug`, `plan`, `review` | `medium` | glm · max |
111
+ | z.ai | `ops`, `explore`, `docs` | `medium` | flash · high |
112
+ | z.ai | `ops`, `explore`, `docs` | `high` | flash · max |
113
+
114
+ GLM-5.3 is text-only. Image-bearing history excludes it when the router can select a compatible route.
115
+ The default models all have a 1M-token context window.
116
+
117
+ Subagent routing is on for built-in profiles:
118
+
119
+ | Profile | Light | Standard | Heavy |
120
+ | --- | --- | --- | --- |
121
+ | Anthropic | haiku | sonnet | opus |
122
+ | DeepSeek | flash | flash | flash |
123
+ | z.ai | flash | glm | glm |
124
+
125
+ Subagents receive a model at spawn, not a routed effort. Their own effort setting still applies.
126
+
127
+ These defaults are starting policies, not measured quality or savings guarantees.
128
+ See [the evidence and limits](evaluation.md#provider-profiles).
129
+ For prices and cache settings, see [the configuration reference](configuration.md#provider-profiles).
130
+
131
+ ## Add another provider
132
+
133
+ No code change or provider registration is needed.
134
+ Choose a name, create its file, and set `CLAUDE_ROUTER_PROVIDER` to that name.
135
+
136
+ Unlike built-in profiles, a custom profile cannot use only `{}`.
137
+ Define all four routes and a complete model entry for each model they reference.
138
+ Custom profiles start with subagent routing off and automatic-cache accounting.
139
+
140
+ ### Example: two local models
141
+
142
+ Save the following as `ollama-router.json` in your Claude Code profile directory.
143
+ Replace the two placeholder IDs with models installed on your server.
144
+ Set each context window to the limit configured for that model.
145
+
146
+ This example assumes local models with no per-token charge and no exposed effort control.
147
+ The zero prices and 32K windows are example settings, not defaults for every Ollama model.
148
+
149
+ ```json
150
+ {
151
+ "models": {
152
+ "fast": {
153
+ "id": "your-fast-model",
154
+ "input": 0,
155
+ "output": 0,
156
+ "cacheRead": 0,
157
+ "contextWindow": 32768,
158
+ "billing": "plan",
159
+ "efforts": [],
160
+ "strength": 1,
161
+ "imageInput": false
162
+ },
163
+ "strong": {
164
+ "id": "your-strong-model",
165
+ "input": 0,
166
+ "output": 0,
167
+ "cacheRead": 0,
168
+ "contextWindow": 32768,
169
+ "billing": "plan",
170
+ "efforts": [],
171
+ "strength": 2,
172
+ "imageInput": false
173
+ }
174
+ },
175
+ "routes": {
176
+ "micro": { "model": "fast", "effort": null },
177
+ "low": { "model": "fast", "effort": null },
178
+ "medium": { "model": "strong", "effort": null },
179
+ "high": { "model": "strong", "effort": null }
180
+ },
181
+ "cache": { "mode": "disabled" }
182
+ }
183
+ ```
184
+
185
+ Start with the fast model, after replacing its placeholder ID:
186
+
187
+ ```sh
188
+ CLAUDE_ROUTER_PROVIDER=ollama claude --model your-fast-model
189
+ ```
190
+
191
+ `cache.mode` controls the router's cost estimates. It does not disable a server's internal cache.
192
+ Here it avoids assuming a billed prompt cache for the local models.
193
+
194
+ The same profile format works for OpenRouter or another hosted provider.
195
+ Use that provider's model IDs, supported efforts, context limits and actual token prices instead of the local example values.
196
+ Use `billing: "credits"` for token-billed models.
197
+ Set the [cache policy](configuration.md#provider-cache-behavior) to match the provider.
198
+
199
+ ### Model and effort rules
200
+
201
+ - Alias names such as `fast` and `strong` are yours to choose. Routes refer to aliases, not API IDs.
202
+ - `efforts` lists only the effort levels that Claude Code can send and the provider honors.
203
+ - With `efforts: []`, use `effort: null` in every route. This omits routed effort, not model thinking.
204
+ - With named efforts, use only levels listed for that model. API compatibility does not make effort names equivalent.
205
+ - `strength` orders models for routing. A higher price does not prove higher capability.
206
+ - Prices are USD per million tokens. Use zero only when there is no token charge.
207
+ - `imageInput` describes the model's actual input support, not the provider's general capabilities.
208
+
209
+ For the full schema, see [Configuration](configuration.md#optional-routerjson).
210
+ To enable custom subagent routes, also configure [subagent routing](configuration.md#subagent-routing).
211
+
212
+ ## Check the selected profile
213
+
214
+ 1. Open `/router` and check the provider name and file path.
215
+ 2. Start on a model used by a configured route, or run `/router auto`.
216
+ 3. Check that the band names the expected model and effort after a prompt.
217
+
218
+ If routing is unavailable, inspect the selected file first.
219
+ A typo in the provider name selects a different filename. It does not choose the default profile.
220
+
221
+ Changing a provider name requires a new session.
222
+ Pane edits stay within the selected profile and apply from the next turn.
@@ -36,18 +36,22 @@ names a mode other than balanced.
36
36
 
37
37
  A change applies from the next turn. It changes the route the router prefers; the route in use moves through the
38
38
  same checks as any other switch. On the same task a cheaper route waits until `minDwellRequests` requests have run on
39
- the route in use and a check (tests, build, lint) has passed since. A move must also pay back its cache write. Until
39
+ the route in use and a checkpoint since: a passed check (tests, build, lint), or the success the route's activity can
40
+ show ([Changes during a task](user-guide.md#changes-during-a-task)). A move must also pay back its cache write. Until
40
41
  then the band says why the route stays. Pin a tier to run its configured route now.
41
42
 
42
43
  ## Policy per mode
43
44
 
44
- Each mode except `balanced` replaces some `policy` fields while it is active. The built-in values come from
45
- codex-router and are **not tuned** on this router:
45
+ Each mode except `balanced` replaces some `policy` fields while it is active. The built-in values started as
46
+ codex-router's and are **not tuned** on outcomes. Since 1.16, `cost` upgrades on balanced's bar (2 votes from 0.75):
47
+ with 3 votes from 0.85, the cache write of a cold stronger model raised the bar to about 0.92 from 60k tokens and 0.97
48
+ at 250k, so a cost turn on Haiku kept a task the classifier scored hard at 90%. `cost` still moves down sooner than
49
+ `balanced` (one vote, 80% support, a 4-request dwell):
46
50
 
47
51
  ```json
48
52
  {
49
53
  "modes": {
50
- "cost": { "policy": { "upgradeVotes": 3, "upgradeBase": 0.85, "jumpConfidence": 0.98, "downgradeVotes": 1,
54
+ "cost": { "policy": { "upgradeVotes": 2, "upgradeBase": 0.75, "jumpConfidence": 0.98, "downgradeVotes": 1,
51
55
  "downgradeMass": 0.8, "minDwellRequests": 4, "escalationHoldTurns": 1 } },
52
56
  "quality": { "policy": { "upgradeVotes": 1, "upgradeBase": 0.6, "jumpConfidence": 0.9, "downgradeVotes": 3,
53
57
  "downgradeMass": 0.95, "minDwellRequests": 16, "escalationHoldTurns": 4 } }
@@ -9,6 +9,9 @@ claude plugin marketplace add alexei-led/claude-router
9
9
  claude plugin install router@alexei-led-claude-router
10
10
  ```
11
11
 
12
+ For another execution provider, follow [Providers](providers.md). That guide covers profile names, defaults and custom files.
13
+ The following startup example uses the default Anthropic profile.
14
+
12
15
  Start with the full baseline model so routing has a known starting point:
13
16
 
14
17
  ```sh
@@ -26,7 +29,10 @@ In Claude Code:
26
29
  3. To use another classifier, open the pane's **Classifier** tab and select its row. See [Choose the classifier](#choose-the-classifier).
27
30
  4. Check the band above the prompt: `Routing on · ready`. On a model that no tier routes to, and that no activity override uses with activity routing `on`, the session starts with routing off and the band says why; run `/router auto` to route.
28
31
 
29
- Keys are stored as sensitive plugin options. Do not paste them into a model conversation. The [configuration guide](configuration.md) covers optional settings and migrations.
32
+ Keys are stored as sensitive plugin options. Do not paste them into a model conversation. The [configuration guide](configuration.md) covers settings and migrations.
33
+
34
+ In this guide, `router.json` means the selected router file. For example, with `CLAUDE_ROUTER_PROVIDER=zai`, edits go to `zai-router.json`.
35
+ The pane shows its provider and file path.
30
36
 
31
37
  ## Read the status band
32
38
 
@@ -52,14 +58,14 @@ Read the first line of the picture from left to right:
52
58
  | `⚠ Clef: no account ID · keeping model` | Clef has its API token but no Cloudflare account ID. **Set up** opens the dialog. |
53
59
  | `⚠ Jev timed out · keeping model` | The classifier failed: timed out, unreachable, rejected the key, or paused. |
54
60
  | `○ Routing off [ Turn on ] · every turn uses …` | Routing is off: Claude's model answers every turn. **Turn on** turns it back on. The footer also shows `routing off`. |
55
- | `✕ Routing unavailable` | Nothing routes: an old Claude Code or leftover v0.8 settings. **Fix** opens the pane. |
61
+ | `✕ Routing unavailable` | Nothing routes: a missing/invalid provider file, an old Claude Code, or leftover v0.8 settings. **Fix** opens the pane. |
56
62
  | `○ Router · ■ Haiku 5.5 · moved down by the router` | You are viewing a subagent's transcript. The model it runs on, and who picked it; see below. |
57
63
 
58
64
  The band shows one routing control at a time. While routing is on, hover over the band for a second row: pin a tier for the next turn, **Turn off** routing, or show two rows. While routing is off, **Turn on** sits on the first line next to `Routing off` and stays at any width: a narrow band drops the explanation and the model first. On a narrow band the hover row drops `routing on`, then **2 rows**, then `pin next turn`, then the pins; it keeps **Turn off**, and **1 row** when the band shows two. The hover row needs a pointer: from the keyboard, run `/router off`, or open the pane and press `f`. The two-row band adds this session against your model, the one `/model` selects now: `session saved $1.84 (22%) vs Opus 5.5 · xhigh · 64 replies · cold-cache writes +$0.47`, or `session extra $2.48 (×5.0) vs Haiku 5.5 · high · 41 replies · stronger models +$2.31` when routing cost more. The last part names the larger of the two costs behind the result, when there is one. After a `/model` change the row shows the whole session against the new model. Before the tenth routed reply it reads `session 3 replies · too early to compare`. When the row is short, the cost part drops first, then the reply count. Router remembers that choice across sessions. When Router changes the model between turns, a toast reads `Model changed: old → new · reason`. A pin does not raise one, and neither does a change of effort alone.
59
65
 
60
66
  The band steps aside while a survey needs the space.
61
67
 
62
- Inside a turn the router checks the route again as the work changes; see [Changes during a task](#changes-during-a-task). A subagent gets at most one model, when it starts, and keeps it for every step: Haiku for exploration, Opus for clearly hard tasks, Sonnet for the rest. An agent that pins a model in its definition keeps it, unless it sets `modelRouting: auto`. The Usage tab's **SUBAGENTS** section shows what each agent type ran on and cost, and the Now tab shows this session's agents. See [Subagent routing](configuration.md#subagent-routing).
68
+ Inside a turn the router checks the route again as the work changes; see [Changes during a task](#changes-during-a-task). A subagent gets at most one model, when it starts, and keeps it for every step: For the Anthropic profile, these are Haiku for exploration, Opus for clearly hard tasks, and Sonnet for the rest. Other profiles have [their own defaults](providers.md#activity-overrides). An agent that pins a model in its definition keeps it, unless it sets `modelRouting: auto`. The Usage tab's **SUBAGENTS** section shows what each agent type ran on and cost, and the Now tab shows this session's agents. See [Subagent routing](configuration.md#subagent-routing).
63
69
 
64
70
  In a subagent's transcript the band names the model the agent runs on and who picked it. `■ Haiku 5.5 · moved down by the router · Claude Code: Opus 5.5` means the router chose a cheaper model than Claude Code would have; `up` means a stronger one. `□ Sonnet 5.5 · the router kept Claude Code’s pick` means the router agreed. `□ Opus 5.5 · Claude Code’s pick: the workflow sets it` means the router did not route the agent, and says why. A narrow band drops the `Claude Code:` part first. The band falls back to `subagent model chosen at spawn` when the router has no record of the agent, such as after a plugin reload, and to `subagents keep their own model` with subagent routing off.
65
71
 
@@ -194,12 +200,18 @@ The classifier labels a turn from its prompt, and the work can change after that
194
200
 
195
201
  - **On every later step of a turn** it reads the turn's tool calls. A turn labelled `ops` or `explore` that edits a code file moves at once to the tier's `code` route (`docs` when it edits only Markdown or `docs/` files). The tools are the evidence, so this needs no classifier support, and the cache cost does not hold it back; only the cash cap on a credits-billed model can. This move only goes up. The toast and the band show it as `↗ coding`.
196
202
  - **Every 4 requests inside a turn** (`policy.reviewEveryRequests`) it asks the classifier again, in the background, with the turn's prompt and the recent dialogue. A step never waits for the answer: it applies at the first step after it arrives. Each review sends the classifier the same kind of text a new turn does. `0` turns reviews off.
197
- - **A new prompt that continues the task**, such as a task notification, a message from another agent, or "go on", is decided the same way as a review.
203
+ - **A new prompt that continues the task** is decided the same way as a review. Claude Code stamps each prompt with where it came from. A task notification, an observer's report or a programmatic follow-up is always progress on the running task: the classifier is asked about your last request, with the notification as the newest dialogue line, so it judges the work still to do rather than the notification's wording. A message from you or another agent, or "go on", counts as the running task when the classifier scores it as a continuation. After a resume the router does not know your last request yet, so a notification is judged as it reads.
198
204
 
199
205
  On the running task:
200
206
 
201
207
  - A stronger tier takes the usual votes: two agreeing answers, or one for a clear two-tier jump. A stronger activity takes one answer whose probability clears the cache check. Repeated tool errors still escalate at once.
202
- - A cheaper tier or activity also waits for a checkpoint: at least 8 requests since the last model change (`policy.minDwellRequests`), and the last test, build, lint or type-check command since then passed. A check is a test runner, type checker or linter (`pytest`, `tsc`, `eslint`), or a launcher running one (`npm test`, `go test`, `make lint`), alone or after `&&`. A check piped into another command (`npm test | tail`), followed by `;` or `|| true`, or sent to the background does not count, because its exit status can hide a failure or is not known yet. While none ran, or the last one failed, the route stays: for a tier the band shows `… down after a passed check`; a held activity keeps the running one and shows `= fits`. A cheaper activity also needs 90% probability (`policy.downgradeMass`).
208
+ - A cheaper tier or activity also waits for a checkpoint: at least 8 requests since the last model change (`policy.minDwellRequests`), and a success since then that fits the work the route runs for. A passed test, build, lint or type-check always counts. A check is a test runner, type checker or linter (`pytest`, `tsc`, `eslint`), or a launcher running one (`npm test`, `go test`, `make lint`), alone or after `&&`. A check piped into another command (`npm test | tail`), followed by `;` or `|| true`, or sent to the background does not count, because its exit status can hide a failure or is not known yet. Without a passed check, the route's activity decides what counts:
209
+ - `ops`: the last command that ran something succeeded, with no file edit or delegated agent since.
210
+ - `docs`: the last edit succeeded and touched only Markdown, text or `docs/` files, with no command run beside it.
211
+ - `explore`, `plan`, `review`: a turn finished, nothing was edited, written, run or delegated, and the last tool result was not an error.
212
+ - `code`, `debug` and a route with no activity: only a passed check counts.
213
+
214
+ A failed check blocks every one of these, and so does a check whose result is not the check's own (chained, redirected, piped, after `;` or `||`, or in the background). While no checkpoint is met, the route stays: for a tier the band shows `… down after a checkpoint`; a held activity keeps the running one and shows `= fits`. A cheaper activity also needs 90% probability (`policy.downgradeMass`).
203
215
  - A cheaper tier lands where the answer as a whole points: when the classifier says `micro` 63% and `low` 30%, the turn moves to `low`, which 93% of the answer supports, instead of staying until `micro` alone reaches 90%.
204
216
  - A pinned turn does not move. A new task, a prompt the classifier does not score as a continuation, is routed as a fresh turn. Ollama does not answer the continuation question, so every prompt is a new task to it; reviews inside a turn still apply.
205
217
 
@@ -227,12 +239,17 @@ On the **Classifier** tab, **ACROSS SESSIONS · since the last reset** shows the
227
239
  | `/router activities <off\|on>` | Set the [activity routing](#route-by-activity) mode. Saved to `router.json` at once; **Undo** reverts it. |
228
240
  | `/router mode <cost\|balanced\|quality>` | Set this session's [routing mode](routing-modes.md) from the next turn. A resume keeps it. |
229
241
  | `/router mode default` | Clear the session's mode: the project's or the profile's applies again. |
242
+ | `/router decisions [n]` | Print this session's last `n` routing decisions, 20 by default. See [Routing decisions](#routing-decisions). |
230
243
  | `/model <name>` | Select a model and turn routing off. Use `/router auto` to turn it back on. |
231
244
  | **Turn on** / **Turn off** on the band | The same as `/router auto` and `/router off`. |
232
245
  | **on** / **off** on the pane (`o` / `f`) | The same as `/router auto` and `/router off`. |
233
246
  | **pin** on the Now tab | Pin that tier for the next turn. Routing on must already be enabled. |
234
247
 
235
- A routing mode moves each tier's route one step toward cost or quality; pins and `micro` turns are not moved. The band and the Now tab show the mode and where it comes from, such as `cost (session)`. A change applies from the next turn, and the route in use moves only through the usual checks, so on a running task a cheaper route can wait a few requests and for a passed test. **Mode** on the Policy tab sets the profile's mode. See [Routing modes](routing-modes.md).
248
+ A routing mode moves each tier's route one step toward cost or quality; pins and `micro` turns are not moved. The band and the Now tab show the mode and where it comes from, such as `cost (session)`. When the mode kept the cell's model and changed only its effort, as `cost` does for Opus at `high`, the band adds `effort only`: the cost estimates price the same tokens on both routes, so that change shows no difference there, though real output length can differ. A change applies from the next turn, and the route in use moves only through the usual checks, so on a running task a cheaper route can wait a few requests and for a checkpoint. **Mode** on the Policy tab sets the profile's mode. See [Routing modes](routing-modes.md).
249
+
250
+ ### Routing decisions
251
+
252
+ Each routed turn adds rows to the session's decision record in `$.store` (`decisions:v1:<session id>`): one when the turn starts, one per classifier review or tool-based move inside it, and one when it ends. A row holds the prompt's origin (`composer`, `task-notification`, …, or `unknown`), the classifier's tier and activity with their shares, whether it counted as the running task, the tier, activity, route and reason chosen, and at the end the turn's tool bucket and how many replies were priced. It holds no prompt, tool or file text. `/router decisions [n]` prints them. Each session keeps its newest 60 rows; records of the 20 most recent other sessions stay, for at most 30 days. **Delete history** deletes them all.
236
253
 
237
254
  A pin does not change the next turn after the pinned turn finishes. A fresh session on a model that a tier routes to, or with activity routing `on` a model an activity override uses (Sonnet 5.5 on the defaults), starts with routing on. A fresh session on any other model starts with routing off. `/clear` starts the new session with routing on. Resuming a saved session restores its saved routing on or off.
238
255
 
@@ -251,7 +268,11 @@ The model list comes from the aliases in `router.json` `models`, limited by the
251
268
 
252
269
  **Activity routing** at the top sets `off` or `on`, and says what the mode does. A yellow line says when the overrides do not run: activity routing `off`, or routing off or unavailable.
253
270
 
254
- Under the grid, `3 prompt caches in use` counts the caches the grid can run on. Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 keep one cache per model across efforts with an API key or a Claude subscription; on Amazon Bedrock, Google Cloud, Microsoft Foundry or a custom `ANTHROPIC_BASE_URL`, each (model, effort) pair has its own. Moving to a model without a warm cache writes the whole conversation into a new cache, which is the switch cost on the Now tab. More caches mean more of those writes. A yellow line flags two neighbouring tiers that run the same model and effort, since that step changes nothing.
271
+ The Routes tab describes the selected profile's cache policy. With Anthropic explicit caching, it counts the cache identities used by the routes. A model switch can require a cold write of the conversation.
272
+
273
+ Automatic-cache profiles, including DeepSeek and z.ai, do not assume a fixed lifetime or guaranteed sharing across efforts. They use hit/miss input prices without a separate write premium. See [cache settings](configuration.md#provider-cache-behavior).
274
+
275
+ A yellow line flags neighbouring tiers with the same model and effort. That step changes nothing.
255
276
 
256
277
  **Reset routes to defaults** (`r`) loads the built-in tier routes and start tier into the draft; **Save** then removes your route overrides from `router.json`. Activity edits and the mode stay in the draft.
257
278
 
@@ -304,7 +325,9 @@ The routing policy thresholds were tuned against Jev's probabilities. Clef's, Op
304
325
 
305
326
  ### Use Ollama
306
327
 
307
- Ollama runs the classifier on this machine, so the prompt text does not leave it. It needs no key.
328
+ This section configures Ollama as the **classifier**, not the model that answers your prompts. To route coding models on Ollama, use a [custom execution-provider profile](providers.md#add-another-provider).
329
+
330
+ Ollama runs the classifier on this machine, so classification text stays local. It needs no key.
308
331
 
309
332
  1. Install Ollama and pull a model: `ollama pull qwen3.5:9b`.
310
333
  2. Start the server: `ollama serve`. The router calls `http://127.0.0.1:11434`.
@@ -337,7 +360,9 @@ To stop routing for a session, run `/router off`. To keep tier routing but stop
337
360
  | Status says `no account ID` | Clef, Clef Flash or Clef Omni is active without the Cloudflare account ID. | Run `/plugin configure router` and save the Cloudflare account ID. |
338
361
  | Route stays on the current model | The classifier timed out, failed, is paused, or network policy refused it. | Read the status band and the pane header. Network policy refusal is not bypassed. |
339
362
  | `/model` changed but routing stopped | Choosing a model turns routing off. | Run `/router auto` to turn routing back on. |
340
- | 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-an-older-routerjson). |
363
+ | Selected provider file is missing | The provider name selects a file that does not exist. | Create that file in the active Claude Code profile directory. Use `{}` only for built-in profiles. See [Providers](providers.md). |
364
+ | A custom profile containing `{}` fails | No built-in model catalog exists for that provider name. | Define all four routes and their model entries. See the [custom profile example](providers.md#add-another-provider). |
365
+ | Router reports invalid configuration | The selected file is invalid, or project/local settings redirect the profile. | Inspect the file shown in the pane. Remove project/local `HOME`, `CLAUDE_CONFIG_DIR`, or `CLAUDE_ROUTER_PROVIDER` overrides. |
341
366
  | Router says old settings need migration | `router.json` still contains v0.8 gateway keys or the 1.1 `jev` section. | Run the [migration command](configuration.md#convert-an-older-routerjson). |
342
367
  | `⚠ OpenAI rejected the key · keeping model` | The OpenAI key is wrong, revoked, or lacks access to `gpt-6-luna`. | Run `/plugin configure router` and save a valid OpenAI API key. |
343
368
  | `⚠ Ollama unreachable · keeping model` | No Ollama server listens on `127.0.0.1:11434`. | Run `ollama serve`, then start a new turn. |