Meta Agent Tools
PT

Back to the catalog

AgentPool

See each coding-agent subscription's live limits and offload work to one with headroom.

Open source Open in the app JSON README (API)

About

See each coding-agent subscription's live limits and offload work to one with headroom.

Details

Kind
MCP servers
Topic
No topic detected
Publisher
sidduhere
Origin
official
Category
ferramentas
Transport
local
Version
0.1.13
Open pull requests
9
Last push
2026-08-05T02:23:06Z
Repository state
ativo
Language
Python
License
MIT
Added
2026-08-29 04:01:24
Updated
2026-08-29 04:01:24
Origin id
io.github.sidduHERE/agentpool

README

# 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`.

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

Then:

```bash
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:

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

Install from source:

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

Or run from a development checkout:

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

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

```bash
scripts/install.sh latest
```

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

## Quickstart

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

```bash
agentpool skills get agentpool
agentpool skills get core --full
```

```bash
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:

```bash
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:

```bash
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

```bash
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

| Provider id | Command | Usage status in v0.1 | Model pinning |
| --- | --- | --- | --- |
| `codex-cli` | `codex` | native local app-server rate-limit probe; CodexBar optional | `--model` + config-scoped reasoning/service tier |
| `cursor-cli` | `agent` or `cursor-agent` | optional CodexBar Cursor usage; native CLI usage is interactive `/usage` only | `--model` + read-only `--mode ask` |
| `claude-code` | `claude` | temporary `/usage` probe; ccusage telemetry optional | `--model` + `--effort` |
| `devin-cli` | `devin` | Devin/Windsurf plan-status API from existing CLI auth, with `/usage` fallback | `--model` |
| `copilot-cli` | `gh copilot` | GitHub Copilot usage API from env or `gh auth token` | forwarded `--model` |
| `droid-cli` | `droid` | unknown unless surfaced by future safe probe | process-local settings file + `--reasoning-effort` |
| `opencode` | `opencode` | configured adapter; usage unknown in this alpha | `--model` with provider/model ids |

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:

```bash
agentpool doctor --privacy --json
```

See [SECURITY.md](SECURITY.md) and
[docs/usage-detection.md](docs/usage-detection.md).

## MCP

Start the MCP server:

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

Example host config:

```bash
agentpool mcp-config --client generic
```

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

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

```bash
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:

```bash
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](docs/mcp-clients.md).
Team templates: [.cursor/mcp.json.example](.cursor/mcp.json.example),
[.mcp.json.example](.mcp.json.example), and [docs/examples/README.md](docs/examples/README.md).
MCP Registry metadata: [server.json](server.json). It advertises the
`agentpool-cli` PyPI package and should be bumped with each release. Release
checklist: [docs/release.md](docs/release.md).
Provider setup guides:
[Cursor](docs/setup-cursor.md),
[Cursor Agent CLI](docs/setup-cursor-cli.md),
[Codex](docs/setup-codex.md),
[Claude Code](docs/setup-claude-code.md),
[Copilot](docs/setup-copilot.md),
[Droid](docs/setup-droid.md), and
[Devin](docs/setup-devin.md).

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](docs/agent-cli-and-mcp.md).

## Development Checks

Development and CI checks are documented in [CONTRIBUTING.md](CONTRIBUTING.md).

More