Skip to main content
open-agent-router: route coding jobs across your AI subscriptions

open-agent-router

Hand coding-agent jobs to the AI subscriptions you already pay for — Claude Code, Kimi Code, OpenCode, Cline — and let a local gateway pick the one with the most limit left.

PyPI CI License: MIT Python 3.12 Windows | Linux | macOS (experimental) Status: alpha

This is an early alpha (v0.2.0); interfaces and configuration may change.

Why

You pay for several AI coding subscriptions, but each one has its own limits and pace. You do not want a job to fail mid-run because a limit ran out, and you do not want to spend a strong model on a task a cheap one handles fine. open-agent-router is a local gateway that keeps your subscriptions busy without surprises:

  • Subscriptions do not sit idle. The gateway tracks usage in every limit window and prefers the pool that is furthest behind its expected pace.
  • Limits do not surprise you. A pool that reports a limit is blocked until its reset; on a usage limit and on an executor error the job moves to another route. A writing attempt that already changed files ends partial and is not retried.
  • Jobs go where they are cheap enough. Each job gets a tier — cheap, standard or strong — and the gateway picks a route for that tier by priority and by how far each subscription is behind its pace. An optional classifier — a local model or a cloud one — can assign the tier for you.

It is for you if you have two or more subscriptions to agentic coding CLIs (such as Claude Code, Kimi Code, OpenCode or Cline) and an orchestrator agent that delegates jobs to others.

Terminal: agent-router advice ranks routes by how far each pool is behind its pace, agent-router status shows usage of every pool window

How is this different from LiteLLM, OpenRouter or switching by hand?

  • LiteLLM, OpenRouter and other API gateways route single model requests using API keys, with usage billed per token. open-agent-router hands whole jobs — a prompt, a directory and a read or write mode — to the subscriptions you already pay for through their official CLIs, and never sees provider keys.
  • Switching by hand means checking several usage pages and guessing which limit resets first. The gateway keeps track of every limit window and its pace, moves a job to another route when a limit is hit, and keeps strong models for the jobs that need them.
  • An agent's own model picker stays inside one subscription. The gateway spreads jobs across subscriptions from different providers, and an orchestrator agent can use it through the CLI or the MCP server.

Quick start

You need Python 3.12, uv, git, and at least one harness CLI (Kimi Code, OpenCode, Cline or Claude Code), installed and signed in.

uv tool install open-agent-router
agent-router init --allowed-root <directory>
agent-router serve

To run the latest main instead, install with uv tool install git+https://github.com/kdenischenko/open-agent-router. If agent-router is not found after the install, run uv tool update-shell and open a new terminal. serve keeps running in its terminal; stop it with Ctrl+C.

With the gateway running, agent-router advice --tier standard shows which routes can take a job. The opencode-go limits in the template are placeholders; replace them with your plan limits.

The open-agent-router package installs the agent-router command. init creates the gateway home directory with config.toml and two tokens, adds <directory> to tasks.allowed_roots (repeat init --allowed-root to allow more directories, also on an existing config, then restart a running serve) and prints the next steps. Routes are enabled for the harnesses init finds, except Claude Code and Cline: set enabled = true on the claude-cli/sonnet or cline/glm-5.3 route in config.toml to let jobs use them. Jobs run before you calibrate the pools; record your real usage later with agent-router calibrate. Ready-made configs for typical setups are in docs/examples/. Then submit a job from another terminal:

agent-router run --no-wait --cwd <directory> --mode read "Describe the structure of this repository"
agent-router approve <job-id>
agent-router wait <job-id>

wait exits 4 while the job is still running; run it again, or use --timeout to wait longer. A job that needs approval returns at once with job awaits approval: agent-router approve <id> before <time>, then agent-router wait <id>.

Terminal: a job is submitted with run --no-wait, a human approves it, wait prints the result, rate records the rating and status shows the pool usage

Every route in the init template has confirm = true, so a job waits until you approve it with approve or in the dashboard. Set confirm = false on a route to let its jobs start right away. Without a decision the approval expires after tasks.approval_timeout_s (default 600 s): the job ends as declined with error approval_expired and does not move to another route.

A job is stopped when it exceeds tasks.default_timeout_s (default 14400 s, a hard cap), or when the harness prints nothing to stdout or stderr for tasks.idle_timeout_s (default 600 s; 0 disables the check). --timeout on run, or route.timeout_s, replaces the hard cap, but the idle limit still applies. Claude Code prints its JSON only at the end, so its jobs are limited by the hard cap alone.

The full guide — harness sign-in, limit calibration, Windows autostart, the web dashboard and the delegation skills for orchestrators — is in docs/INSTALL.md.

Use from your agent

An orchestrator agent can work through the gateway in two ways.

