/brouter (bro)
Mechanics live in the @broject/brouter package. bro is the rig
(workflow, fleet, review loop); the router is the other half — it serves
the model catalog and drives the agents behind it.
The thin-client adapters — rendering the catalog in each client's own
vocabulary (Claude Code's modelPicker and its kin) — are
@broject/client-adapters, a separate package (spec bro-0ykhg.6): they
break on CLIENT releases, not on routing changes. See the
client-adapters skill; bro router client … mounts them beside this
surface.
The boundary
| Owns |
bro |
brouter |
client-adapters |
| the served catalog (which models, which lane) |
reads it |
owns it |
reads it |
| the client adapters (the model block per client) |
— |
— |
owns it |
the protocol clients (an ACP client, ask) |
— |
owns it |
— |
| the gateway itself |
bro serve (until the move) |
brouter serve (later) |
— |
| the agent workflow (skills, hooks, fleet, beads) |
owns it |
— |
— |
One-way: bro depends on brouter, client-adapters depends on brouter —
never the reverse. Both run without beads, without the bus, without a
git repo.
The honest id
The router serves the truth; the id is <entry>/<model> — no protocol,
no re-spelling. A label is a label; the id is what the client sends.
What a CLIENT does with that id (its own filter, its own picker) is the
adapter's business — the router never renames a model to survive a
client's filter.
Commands
| Command |
What it does |
brouter models [--json] |
the served catalog, read off the running router |
brouter clients [--json] |
the agent clients — installed / configured / connector / ready |
brouter client … |
moved — prints bro router client … (@broject/client-adapters) |
brouter store path | migrate | stats [--path P] [--json] |
the router's own ledger — where it lives, what it holds |
brouter routes list | validate [--routes P] |
the route table — the routes, or the problems |
brouter health [--json] [--path P] |
what can serve right now — the walls and the open sessions |
brouter route "<task>" [--routes P] [--type T] [--complexity C] [--priority P] [--json] |
which route serves this task — the route, the chain, and the why |
brouter ask "<question>" [--provider P] [--model M] [--explain[=SLICES]] |
ask one agent — --explain says which agent served, which model, and what it cost |
bro router … |
the same surfaces plus client <id> — bro's spelling (the wrapper) |
The explain surface
--explain answers WHY a request went where it went. The vocabulary is
SLICES, not levels — the user asks questions, so the flag names them:
| Slice |
What it answers |
route |
the route, the chain, the candidates, every reject with its reason |
model |
the model that serves, and who pinned it (you, the route, the entry) |
health |
what the router knew at decision time — the walls, the sessions |
cost |
the turn's context and cost, and the ledger's window counters |
--explain — every slice. --explain=route,model — only those.
brouter route --explain → stdout (the explanation IS the output).
brouter ask --explain → stderr (stdout stays the answer, pipeable);
bro loop --explain → stderr (stdout stays the run log).
- An unknown cost says unknown, never
0 — a provider that reports no
cost is unknown, not free. Token counts are labelled reported or
estimated.
brouter ask routes through the table when one is declared: the chain's
first acp entry serves, --provider still wins, and with no table the
first acp entry answers. The explanation names WHICH rule fired.
The route table
A route says WHICH models a task may land on and WHEN it fits. The table
is TOML (kind = "route", version = 1); the md beside it is prose for
the decision model, never a second schema.
kind = "route"
version = 1
[routes.edit]
match = { type = "edit" }
chain = [{ provider = "devin-acp", model = "swe-2-max" }]
match — the task's shape: type, complexity, priority. A route
that pins a field needs the task to carry it; a route that pins nothing
fits every task.
chain — the models, in order, as the honest <entry>/<model> ids the
router serves. devin-acp serves the swe-2 family: swe-2-max is the
id devin's model list carries (the ACP lane's own catalog advertises
the base id swe-2-high, and the -max composite pins it with the max
thinking level), while devin-acp/claude-opus-5 is not a model of that
lane at all. A route whose chain contradicts what brouter.models
declares for that provider is a config error (routes validate names
it), never a silently skipped route.
onWall — park or fallthrough, the fleet's vocabulary.
- the table's path:
brouter.routes in bro.config.json (or --routes).
The DECISION MODEL picks the route; the chain and the health are the
code's. It is a judge (brouter.router.provider + mode): either a
lane the operator configured, or a model the ROUTER SERVES — proxied
through the router's own gateway, so jev, openai or anthropic can all
decide. A proxied model answers in prose (the gateway has no
/v1/systemone route), so it journals in shadow and is refused under
enforce.
Config
brouter.models (bro.config.json) is the operator's model list — the
model→lane registry (spec bro-n1p0s); it is the served catalog's
whitelist as of the router's second milestone.
1---23name: brouter4description: "Use when the model list a client shows is wrong, filtered, or empty — the router's served catalog, `bro router`, the route table and explain surface, or the brouter package boundary. Client model blocks (claude-code pilot) live in the client-adapters skill. Mechanics live in @broject/brouter; this skill carries the contract and policy only."5metadata:6 source: https://skillmd.com/skills/theplenkov/brouter7---89# /brouter (bro)1011**Mechanics live in the `@broject/brouter` package.** bro is the rig12(workflow, fleet, review loop); the router is the other half — it serves13the model catalog and drives the agents behind it.1415The thin-client adapters — rendering the catalog in each client's own16vocabulary (Claude Code's `modelPicker` and its kin) — are17`@broject/client-adapters`, a separate package (spec bro-0ykhg.6): they18break on CLIENT releases, not on routing changes. See the19`client-adapters` skill; `bro router client …` mounts them beside this20surface.2122## The boundary2324| Owns | bro | brouter | client-adapters |25| ------------------------------------------------ | ---------------------------- | ----------------------- | --------------- |26| the served catalog (which models, which lane) | reads it | owns it | reads it |27| the client adapters (the model block per client) | — | — | owns it |28| the protocol clients (an ACP client, `ask`) | — | owns it | — |29| the gateway itself | `bro serve` (until the move) | `brouter serve` (later) | — |30| the agent workflow (skills, hooks, fleet, beads) | owns it | — | — |3132One-way: **bro depends on brouter, client-adapters depends on brouter —33never the reverse.** Both run without beads, without the bus, without a34git repo.3536## The honest id3738The router serves the truth; the id is `<entry>/<model>` — no protocol,39no re-spelling. A label is a label; the id is what the client sends.40What a CLIENT does with that id (its own filter, its own picker) is the41adapter's business — the router never renames a model to survive a42client's filter.4344## Commands4546| Command | What it does |47| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |48| `brouter models [--json]` | the served catalog, read off the running router |49| `brouter clients [--json]` | the agent clients — installed / configured / connector / ready |50| `brouter client …` | moved — prints `bro router client …` (@broject/client-adapters) |51| `brouter store path \| migrate \| stats [--path P] [--json]` | the router's own ledger — where it lives, what it holds |52| `brouter routes list \| validate [--routes P]` | the route table — the routes, or the problems |53| `brouter health [--json] [--path P]` | what can serve right now — the walls and the open sessions |54| `brouter route "<task>" [--routes P] [--type T] [--complexity C] [--priority P] [--json]` | which route serves this task — the route, the chain, and the why |55| `brouter ask "<question>" [--provider P] [--model M] [--explain[=SLICES]]` | ask one agent — `--explain` says which agent served, which model, and what it cost |56| `bro router …` | the same surfaces plus `client <id>` — bro's spelling (the wrapper) |5758## The explain surface5960`--explain` answers WHY a request went where it went. The vocabulary is61SLICES, not levels — the user asks questions, so the flag names them:6263| Slice | What it answers |64| -------- | -------------------------------------------------------------------- |65| `route` | the route, the chain, the candidates, every reject with its reason |66| `model` | the model that serves, and who pinned it (you, the route, the entry) |67| `health` | what the router knew at decision time — the walls, the sessions |68| `cost` | the turn's context and cost, and the ledger's window counters |69- `--explain` — every slice. `--explain=route,model` — only those.70- `brouter route --explain` → stdout (the explanation IS the output).71 `brouter ask --explain` → stderr (stdout stays the answer, pipeable);72 `bro loop --explain` → stderr (stdout stays the run log).73- An unknown cost says **unknown**, never `0` — a provider that reports no74 cost is unknown, not free. Token counts are labelled `reported` or75 `estimated`.76- `brouter ask` routes through the table when one is declared: the chain's77 first acp entry serves, `--provider` still wins, and with no table the78 first acp entry answers. The explanation names WHICH rule fired.7980## The route table8182A route says WHICH models a task may land on and WHEN it fits. The table83is TOML (`kind = "route"`, `version = 1`); the md beside it is prose for84the decision model, never a second schema.8586```toml87kind = "route"88version = 18990[routes.edit]91match = { type = "edit" }92chain = [{ provider = "devin-acp", model = "swe-2-max" }]93onWall = "fallthrough"94```9596- `match` — the task's shape: `type`, `complexity`, `priority`. A route97 that pins a field needs the task to carry it; a route that pins nothing98 fits every task.99- `chain` — the models, in order, as the honest `<entry>/<model>` ids the100 router serves. `devin-acp` serves the swe-2 family: `swe-2-max` is the101 id devin's model list carries (the ACP lane's own catalog advertises102 the base id `swe-2-high`, and the `-max` composite pins it with the max103 thinking level), while `devin-acp/claude-opus-5` is not a model of that104 lane at all. A route whose chain contradicts what `brouter.models`105 declares for that provider is a config error (`routes validate` names106 it), never a silently skipped route.107- `onWall` — `park` or `fallthrough`, the fleet's vocabulary.108- the table's path: `brouter.routes` in `bro.config.json` (or `--routes`).109110The DECISION MODEL picks the route; the chain and the health are the111code's. It is a judge (`brouter.router.provider` + `mode`): either a112lane the operator configured, or a model the ROUTER SERVES — proxied113through the router's own gateway, so jev, openai or anthropic can all114decide. A proxied model answers in prose (the gateway has no115`/v1/systemone` route), so it journals in `shadow` and is refused under116`enforce`.117118## Config119120`brouter.models` (bro.config.json) is the operator's model list — the121model→lane registry (spec bro-n1p0s); it is the served catalog's122whitelist as of the router's second milestone.