Skip to content
Back to search

open-agent-router

Local gateway that routes coding-agent jobs across your AI subscriptions by remaining quota

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kdenischenko--open-agent-router/badge.svg)](/listings/kdenischenko--open-agent-router)

HTML

<a href="/listings/kdenischenko--open-agent-router"><img src="/api/listings/kdenischenko--open-agent-router/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need Python 3.12, [uv](https://docs.astral.sh/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/`](https://github.com/kdenischenko/open-agent-router/tree/main/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>`.

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](https://github.com/kdenischenko/open-agent-router/blob/main/docs/INSTALL.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 296 lines
  1. <picture>
  2. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kdenischenko/open-agent-router/main/docs/assets/banner-dark.svg">
  3. <img src="https://raw.githubusercontent.com/kdenischenko/open-agent-router/main/docs/assets/banner-light.svg" alt="open-agent-router: route coding jobs across your AI subscriptions">
  4. </picture>
  5. # open-agent-router
  6. **Hand coding-agent jobs to the AI subscriptions you already pay for — Claude Code, Kimi Code,
  7. OpenCode, Cline — and let a local gateway pick the one with the most limit left.**
  8. [![PyPI](https://img.shields.io/pypi/v/open-agent-router.svg)](https://pypi.org/project/open-agent-router/)
  9. [![CI](https://github.com/kdenischenko/open-agent-router/actions/workflows/ci.yml/badge.svg)](https://github.com/kdenischenko/open-agent-router/actions/workflows/ci.yml)
  10. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/kdenischenko/open-agent-router/blob/main/LICENSE)
  11. [![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org)
  12. [![Windows | Linux | macOS (experimental)](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS%20(experimental)-blue.svg)](https://github.com/kdenischenko/open-agent-router#platforms)
  13. [![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)](https://github.com/kdenischenko/open-agent-router/blob/main/ROADMAP.md)
  14. This is an early alpha (v0.2.0); interfaces and configuration may change.
  15. ## Why
  16. You pay for several AI coding subscriptions, but each one has its own limits and pace.
  17. You do not want a job to fail mid-run because a limit ran out, and you do not want to
  18. spend a strong model on a task a cheap one handles fine. open-agent-router is a local
  19. gateway that keeps your subscriptions busy without surprises:
  20. - **Subscriptions do not sit idle.** The gateway tracks usage in every limit window and
  21. prefers the pool that is furthest behind its expected pace.
  22. - **Limits do not surprise you.** A pool that reports a limit is blocked until its reset;
  23. on a usage limit and on an executor error the job moves to another route. A writing
  24. attempt that already changed files ends `partial` and is not retried.
  25. - **Jobs go where they are cheap enough.** Each job gets a tier — `cheap`, `standard` or
  26. `strong` — and the gateway picks a route for that tier by priority and by how far each
  27. subscription is behind its pace. An optional classifier — a local model or a cloud one —
  28. can assign the tier for you.
  29. It is for you if you have two or more subscriptions to agentic coding CLIs (such as Claude Code,
  30. Kimi Code, OpenCode or Cline) and an orchestrator agent that delegates jobs to others.
  31. ![Terminal: agent-router advice ranks routes by how far each pool is behind its pace, agent-router status shows usage of every pool window](https://raw.githubusercontent.com/kdenischenko/open-agent-router/main/docs/assets/demo.svg)
  32. ## How is this different from LiteLLM, OpenRouter or switching by hand?
  33. - **LiteLLM, OpenRouter and other API gateways** route single model requests using API keys,
  34. with usage billed per token. open-agent-router hands whole jobs — a prompt, a directory and
  35. a read or write mode — to the subscriptions you already pay for through their official CLIs,
  36. and never sees provider keys.
  37. - **Switching by hand** means checking several usage pages and guessing which limit resets
  38. first. The gateway keeps track of every limit window and its pace, moves a job to another
  39. route when a limit is hit, and keeps strong models for the jobs that need them.
  40. - **An agent's own model picker** stays inside one subscription. The gateway spreads jobs
  41. across subscriptions from different providers, and an orchestrator agent can use it through
  42. the CLI or the MCP server.
  43. ## Quick start
  44. You need Python 3.12, [uv](https://docs.astral.sh/uv/), git, and at least one harness CLI
  45. (Kimi Code, OpenCode, Cline or Claude Code), installed and signed in.
  46. ```bash
  47. uv tool install open-agent-router
  48. agent-router init --allowed-root <directory>
  49. agent-router serve
  50. ```
  51. To run the latest `main` instead, install with `uv tool install git+https://github.com/kdenischenko/open-agent-router`. If
  52. `agent-router` is not found after the install, run `uv tool update-shell` and open a new
  53. terminal. `serve` keeps running in its terminal; stop it with Ctrl+C.
  54. With the gateway running, `agent-router advice --tier standard` shows which routes can take a
  55. job. The `opencode-go` limits in the template are placeholders; replace them with your plan
  56. limits.
  57. The `open-agent-router` package installs the `agent-router` command. `init` creates the
  58. gateway home directory with `config.toml` and two tokens, adds `<directory>` to
  59. `tasks.allowed_roots` (repeat `init --allowed-root` to allow more directories, also on an
  60. existing config, then restart a running `serve`) and prints the next steps. Routes are enabled
  61. for the harnesses `init` finds, except Claude Code and Cline: set `enabled = true` on the
  62. `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
  63. your real usage later with `agent-router calibrate`. Ready-made configs for typical setups are
  64. in [`docs/examples/`](https://github.com/kdenischenko/open-agent-router/tree/main/docs/examples). Then submit a job from another terminal:
  65. ```bash
  66. agent-router run --no-wait --cwd <directory> --mode read "Describe the structure of this repository"
  67. agent-router approve <job-id>
  68. agent-router wait <job-id>
  69. ```
  70. `wait` exits 4 while the job is still running; run it again, or use `--timeout` to wait longer.
  71. A job that needs approval returns at once with
  72. `job awaits approval: agent-router approve <id> before <time>, then agent-router wait <id>`.
  73. ![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](https://raw.githubusercontent.com/kdenischenko/open-agent-router/main/docs/assets/cycle.svg)
  74. Every route in the `init` template has `confirm = true`, so a job waits until you approve it
  75. with `approve` or in the dashboard. Set `confirm = false` on a route to let its jobs start
  76. right away. Without a decision the approval expires after `tasks.approval_timeout_s`
  77. (default 600 s): the job ends as `declined` with error `approval_expired` and does not move
  78. to another route.
  79. A job is stopped when it exceeds `tasks.default_timeout_s` (default 14400 s, a hard cap), or
  80. when the harness prints nothing to stdout or stderr for `tasks.idle_timeout_s` (default 600 s;
  81. `0` disables the check). `--timeout` on `run`, or `route.timeout_s`, replaces the hard cap, but
  82. the idle limit still applies. Claude Code prints its JSON only at the end, so its jobs are
  83. limited by the hard cap alone.
  84. The full guide — harness sign-in, limit calibration, Windows autostart, the web dashboard
  85. and the delegation skills for orchestrators — is in [docs/INSTALL.md](https://github.com/kdenischenko/open-agent-router/blob/main/docs/INSTALL.md).
  86. ## Use from your agent
  87. An orchestrator agent can work through the gateway in two ways.
  88. The first is the MCP server. Register it with your orchestrator, for example with
  89. `claude mcp add agent-router -- agent-router mcp`: it exposes job operations as MCP
  90. tools, and it needs the running gateway. Setup for every supported harness is in
  91. [docs/MCP.md](https://github.com/kdenischenko/open-agent-router/blob/main/docs/MCP.md).
  92. The second way is a delegation skill: ready-made delegation instructions for
  93. orchestrators live in [`integrations/`](https://github.com/kdenischenko/open-agent-router/tree/main/integrations): clone or download the
  94. repository and copy the `agent-router-delegate` folder of your harness into its skills directory.
  95. ## How it works
  96. <picture>
  97. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kdenischenko/open-agent-router/main/docs/assets/architecture-dark.svg">
  98. <img src="https://raw.githubusercontent.com/kdenischenko/open-agent-router/main/docs/assets/architecture-light.svg" alt="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">
  99. </picture>
  100. You submit a job: a prompt, a directory, a mode and optional hints. The gateway estimates
  101. the tier, checks the remaining limits and pace of every pool, picks a route, queues the
  102. job and — for routes with `confirm = true` — waits until you approve it. It then runs the
  103. harness CLI as a child process, records the spend and returns the result. See
  104. [docs/DESIGN.md](https://github.com/kdenischenko/open-agent-router/blob/main/docs/DESIGN.md) for the full architecture.
  105. ## Tier classifier
  106. A job submitted without `--tier` can get its tier from a classifier model. It can be local —
  107. a decision or chat model in [Ollama](https://ollama.com), or any OpenAI-compatible server
  108. such as LM Studio — or a cloud provider over HTTPS with a key from an environment variable.
  109. Several models can vote side by side: in `shadow` mode they only record votes, and
  110. `agent-router classifier report` compares them with the tiers you confirm before you let one
  111. of them decide. Configuration examples, what the classifier receives and measured results are
  112. in [docs/CLASSIFIER.md](https://github.com/kdenischenko/open-agent-router/blob/main/docs/CLASSIFIER.md).
  113. ## Dashboard
  114. ![Web dashboard with pool limits, advice and jobs](https://raw.githubusercontent.com/kdenischenko/open-agent-router/main/docs/assets/dashboard.png)
  115. The gateway also serves a dashboard at `http://127.0.0.1:<port>/` (the port is
  116. `server.port`, default 8787). Log in with the admin token: paste the contents of the
  117. `admin.token` file whose path `init` prints. Jobs waiting for your approval are listed at
  118. the top of the home page with Approve and Deny. Below them the home page shows one card per
  119. pool with usage, expected pace, reset countdowns and observation age for each window,
  120. including stale and blocked states; the full limits table stays under a disclosure. The job
  121. list filters by status, route and caller, searches by job id or prompt text, sorts by
  122. creation time or duration and pages through 50 jobs at a time; the filters live in the
  123. address, so a filtered view can be bookmarked. Manual calibration shows field-specific
  124. errors and, with scripts on, validates input and previews usage pace and the local reset time;
  125. after saving, the updated pool card is highlighted. The job page refreshes itself, shows the
  126. error, and lets you rate a finished job.
  127. It shows the attempt, token, cost and duration totals, a per-attempt timeline, and the prompt,
  128. final text and per-attempt output in expandable blocks, with a copy button when clipboard
  129. scripting is available.
  130. ## Harnesses
  131. The gateway runs each harness CLI with the sign-in you already made in it; it never sees
  132. provider keys.
  133. | Harness | CLI command | Usage source | Status |
  134. |---|---|---|---|
  135. | Kimi Code | `kimi` | journal | tested live on Windows |
  136. | OpenCode | `opencode` | counter (`opencode stats`) | tested live on Windows |
  137. | Cline | `cline` or `cline-cli` | journal | tested live on Windows |
  138. | Claude Code | `claude` | journal | not tested live: covered by tests with recorded output only |
  139. ## Platforms
  140. Windows is supported and tested in CI and live. Linux and macOS are experimental:
  141. the test suite runs on them in CI, but the gateway has not been run live there,
  142. and autostart is Windows-only. Help wanted — see
  143. [ROADMAP](https://github.com/kdenischenko/open-agent-router/blob/main/ROADMAP.md).
  144. ## Commands
  145. All commands are `agent-router <command>`. Run `agent-router <command> --help` for every
  146. option.
  147. | Command | What it does |
  148. |---|---|
  149. | `init` | Create the gateway home, `config.toml`, tokens; `--allowed-root DIR` allows job dirs |
  150. | `serve` | Run the gateway on `127.0.0.1` (`--port` overrides `server.port`) |
  151. | `mcp` | Run an MCP server over stdio for orchestrator agents |
  152. | `status` | Show pool usage, expected pace and window resets in local time |
  153. | `advice` | Show matching routes for a tier (and `--mode read` or `write`) and why the others are excluded |
  154. | `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) |
  155. | `unblock POOL` | Remove a pool block set after a limit hit (admin token) |
  156. | `run [TEXT]` | Submit a job and wait up to 100 s; `--no-wait` prints the job id, `-` reads the prompt from stdin |
  157. | `wait JOB_ID` | Wait for a job and print its result; retries for up to 10 s while the gateway restarts |
  158. | `result JOB_ID` | Print the status and result of a job without waiting |
  159. | `rate JOB_ID good\|bad\|partial` | Rate a finished job; the last rating wins, a `--note` is stored as hash and length only |
  160. | `jobs` | List jobs with status, route, tier and creation time, optionally by `--status` |
  161. | `cancel JOB_ID` | Cancel a queued or running job |
  162. | `approve JOB_ID` / `deny JOB_ID` | Approve or deny a job that awaits confirmation (admin token) |
  163. | `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` |
  164. | `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 `'` |
  165. | `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 |
  166. | `classifier report` | Show classifier votes, errors and accuracy against ratings; `--json` adds the tier matrix and latency |
  167. | `classifier eval --models ID,...` | Replay past prompts through offline classifier models |
  168. Job history is kept forever by default. To bound it, set `retention_days = 30` in `[storage]`,
  169. then run `agent-router purge`. Age is measured from the job's finish time. Queued, running and
  170. awaiting-approval jobs are never purged, and `serve` does not purge automatically. Check the count
  171. first with `agent-router purge --dry-run`.
  172. `doctor --statusline-snippet` prints the settings for the Claude Code status line, which reports
  173. Claude usage to the gateway; see [docs/INSTALL.md](https://github.com/kdenischenko/open-agent-router/blob/main/docs/INSTALL.md).
  174. A route without an explicit `spend` inherits the usage source of its harness. When that source is
  175. `counter` and the counter of the route's pool cannot see the route's harness, the pool's `usd`
  176. window never counts the route's spending; `doctor` warns about it and suggests `spend = "journal"`,
  177. which records every job in the journal instead. A route that inherits `counter` on a pool with no
  178. counter is invisible in the same way, and `doctor` warns about it too.
  179. ## Exit codes
  180. Commands that call the gateway exit `5` when the gateway is unavailable or rejects the
  181. token, `6` when the request is denied with HTTP 4xx (including a full queue), and `1` on
  182. other errors. For `run`, `wait` and `result`, once the job state is known: `0` —
  183. `completed`, `2` — `partial`, `3` — `failed`, `declined` or `cancelled`, `4` — the job is
  184. not finished yet. `run --no-wait` exits `0` after a successful submit. Local errors
  185. (configuration, store, reading the prompt, a malformed `--resets-at`) exit `1`; `doctor --live`
  186. exits `1` unless every probe completes.
  187. Common failures and their fixes are in [docs/TROUBLESHOOTING.md](https://github.com/kdenischenko/open-agent-router/blob/main/docs/TROUBLESHOOTING.md).
  188. ## Environment variables
  189. - `AGENT_ROUTER_HOME` — directory with `config.toml`, tokens and stores; defaults to the
  190. per-user `agent-router` configuration directory.
  191. - `AGENT_ROUTER_URL` — gateway address for client commands and the Claude Code status line;
  192. defaults to `http://127.0.0.1:<server.port>` and must use `http` or `https`. Client commands
  193. report unsupported schemes or URL parsing errors as configuration errors (exit code `1`);
  194. the status line skips forwarding for these URLs and continues to render the limits.
  195. ## Adding a subscription or harness
  196. 1. **Pool.** Add a `[[pools]]` section with `[[pools.windows]]` for your plan:
  197. `unit = "percent"` for subscriptions that show a percentage, or `unit = "usd"` with
  198. `limit_usd` for subscriptions billed in dollars. Optional: `priority`, `weight` (a
  199. nudge in percentage points of lag) and `price_file` — a TOML table
  200. `"<model>" = [input, output]` (USD per 1M tokens) used when the harness does not
  201. report a cost.
  202. 2. **Harness.** For a new CLI, write an adapter module like
  203. `src/agent_router/adapters/opencode.py` exposing `HARNESS = HarnessSpec(...)` (name,
  204. adapter, executable names, spend source `counter`/`journal`), register an entry point
  205. in the `agent_router.harnesses` group in `pyproject.toml`, then `uv sync`. Adapter
  206. tests use redacted output samples in `tests/fixtures/` and never run the real CLI. If
  207. the executable is not in PATH, set `[backends.<name>] executable`.
  208. 3. **Routes.** Add `[[routes]]` with `pool`, `backend`, `model`, `tiers`, `quality`,
  209. `modes`; start a new route with `enabled = false`.
  210. 4. **Models.** To share one model across pools, give its routes a common `model_key` and
  211. order the pools in `[models."<model_key>"] prefer = [...]`.
  212. 5. **Verify.** `agent-router doctor` shows the harness, its version and enabled routes;
  213. `agent-router doctor --live` runs one short job per harness (needs a non-empty
  214. `allowed_roots`); `agent-router status` shows pool usage.
  215. ## Security
  216. agent-router is a local tool for a single user and **not a sandbox**: in `--mode write`
  217. the harness starts with auto-approved tools and can change any file your user can touch.
  218. The threat model and how to report a vulnerability are in
  219. [SECURITY.md](https://github.com/kdenischenko/open-agent-router/blob/main/SECURITY.md).
  220. A `read_mode_files_changed` violation on a read-mode job means the working tree changed
  221. while the job ran. If someone else wrote to the same repository in parallel, the
  222. violation is attributed to the job even though the executor changed nothing.
  223. ## Subscriptions
  224. Use only official ways to access the providers and follow their terms. You are
  225. responsible for complying with them. The project is not affiliated with the providers
  226. and does not bypass their restrictions.
  227. ## Contributing and roadmap
  228. Contributions are welcome: open an issue before a large change, follow
  229. [CONTRIBUTING.md](https://github.com/kdenischenko/open-agent-router/blob/main/CONTRIBUTING.md), and keep the gates green
  230. (`uv run ruff check`, `uv run ruff format --check`, `uv run pytest -q`). Plans — Linux
  231. and macOS support and an OpenAI-compatible proxy — are in
  232. [ROADMAP.md](https://github.com/kdenischenko/open-agent-router/blob/main/ROADMAP.md).
  233. ## License
  234. [MIT](https://github.com/kdenischenko/open-agent-router/blob/main/LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.