---

What it does

opencode agents are markdown files (~/.config/opencode/agents/*.md) whose YAML frontmatter carries a model: line:

---
description: High-reasoning review, debugging, and architecture counsel
mode: subagent
model: anthropic/claude-opus-4-8        # ← agent-router rewrites this
reasoningEffort: high                   # ← and any option keys a stack names
temperature: 0.1
tools: { write: false, edit: false }
---
<prompt body — owned by you, never touched by agent-router>

agent-router keeps named stacks — JSON files mapping agent names to models (and optionally to provider options) — and applies them to those frontmatter lines on demand. Premium models for the workday, cheap ones for bulk chores, one command to swap the whole crew:

{
  "agents": {
    "Omni":      { "model": "anthropic/claude-fable-5" },
    "oracle":    { "model": "openai/gpt-5.5", "reasoningEffort": "high" },
    "explorer":  { "model": "openai/gpt-5.4-mini" },
    "librarian": { "model": "openai/gpt-5.4-mini" },
    "fixer":     { "model": "openai/gpt-5.5", "thinking": { "effort": "low" } }
  }
}

The prompt body and opencode framework keys (description, mode, permission, tools, …) are yours; agent-router rewrites only the model: line and the option keys a stack entry names, atomically, through symlinks (dotfile-manager setups survive intact).

~/.config/opencode/
├── agents/                     ← your agent .md files (the live target)
└── agent-router/
    ├── state.json              ← {active, previousActive, …}   (machine state)
    ├── stacks/
    │   ├── premium.json        ← named stacks                   (your config)
    │   └── cheap.json
    └── history/                ← rolling 20 most-recent switches

Stacks are config, history is state — point stacksDir somewhere dotfile-managed if you version your setup (see Configuration).

Install

npx -y @dylanrussell/agent-router init

init will:

1. Capture your agents' current models into a first stack (default) and mark it active.
2. Add @dylanrussell/agent-router@latest to the plugin array in opencode.json (backing it up first).
3. Add the same entry to tui.json — this loads the sidebar + /agent-* commands (opencode ≥ 1.17).
4. Remove the legacy @dylanrussell/omo-router plugin entry if present.

Then restart opencode so it picks up the plugin.

Quickstart

agent-router capture my-mix           # snapshot current frontmatter models as a stack
agent-router list                     # show stacks; * marks active
agent-router use cheap                # apply a stack (validates first)
agent-router back                     # undo the most recent switch
agent-router current                  # print the agent → model mapping in frontmatter
agent-router status                   # print active stack name
agent-router show cheap               # print a stack's JSON
agent-router edit cheap               # open a stack in $EDITOR
agent-router validate --all           # check every stack against `opencode models`
agent-router history                  # list recent switches
agent-router import my-mix <file>     # import a stack from a file
agent-router export my-mix <file>     # export a stack to a file
agent-router rm my-mix                # remove a stack
agent-router path                     # print all paths used (debugging)
agent-router completion               # install shell autocompletion

The everyday loop: tune your agents until you like them → capture <name> → repeat with other models → use <name> to swap between the results.

Stacks

A stack file needs one thing: an agents record whose entries carry a model string. Agent names are the .md basenames in your agents dir (Omni ↔ Omni.md). Any other key on an entry is a provider pass-through option (reasoningEffort, thinking, temperature, topP, maxOutputTokens, …) that opencode forwards to the model — agent-router transcribes these to the agent's frontmatter alongside model: and captures them back. Unknown keys are preserved round-trip.

{
  "agents": {
    "oracle": {
      "model": "openai/gpt-5.5",
      "reasoningEffort": "high",
      "thinking": { "effort": "low" }
    }
  }
}

• Apply writes/updates only the option keys a stack entry names; options the stack omits are left in place. To clear an option, set it to null in the stack entry.
• Reserved opencode framework keys (description, mode, permission, tools, prompt, steps, color, name) are never transcribed — a stack entry can't clobber them.
• Option values serialize to a single frontmatter line: scalars bare (quoted only when needed), objects/arrays as JSON flow. Block-style values an apply replaces are collapsed to flow; capture parses them back into typed JSON.

use is strict by design: if a stack references an agent file that doesn't exist, or one without a model: line, the switch fails before anything is written — your suite is never left half-switched. It also validates every model ID against opencode models first (skip with --no-validate, override with --force-invalid).

capture is the inverse: it reads the current model: line and option keys of every agent file (files without a model: line are skipped) and writes a stack. There are no bundled seed stacks — your real setup is the seed.

Inside opencode

The plugin exposes six tools the agent (or you, by asking it) can call:

tool	what it does
router_status	active stack + current frontmatter mapping + available stacks
router_list	stack list with isActive flags
router_use({name, validate?})	apply a stack; pops a TUI toast
router_capture({name, force?})	snapshot current models into a stack
router_back({n?})	undo last N switches
router_validate({name?, active?})	check model IDs against current opencode auth

"Switch to cheap" — your agent calls router_use, the toast pops up, you restart opencode.

In the TUI

On opencode ≥ 1.17 the plugin also ships a TUI half (loaded from tui.json, wired up by init):

• Sidebar panel — shows the active stack, the stack count, and a ⟳ restart required badge after any switch. Updates live (≤1.5s) when the CLI or agent switches stacks underneath the TUI.
• Commands — type / or open the command palette:

command	what it does
/agent-switch (alias /ar)	pick a stack, validate, apply
/agent-view	browse a stack's agent → model assignments
/agent-edit	reassign a model, picking from your reachable model catalog
/agent-back	confirm + revert to the previous stack
/agent-validate	check a stack's model IDs against current auth
/agent-status	toast the active stack + list

Everything degrades gracefully: on older opencode versions (or if the TUI API changes) the sidebar and commands simply don't appear — the CLI and agent tools keep working.

Debugging the TUI half: AGENT_ROUTER_TUI_DEBUG=/tmp/agent-router-tui.log opencode writes a trace of the plugin's init steps.

Configuration

Paths resolve in this order: explicit option → config.json → env var → default.

~/.config/opencode/agent-router/config.json (read identically by the CLI and the plugin — the recommended place):

{
  "agentsDir": "~/.agents/agents",
  "stacksDir": "~/.agents/agent-router/stacks"
}

setting	env var	default
agents dir	AGENT_ROUTER_AGENTS_DIR	~/.config/opencode/agents
stacks dir	AGENT_ROUTER_STACKS_DIR	${routerHome}/stacks
state home	AGENT_ROUTER_HOME (legacy OMO_ROUTER_HOME)	~/.config/opencode/agent-router

⚠ Things to know

• Restart required. opencode reads agent files once at startup. After every agent-router use, restart opencode for the new models to take effect. The CLI reminds you.
• Hand-edits to frontmatter are not auto-saved into stacks. If you hand-tune a model or option and want to keep it, capture it (or capture <active> --force). The next use that touches that agent overwrites the hand-edit for keys the stack names; keys the stack omits are preserved (set an option to null in a stack entry to clear it).
• Validation is auth-state-dependent. agent-router validate runs opencode models, which only lists models reachable through your current auth. If you revoke a key, previously-valid stacks may suddenly be invalid.

FAQ

Why no variants/fallback models? Native agent frontmatter has a single model: line. If you want a fallback, make it a stack (cheap, free) and switch to it. For per-stack behavior variants (reasoning effort, thinking budget, temperature, …), add the option as a sibling key on the stack entry — it transcribes to frontmatter on use.

Can I have per-project stacks? Point AGENT_ROUTER_STACKS_DIR at a project-local directory in that project's shell env.

Architecture in 60 seconds

┌──────────────────────────────────────────────┐
│ opencode (Bun)                               │
│  └─ agents loaded from agents/*.md ──────────┼── reads at startup ─┐
│  └─ plugin: agent-router (this package) ─────┼─ tools, toast       │
└──────────────────────────────────────────────┘                     ▼
~/.config/opencode/agents/*.md             ◄── `model:` lines rewritten on `use`
~/.config/opencode/agent-router/
  stacks/<name>.json                       ◄── source of truth for each stack
  state.json                               ◄── pointer to active stack
  history/<ts>__<from>-to-<to>.json        ◄── displaced mappings, rolling 20

Contributing

Issues and PRs welcome. Run locally:

git clone https://github.com/dylanrussellmd/agent-router.git
cd agent-router
pnpm install
pnpm test
pnpm build

License

MIT — see LICENSE.