AgentPool

You pay for several coding-agent subscriptions — Codex, Claude Code, Cursor, Copilot, Devin, Droid — but you work in one at a time. The rest sit idle until your active provider hits its 5-hour or weekly limit, and then you stall.

AgentPool is a local Python CLI and MCP server that reads the live usage limits of every coding-agent subscription you have and lets you — or your primary agent — offload work to whichever one still has headroom. Use the capacity you already pay for, and keep moving instead of hard-stopping at a cap.

It is a control plane, not an auto-router. AgentPool exposes live provider, model, session, artifact, lease, and best-effort usage/capacity state, and runs the work you offload as explicit worker sessions. You or your agent still choose the provider and model — AgentPool makes the limits visible so that choice is informed, never automatic.

The v0.1 alpha posture is conservative:

• tmux is the default runtime; Terminal Control is optional when configured.
• Provider selection is explicit; provider=auto is rejected.
• Usage/capacity summaries are confidence-tagged and keyed by provider id.
• CodexBar and ccusage are optional usage helpers when installed or configured.
• AgentPool does not store provider credentials, scrape browser usage pages, rank models, merge code, or push code.

Requirements

• Python 3.11 or newer.
• tmux on PATH.
• Optional: termctrl on PATH for the Terminal Control runtime.
• Git for worktree isolation and diff collection.
• macOS or Linux for live runtimes. Windows is not a v0.1 target except through WSL-like shells.

Install

AgentPool publishes to PyPI as agentpool-cli; the installed command is agentpool.

uv tool install agentpool-cli      # recommended
pipx install agentpool-cli         # fallback
uvx agentpool-cli --help           # zero-install try

Then:

agentpool setup codex
agentpool doctor --deep --privacy

The agentpool-cli package installs on macOS, Linux, and Windows, but live terminal runtimes are supported on macOS or Linux (Windows via WSL).

Optional Terminal Control config:

runtime:
  default: tmux
  terminal_control:
    enabled: true
    binary: termctrl
    session_prefix: agentpool
    cols: 120
    rows: 36

Install from source:

git clone https://github.com/sidduHERE/agentpool.git
cd agentpool
uv tool install --force .

Or run from a development checkout:

uv venv
uv pip install -e ".[dev]"

A GitHub release install (wheel pinned to a tag, no PyPI required) is also supported:

scripts/install.sh latest

See docs/install.md for first-run, upgrade, and MCP setup notes.

Quickstart

For AI agents, start by loading the bundled version-matched skill:

agentpool skills get agentpool
agentpool skills get core --full

agentpool init
agentpool setup cursor
agentpool config validate
agentpool doctor --deep --privacy
agentpool setup all
agentpool smoke --provider fake-question --repo . --json
agentpool inventory --json
agentpool usage-summary --refresh --json

That last command is the one you will run most: it shows every configured subscription's remaining limit, reset time, and a usable flag, so you can see at a glance which provider to offload the next task to.

Start an explicitly selected read-only worker:

agentpool spawn \
  --provider <provider-id> \
  --repo . \
  --task "Inspect the project and ask one clarifying question." \
  --isolation read_only

agentpool observe <session-id> --wait-for completed,error,question,approval_prompt --timeout 60 --json
agentpool send <session-id> "Continue with the smallest useful check."
agentpool artifacts <session-id> --json
agentpool transcript <session-id> --tail-lines 80 --json
agentpool session show <session-id> --json
agentpool sessions --recent 10 --json
agentpool collect <session-id> --json
agentpool 

... [View full README on GitHub](https://github.com/sidduhere/agentpool#readme)