The first agent with room
You rank the agents you use. An agent is only eligible when its usage reading is fresh and under 85%. Unknown or out of date means it is skipped.
← Back to abhirupbanerjee.com
- Available now
- Open source
- MIT
- v0.4.0 · alpha
- macOS and Linux
One task. The right agent. A human gate.
A quota-aware router for headless coding agent CLIs. It reads each agent's live usage meter, picks the first one with room, runs the task in a throwaway git worktree, tests it, leak-checks it and commits it locally. Then it stops. Nothing is pushed or merged without my approval of that exact commit.
worker_orderexample order
0built-in agent CLIs, plus any you define
85%used stops new full-size work
1failover per task, never more
0third-party dependencies, Python 3.10+
01 / OVERVIEW
What it does
Many developers use several AI coding agents, each with its own usage limit. The router decides which one gets the next task, so each allowance is used well and nothing ships without a check.
One task, headless, bounded
The task runs in a fresh git worktree with a lock on the repo, a hard timeout and a silence watchdog. If the agent fails, the task moves to the next eligible agent, trying each agent once and up to three in all.
Tests, leak scan, human approval
Tests run with one retry. A leak check blocks secrets. Push and merge each need a human approval bound to the exact commit.
02 / ARCHITECTURE
How the pieces connect
Solid boxes are on by default. Dashed boxes are optional. The dotted blue box is coming next. Tap any box to see what it does.
Tap a box
Each component shows its role.
On by defaultOptionalNeeds human approvalComing next
03 / LIFECYCLE
One task, start to merge
Scroll to move a task through each step.
STEP 01
04 / SELECTION
Why a route gets chosen
The same rules as the router's selector, running in your browser. The example order is Claude Code, Codex, Grok Build, Cursor, then a local model. Pick a scenario or move the meters and watch the choice change.
Task size
05 / USAGE AND FAILOVER
Fresh readings or nothing
Each agent's usage meter is refreshed on its own interval. Selection only trusts readings that are still fresh.
One hour of refreshes
A reading stays fresh for a short window after each refresh. A pool at 100% is skipped until it resets.
Failover, each agent once
Triggers: a failed exit, a usage-limit error, a timeout, or a long silence. Each agent is tried once, up to three per task, and only agents with room. A quota error also starts a cooldown.
06 / SAFETY
Nothing leaves without a check
The amber steps need explicit human approval, tied to one job, one action and one exact commit.
01Tests
Repo test command, 600 s limit. One retry with the failing tail.
02Leak check
Vendor key shapes, .env secrets and a private terms list. A hit blocks the commit. Nothing is deleted.
03Evidence
Diff summary, redacted diff and test output in one bundle.
04 · approvePush
Router refs only. Never forced. Opens a draft PR.
05CI watch
Polls PR checks with backoff and a timeout. Alerts on pass or fail.
06 · approveMerge
PR head must equal the approved commit. All required checks green.
07Done
No admin override and no auto-merge.
07 / STACKWICH
Verified before every commit
Optional, per agent. The agent plans, executes, verifies and checks its own work, then the router enforces strict gates before anything is committed.
08 / COMING NEXT
Where routing is going
What just landed, and what comes after.
Parallel lanes
Limits per agent
Cap how many runs each agent can take at once. An agent at its cap is skipped and the next one in your order gets the task.
Cooldown until reset
An agent that hits a usage limit is set aside until that limit resets, so the router stops retrying it in the meantime.
Scheduling by fit and quota
Large tasks split into independent pieces, each sent to the agent best suited to it with the most usage left.
Grok Bot as a last resort
Grok Bot coordinates, merges and reviews. It is never one of the parallel workers, and picks up a task only when no worker that can do it has enough tokens left.
Smarter switching
When an agent stalls or runs out, the next one picks up from a short handoff instead of starting over.
Token-efficient tiers
Light models for simple steps, strong models for hard ones, a human for anything irreversible.
A learning router
Routing that improves from real outcomes, with every change tested before it ships.
09 / INSTALL
Try it
Install from GitHub. Agent CLIs are not bundled; use the ones you already have.
Quick start
pipx install git+https://github.com/ovhirup/dynamic-llm-router
llm-router init # create a config
llm-router doctor # check your setup
Next steps
Each agent gets write access inside its own worktree. Full setup and configuration are in the README.