Agent Router

Local-first, quota-aware routing for AI coding agents in Herdr.

router is a command-line tool that picks an AI coding agent, model, and reasoning effort for a task, then starts that agent for you in a Herdr pane.

router run "implement the approved plan in docs/plans/billing.md"

It filters your subscriptions with fixed rules (enabled models, quota, the 40% reserve on shared accounts), asks TypeSafe to rank what is left and choose an effort, starts the chosen agent (Cursor, Claude Code, Codex, or OpenCode), and hands it the task.

Pre-release: the project is under active development. Review the security and privacy notes below before using real credentials or shared accounts.

Demo

Why Agent Router?

• Quota-aware: routes around depleted or reserved subscription capacity.
• Policy-first: deterministic eligibility rules run before semantic ranking.
• Local-first: configuration, usage snapshots, decisions, and session history stay on your machine unless an explicitly configured integration needs them.
• Agent-agnostic: supports Cursor, Claude Code, Codex, and OpenCode through one command.

Prerequisites

• Node.js 20 or newer (nvm use reads .nvmrc).
• A TypeSafe API key. Routing always calls TypeSafe; there is no fallback. Each run sends the task text to TypeSafe. Recognizable credentials are rejected locally before the call; do not place other sensitive narrative data in routing tasks.
• At least one agent CLI you are logged in to: agent (Cursor), claude (Claude Code), codex, or opencode. The router uses those logins; no provider API keys are needed.
• Herdr, to launch agents. router run without --dry-run only launches from inside a Herdr pane (HERDR_ENV=1).

Setup

1. Install and build

git clone https://github.com/nidhi-singh02/agent-router.git
cd model-router
npm install
npm run build

2. Put router on your PATH

npm link -w @agent-router/router

Or add an alias to ~/.zshrc:

alias router="node $HOME/Code/model-router/packages/router/dist/cli.js"

After git pull, run npm run build again.

3. Create your config

The config lives in .model-router/ inside the repo (gitignored). Point the router at it from ~/.zshrc, then source ~/.zshrc:

export MODEL_ROUTER_HOME="$HOME/Code/model-router/.model-router"

mkdir -p .model-router
cp config.example.json .model-router/config.json

MODEL_ROUTER_HOME overrides the location on every platform. Without it the router uses the platform config directory:

The router reads config.json from that directory. A missing file is treated as an empty account list, so an unexpectedly empty router status usually means the home is not where you think it is.

4. Store the TypeSafe key in the macOS Keychain

security add-generic-password -a "$USER" -s model-router-typesafe -w

The command prompts for the key, so it never lands in shell history. The config refers to it with "typesafe": { "apiKeyRef": "keychain:model-router-typesafe" }. Every pane and agent then finds the key without exporting anything, and it stays out of agents' environments. To replace the key, add -U. If macOS asks to allow security access the first time, choose "Always Allow". TYPESAFE_API_KEY in the environment still works as a fallback.

5. Add your accounts

There is no router accounts add command. Edit the accounts array in .model-router/config.json (hidden folder; for example code .model-router/config.json) with one entry per agent login:

{
  "id": "acct_personal_claude",
  "label": "personal claude",
  "provider": "anthropic",
  "agent": "claude-code",
  "ownership": "personal",
  "collectorPreference": ["local-session"],
  "enabledModels": ["anthropic:claude-sonnet", "anthropic:claude-opus"],
  "enabled": true
}

Run router accounts to check that the file parses. docs/configuration.md has the full schema.

6. Install the model-router skill (optional, recommended)

The skill lets an agent route the next phase of your work (see Phases). Link the repo copy so updates arrive with git pull:

ln -s "$PWD/skills/model-router" ~/.claude/skills/model-router
ln -s "$PWD/skills/model-router" ~/.codex/skills/model-router
ln -s "$PWD/skills/model-router" ~/.cursor/skills/model-router

The links follow whatever branch is checked out in this repo.

Models

Defined in packages/router/config/models.json. Add an ID to an account's enabledModels to use it.

TypeSafe picks the effort from the model's list. ultra is only offered when your task text contains the word "ultra". Capability, cost, and latency numbers in models.json are estimates you can adjust.

Everyday use

router run "<task>" --dry-run    # see which agent, model, and effort would be used
router run "<task>"              # start that agent in a new Herdr pane and send the task
router status                    # list accounts; add --usage to show quota
router session                   # the latest launch; router session --list for more

--dry-run prints the decision card and the command it would start, without opening a pane or sending anything. A real run splits a new pane next to the current one, starts the agent, waits for it to finish starting up, sends the task, and confirms the agent began working. You can run the router any number of times, in the same tab or different ones; each launch gets its own agent name such as router-codex-3c356c.

The decision card

Selected: cursor / composer-2.5 / none
Phase: implementation
Why: TypeSafe selected acct_personal_cursor:cursor:composer-2.5 for implementation in phase implementation
Reserve policy: personal account
Cache decision: no previous session
Usage source: estimated local-session
Quota: auto 70% left (spend 45% left)
Freshness: refreshed at 2026-09-17T12:00:00.000Z

The router routes one phase per task (planning, implementation, debugging, review, research, and so on). It does not answer your question itself; the launched agent does.

Exit codes

| Code | Meaning |