The first is the MCP server. Register it with your orchestrator, for example with claude mcp add agent-router -- agent-router mcp: it exposes job operations as MCP tools, and it needs the running gateway. Setup for every supported harness is in docs/MCP.md.

The second way is a delegation skill: ready-made delegation instructions for orchestrators live in integrations/: clone or download the repository and copy the agent-router-delegate folder of your harness into its skills directory.

How it works

Architecture: an orchestrator calls the agent-router CLI, the gateway HTTP API checks the token and passes the job to the dispatcher; the dispatcher asks the tier classifier (local or cloud models), checks the job directory and human approval, the route policy picks a pool from the ledger and pacing data in SQLite, and the runner starts the harness CLI through its adapter

You submit a job: a prompt, a directory, a mode and optional hints. The gateway estimates the tier, checks the remaining limits and pace of every pool, picks a route, queues the job and — for routes with confirm = true — waits until you approve it. It then runs the harness CLI as a child process, records the spend and returns the result. See docs/DESIGN.md for the full architecture.

Tier classifier

A job submitted without --tier can get its tier from a classifier model. It can be local — a decision or chat model in Ollama, or any OpenAI-compatible server such as LM Studio — or a cloud provider over HTTPS with a key from an environment variable. Several models can vote side by side: in shadow mode they only record votes, and agent-router classifier report compares them with the tiers you confirm before you let one of them decide. Configuration examples, what the classifier receives and measured results are in docs/CLASSIFIER.md.

Dashboard

Web dashboard with pool limits, advice and jobs

The gateway also serves a dashboard at http://127.0.0.1:<port>/ (the port is server.port, default 8787). Log in with the admin token: paste the contents of the admin.token file whose path init prints. The job page refreshes itself, shows the error, and lets you rate a finished job.

Harnesses

The gateway runs each harness CLI with the sign-in you already made in it; it never sees provider keys.

Harness CLI command Usage source Status
Kimi Code kimi journal tested live on Windows
OpenCode opencode counter (opencode stats) tested live on Windows
Cline cline or cline-cli journal tested live on Windows
Claude Code claude journal not tested live: covered by tests with recorded output only

Platforms

Windows is supported and tested in CI and live. Linux and macOS are experimental: the test suite runs on them in CI, but the gateway has not been run live there, and autostart is Windows-only. Help wanted — see ROADMAP.

Commands

All commands are agent-router <command>. Run agent-router <command> --help for every option.

Command What it does
init Create the gateway home, config.toml, tokens; --allowed-root DIR allows job dirs
serve Run the gateway on 127.0.0.1 (--port overrides server.port)
mcp Run an MCP server over stdio for orchestrator agents
status Show pool usage, expected pace and window resets in local time
advice Show matching routes for a tier (and --mode read or write) and why the others are excluded
calibrate POOL WINDOW PERCENT Record the usage your subscription shows; --resets-at or --resets-in 10d sets the reset of a fixed window, a rolling window takes none (admin token)
unblock POOL Remove a pool block set after a limit hit (admin token)
run [TEXT] Submit a job and wait up to 100 s; --no-wait prints the job id, - reads the prompt from stdin
wait JOB_ID Wait for a job and print its result; retries for up to 10 s while the gateway restarts
result JOB_ID Print the status and result of a job without waiting
rate JOB_ID good|bad|partial Rate a finished job; the last rating wins, a --note is stored as hash and length only
jobs List jobs with status, route, tier and creation time, optionally by --status
cancel JOB_ID Cancel a queued or running job
approve JOB_ID / deny JOB_ID Approve or deny a job that awaits confirmation (admin token)
doctor Check config, store, harnesses and gateway; warns when a route's counter spend is invisible: the pool counter cannot see its harness, or the pool has no counter; --live runs one read job per harness on routes without confirm
export --since DATE Export jobs, attempts, ratings, classifier votes and usage as JSON Lines or CSV; texts are replaced by hash and length, CSV cells that a spreadsheet would read as a formula get a leading '
purge Delete terminal jobs older than storage.retention_days, with their prompts, results and attempt logs; usage/spend records are kept; --dry-run only reports the count
classifier report Show classifier votes, errors and accuracy against ratings; --json adds the tier matrix and latency
classifier eval --models ID,... Replay past prompts through offline classifier models

Job history is kept forever by default. To bound it, set retention_days = 30 in [storage], then run agent-router purge. Age is measured from the job's finish time. Queued, running and awaiting-approval jobs are never purged, and serve does not purge automatically. Check the count first with agent-router purge --dry-run.

doctor --statusline-snippet prints the settings for the Claude Code status line, which reports Claude usage to the gateway; see docs/INSTALL.md.

