agent-router

agent-router decides which model runs each Claude Code subagent. You assign a model to five agent roles from the catalog your endpoint publishes, and the mod rewrites every Agent spawn to that exact model id, holds it through the child’s turns, and records what was requested, what was applied and what Claude actually started. It is for people who run Claude Code through a gateway, a proxy or a local server that serves more than Anthropic’s own models.

The “non-official models” in the repo’s description are simply whatever your endpoint lists under GET /v1/models: models behind a gateway, a server on localhost, or Anthropic’s API itself. Ids can carry provider prefixes or local paths. The mod ships no model and no provider; it discovers what the endpoint in ANTHROPIC_BASE_URL advertises and lets you pick from that.

What it does

• Five roles, each with its own model: scout (read-only code discovery), reviewer (code quality and security review, with read-only diff and history commands), security-reviewer (read-only vulnerability analysis), task (general delegated work) and sonic (mechanical updates and data collection). The role definitions are adapted from Oh My Pi under its MIT license. The same model can serve several roles.
• Aliases for Claude Code’s own agents: Explore goes to the scout role, general-purpose to the task role, and the built-in Plan keeps its definition but runs on the task model. A per-role assignment wins over the model the caller requested.
• /agent-models opens a pane with a search box over the catalog. Each entry shows its exact id and the context and output limits the endpoint advertises. Picking one saves it through Claude Code’s plugin configuration and jumps to the next unassigned role. To type an id by hand, use /plugin configure agent-router@agent-router-tools.
• Effort per role. Since 0.8.0 each role also has an effort setting (default, low, medium, high, xhigh, max), picked in the same pane. Default keeps Claude Code’s own effort; a model that takes no effort setting receives none.
• /agent-models-apply applies the models and efforts you just saved to the current session, after checking them against the endpoint’s catalog, instead of waiting for a new session. Subagents already running keep what they started with; the endpoint itself stays pinned.
• Agent team teammates. With CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, teammates are routed by their agent type like subagents, in-process and split-pane alike; a split-pane teammate adopts its lead’s pinned policy. An optional Teammates entry sets one model and effort for every teammate instead. Plan and unmapped types are refused as teammates.
• A ⇄ button above the prompt cycles three views: Activity (running, completed and failed managed agents, from Claude’s own roster), Usage (input, output and cache-read tokens of completed turns) and Routing (decisions, overrides and mismatches). While you view a subagent’s transcript the icon also names its model and effort. ⇄* means you saved changes that apply from the next session, or now with /agent-models-apply.
• /agent-router:routes prints, per agent, the requested type and model, the role, model and effort the policy chose, the model Claude resolved, and the response model labels and token counts observed on completed turns.

agent-flow draws the tree of subagents in a pane; agent-router decides which model each of them runs on. They cover different questions.

Install

Needs Claude Code 2.1.287 or later, Node.js 22 or newer on PATH, and ANTHROPIC_BASE_URL pointing at an Anthropic-compatible endpoint that supports GET /v1/models. Remote endpoints must use HTTPS; loopback addresses can use HTTP. The author verifies the mod with Claude Code 2.1.280 and requires that version or newer.

claude plugin marketplace add alexandernicholson/agent-router
claude plugin install agent-router@agent-router-tools

Start Claude Code with your endpoint and credentials in the environment, then run /agent-models and assign all five roles. The picker also opens by itself in the first interactive session that has an endpoint and roles still unassigned, when the terminal is 144 columns or wider. It needs at least 110 columns to draw. A session is routing-ready once its five roles are set; assignments you change later apply to the next session, or to this one with /agent-models-apply.

How it works

The mod hooks four engine events on the subagent path. tool.call on the Agent tool is only a guard: it refuses remote agents (they cannot inherit the mod) and refuses agent-router roles when no endpoint is configured, and it reads neither the prompt nor the arguments. agent.spawn maps the requested type to a role, replaces the subagent type and model before the child starts, and logs the decision. turn.step reapplies the assigned model and effort on every turn of a managed child and prints a line if the engine tried to substitute it. turn.complete records the child’s outcome and token usage; for split-pane teammates the lead refreshes the totals every five seconds while they run. Routing is off, and every agent passes through untouched, unless ANTHROPIC_BASE_URL is set.

Policy, records and catalog discovery run in a bridge script the mod launches with node per action, with a 20 second timeout. That is why Node.js is a requirement.

The only network call the mod makes is GET /v1/models on your endpoint, when the picker loads or you press Refresh catalog. It sends x-api-key from ANTHROPIC_API_KEY, a bearer token from ANTHROPIC_AUTH_TOKEN and any headers in ANTHROPIC_CUSTOM_HEADERS, identifying itself as claude-code/agent-router. With CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 it also reads Claude Code’s ~/.claude/cache/gateway-models.json and merges the cached models for the same endpoint. The subagents’ own inference traffic goes through Claude Code as usual, not through the mod.

On disk, the five model ids live in the plugin’s configuration. Routing records go to the plugin data directory, normally ~/.claude/plugins/data/agent-router-agent-router-tools/: session and agent ids, model selections, turn outcomes and usage counters. Prompts, answers and credentials are not written there. Claude Code’s plugin store keeps the panel view you last chose and the per-session list of finished agents, so counts survive a configuration reload.

The mod adds nothing to the model’s context, so it costs no tokens on its own. What changes your bill is which model each subagent runs on; the Usage view and /agent-router:routes show the client-side counts, and the author points to gateway logs as the authoritative source for billing.

Limitations

• Each session freezes its endpoint at start. Models and efforts saved with /agent-models take effect in the next session, or now with /agent-models-apply; a new ANTHROPIC_BASE_URL always needs a new session.
• Agents spawned with remote isolation are refused while routing is active.
• Teammate routing reads launch details that Claude Code 2.1.280 provides outside the documented plugin API; the author asks you to recheck it after upgrading Claude Code. /agent-models-apply is refused inside a split-pane teammate session.
• The picker needs an interactive terminal or desktop session; in the terminal it asks for 110 columns. The ⇄ panel draws only in an interactive terminal, and clicking it needs /tui fullscreen; Tab and Enter work without the mouse.
• Keep CLAUDE_CODE_SUBAGENT_MODEL_FORCE unset, or it conflicts with per-role models.
• Mismatches compare the assignment with the model Claude resolved, not with the response labels, which may drop Claude’s [1m] context suffix.
• If catalog discovery fails (for example a 401 or 403 from the endpoint), the saved roles stay and the picker shows the catalog as unavailable.
• Version 0.10.2, verified by the author on Claude Code 2.1.280; we have not run it ourselves.