AgentPool

<!-- mcp-name: io.github.sidduHERE/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 terminate <session-id> --dry-run --json
agentpool terminate <session-id> --json

spawn defaults --initial-prompt-mode to provider_default. For Codex CLI this resolves to arg, which passes the first task as the Codex prompt argument instead of relying on a paste-and-submit startup cycle. Providers that expose reasoning controls also accept process-local overrides such as --reasoning-effort high; Codex also accepts --service-tier priority. AgentPool does not edit your provider config.

For AgentPool-created edit isolation, choose worktrees explicitly:

agentpool spawn \
  --provider <provider-id> \
  --repo . \
  --task "Make the small patch." \
  --role implementer \
  --isolation worktree

agentpool worktrees list --repo .
agentpool worktrees cleanup --session-id <session-id> --dry-run --json
agentpool worktrees cleanup --session-id <session-id>

Worktree isolation is not forced by default. Users often have their own worktree setup and cleanup rules, so AgentPool only creates a worktree when requested through --isolation worktree or policy configuration.

Usage And Capacity

agentpool usage-summary --refresh --json
agentpool usage-summary --refresh --no-interactive --json
agentpool stats --since 7d --json
agentpool usage-summary --refresh --backend codexbar --json
agentpool usage-summary --refresh --backend ccusage --provider claude-code --json

usage-summary returns a providers object keyed by provider id. It is not ordered and it is not a recommendation list. Each row includes usable, unusable_reason, quota windows, confidence, age/staleness, and reset timing when the provider exposes it. The older CLI capacity-summary command is retained as a human convenience alias; MCP also exposes get_capacity_summary as a compatibility alias for get_usage_summary.

The default buffer is policy.min_remaining_percent = 10. If any reported quota window is below that buffer, the provider row is marked unusable for the summary. Staleness is reported as age information only; it does not by itself make a provider unusable. If you want cached summary reads to refresh automatically after a threshold, set policy.usage_auto_refresh_after_seconds in ~/.agentpool/config.yaml. AgentPool still does not pick an alternative provider for you. MCP usage refreshes are intentionally bounded and may return partial=true; use the CLI commands above when a shell-capable agent needs a complete live refresh. Use --no-interactive or AGENTPOOL_NO_INTERACTIVE_USAGE=1 when a shell script must avoid provider TUI fallback probes.

Provider Matrix

Compatibility note: the PRD calls Factory's coding product factory-droid, but AgentPool exposes it as droid-cli because the installed command is droid. Do not add a duplicate factory-droid inventory row unless a distinct harness appears.

Privacy Posture

AgentPool is local-first, but usage probes can still be sensitive because they read existing CLI auth state and may call provider APIs on explicit refresh.

AgentPool does not:

• store provider credentials;
• read browser cookies by default;
• scrape browser dashboards;
• trigger login flows;
• silently accept paid overage.

AgentPool does store:

• SQLite session, event, usage snapshot, artifact, and lease metadata;
• transcript and artifact files under ~/.agentpool/artifacts by default;
• generated runtime settings that are not credentials.

Run:

agentpool doctor --privacy --json

See SECURITY.md and docs/usage-detection.md.

MCP

Start the MCP server:

agentpool mcp
agentpool mcp --toolsets default,stats
AGENTPOOL_MCP_LOCKDOWN=1 agentpool mcp

Example host config:

agentpool mcp-config --client generic

{
  "mcpServers": {
    "agentpool": {
      "command": "agentpool",
      "args": ["mcp"]
    }
  }
}

Verified install helpers (deeplink or one-liner shell command):

agentpool mcp-config --client cursor --absolute-command --install
agentpool mcp-config --client claude-code --absolute-command --install
agentpool mcp-config --client codex --absolute-command --install
agentpool mcp-config --client copilot-cli --absolute-command --install

Raw config generators:

agentpool mcp-config --client claude-code --json
agentpool mcp-config --client codex
agentpool mcp-config --client cursor
agentpool mcp-config --client claude-desktop --json

Use --absolute-command if the MCP host does not inherit your shell PATH. Verified per-host steps live in docs/mcp-clients.md. Team templates: .cursor/mcp.json.example, .mcp.json.example, and docs/examples/README.md. MCP Registry metadata: server.json. It advertises the agentpool-cli PyPI package and should be bumped with each release. Release checklist: docs/release.md. Provider setup guides: Cursor, Cursor Agent CLI, Codex, Claude Code, Copilot, Droid, and Devin.

MCP-connected agents should read these once on connect:

• agentpool://onboarding
• agentpool://skill.md
• agentpool://preferences.md

Then use tools for live operations. The user-owned preferences file also shows up through agentpool preferences and get_delegation_preferences(). It may say to use your native subagent system instead of AgentPool for some tasks. The default MCP toolset is deliberately small: inventory, usage snapshot, usage summary, provider models, preferences, spawn, observe, poll, send, interrupt, collect, artifact manifest, transcript paging, and terminate. Add opt-in toolsets with agentpool mcp --toolsets default,stats,sessions,leases,worktrees.

Shell-capable agents can use agentpool skills get agentpool instead of MCP resources to load the same core usage guidance from the installed CLI.

Coding agents with shell access should prefer the CLI path. It is more token-efficient because large worker output stays in artifact files and observe/collect return compact manifests by default. MCP remains first-class for MCP-native hosts and no-shell environments. See docs/agent-cli-and-mcp.md.

Development Checks

Development and CI checks are documented in CONTRIBUTING.md.