agent-router

# 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.

```sh
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

[](https://youtu.be/7w8eRWnUUA8 "Agent Router demo — click to play")

## 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-