A route without an explicit spend inherits the usage source of its harness. When that source is counter and the counter of the route's pool cannot see the route's harness, the pool's usd window never counts the route's spending; doctor warns about it and suggests spend = "journal", which records every job in the journal instead. A route that inherits counter on a pool with no counter is invisible in the same way, and doctor warns about it too.

Exit codes

Commands that call the gateway exit 5 when the gateway is unavailable or rejects the token, 6 when the request is denied with HTTP 4xx (including a full queue), and 1 on other errors. For run, wait and result, once the job state is known: 0 — completed, 2 — partial, 3 — failed, declined or cancelled, 4 — the job is not finished yet. run --no-wait exits 0 after a successful submit. Local errors (configuration, store, reading the prompt, a malformed --resets-at) exit 1; doctor --live exits 1 unless every probe completes.

Common failures and their fixes are in docs/TROUBLESHOOTING.md.

Environment variables

  • AGENT_ROUTER_HOME — directory with config.toml, tokens and stores; defaults to the per-user agent-router configuration directory.
  • AGENT_ROUTER_URL — gateway address for client commands and the Claude Code status line; defaults to http://127.0.0.1:<server.port> and must use http or https. Client commands report unsupported schemes or URL parsing errors as configuration errors (exit code 1); the status line skips forwarding for these URLs and continues to render the limits.

Adding a subscription or harness

  1. Pool. Add a [[pools]] section with [[pools.windows]] for your plan: unit = "percent" for subscriptions that show a percentage, or unit = "usd" with limit_usd for subscriptions billed in dollars. Optional: priority, weight (a nudge in percentage points of lag) and price_file — a TOML table "<model>" = [input, output] (USD per 1M tokens) used when the harness does not report a cost.
  2. Harness. For a new CLI, write an adapter module like src/agent_router/adapters/opencode.py exposing HARNESS = HarnessSpec(...) (name, adapter, executable names, spend source counter/journal), register an entry point in the agent_router.harnesses group in pyproject.toml, then uv sync. Adapter tests use redacted output samples in tests/fixtures/ and never run the real CLI. If the executable is not in PATH, set [backends.<name>] executable.
  3. Routes. Add [[routes]] with pool, backend, model, tiers, quality, modes; start a new route with enabled = false.
  4. Models. To share one model across pools, give its routes a common model_key and order the pools in [models."<model_key>"] prefer = [...].
  5. Verify. agent-router doctor shows the harness, its version and enabled routes; agent-router doctor --live runs one short job per harness (needs a non-empty allowed_roots); agent-router status shows pool usage.

Security

agent-router is a local tool for a single user and not a sandbox: in --mode write the harness starts with auto-approved tools and can change any file your user can touch. The threat model and how to report a vulnerability are in SECURITY.md.

A read_mode_files_changed violation on a read-mode job means the working tree changed while the job ran. If someone else wrote to the same repository in parallel, the violation is attributed to the job even though the executor changed nothing.

Subscriptions

Use only official ways to access the providers and follow their terms. You are responsible for complying with them. The project is not affiliated with the providers and does not bypass their restrictions.

Contributing and roadmap

Contributions are welcome: open an issue before a large change, follow CONTRIBUTING.md, and keep the gates green (uv run ruff check, uv run ruff format --check, uv run pytest -q). Plans — Linux and macOS support and an OpenAI-compatible proxy — are in ROADMAP.md.

License

MIT.

Metadata

Release files for open-agent-router 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for open-agent-router 0.2.0
File Size Uploaded Provenance Actions
open_agent_router-0.2.0.tar.gz 686.3 kB Without provenance Details for open_agent_router-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for open-agent-router 0.2.0
File Interpreter ABI Platform Actions
open_agent_router-0.2.0-py3-none-any.whl Python 3 none any Details for open_agent_router-0.2.0-py3-none-any.whl

Total release size: 848.2 kB

Release files / open_agent_router-0.2.0.tar.gz

Download URL open_agent_router-0.2.0.tar.gz
Size 686.3 kB
Tags Source
SHA-256 checksum
How to use checksums
06fdf6d77fb1e5317d8187c8f54e1ca1612cc06f9586c2811bd1d356ba6e1c60
BLAKE2b-256 checksum
How to use checksums
19e0da7a98536d229d6eed09a12f52aef35a32061ae5c160c434abb71e255330
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / open_agent_router-0.2.0-py3-none-any.whl

Download URL open_agent_router-0.2.0-py3-none-any.whl
Size 161.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
16bbdc40da4c57c5c89ebd175f50c67ba96185b2fed2ddff4f6b166e12e5769f
BLAKE2b-256 checksum
How to use checksums
4d86fb4e2a53744a9206aa7f0af8abbfd3bddc966a3c0016c8491f80c0df06fb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for open-agent-router 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page