{
  "markdown": "# AgentPool\n\n<!-- mcp-name: io.github.sidduHERE/agentpool -->\n\nYou pay for several coding-agent subscriptions — Codex, Claude Code, Cursor,\nCopilot, Devin, Droid — but you work in one at a time. The rest sit idle until\nyour active provider hits its 5-hour or weekly limit, and then you stall.\n\nAgentPool is a local Python CLI and MCP server that reads the live usage limits\nof every coding-agent subscription you have and lets you — or your primary\nagent — offload work to whichever one still has headroom. Use the capacity you\nalready pay for, and keep moving instead of hard-stopping at a cap.\n\nIt is a control plane, not an auto-router. AgentPool exposes live provider,\nmodel, session, artifact, lease, and best-effort usage/capacity state, and runs\nthe work you offload as explicit worker sessions. You or your agent still choose\nthe provider and model — AgentPool makes the limits visible so that choice is\ninformed, never automatic.\n\nThe v0.1 alpha posture is conservative:\n\n- tmux is the default runtime; Terminal Control is optional when configured.\n- Provider selection is explicit; `provider=auto` is rejected.\n- Usage/capacity summaries are confidence-tagged and keyed by provider id.\n- CodexBar and ccusage are optional usage helpers when installed or configured.\n- AgentPool does not store provider credentials, scrape browser usage pages,\n  rank models, merge code, or push code.\n\n## Requirements\n\n- Python 3.11 or newer.\n- tmux on `PATH`.\n- Optional: `termctrl` on `PATH` for the Terminal Control runtime.\n- Git for worktree isolation and diff collection.\n- macOS or Linux for live runtimes. Windows is not a v0.1 target except through\n  WSL-like shells.\n\n## Install\n\nAgentPool publishes to PyPI as `agentpool-cli`; the installed command is\n`agentpool`.\n\n```bash\nuv tool install agentpool-cli      # recommended\npipx install agentpool-cli         # fallback\nuvx agentpool-cli --help           # zero-install try\n```\n\nThen:\n\n```bash\nagentpool setup codex\nagentpool doctor --deep --privacy\n```\n\nThe `agentpool-cli` package installs on macOS, Linux, and Windows, but live\nterminal runtimes are supported on macOS or Linux (Windows via WSL).\n\nOptional Terminal Control config:\n\n```yaml\nruntime:\n  default: tmux\n  terminal_control:\n    enabled: true\n    binary: termctrl\n    session_prefix: agentpool\n    cols: 120\n    rows: 36\n```\n\nInstall from source:\n\n```bash\ngit clone https://github.com/sidduHERE/agentpool.git\ncd agentpool\nuv tool install --force .\n```\n\nOr run from a development checkout:\n\n```bash\nuv venv\nuv pip install -e \".[dev]\"\n```\n\nA GitHub release install (wheel pinned to a tag, no PyPI required) is also\nsupported:\n\n```bash\nscripts/install.sh latest\n```\n\nSee [docs/install.md](docs/install.md) for first-run, upgrade, and MCP setup\nnotes.\n\n## Quickstart\n\nFor AI agents, start by loading the bundled version-matched skill:\n\n```bash\nagentpool skills get agentpool\nagentpool skills get core --full\n```\n\n```bash\nagentpool init\nagentpool setup cursor\nagentpool config validate\nagentpool doctor --deep --privacy\nagentpool setup all\nagentpool smoke --provider fake-question --repo . --json\nagentpool inventory --json\nagentpool usage-summary --refresh --json\n```\n\nThat last command is the one you will run most: it shows every configured\nsubscription's remaining limit, reset time, and a `usable` flag, so you can see\nat a glance which provider to offload the next task to.\n\nStart an explicitly selected read-only worker:\n\n```bash\nagentpool spawn \\\n  --provider <provider-id> \\\n  --repo . \\\n  --task \"Inspect the project and ask one clarifying question.\" \\\n  --isolation read_only\n\nagentpool observe <session-id> --wait-for completed,error,question,approval_prompt --timeout 60 --json\nagentpool send <session-id> \"Continue with the smallest useful check.\"\nagentpool artifacts <session-id> --json\nagentpool transcript <session-id> --tail-lines 80 --json\nagentpool session show <session-id> --json\nagentpool sessions --recent 10 --json\nagentpool collect <session-id> --json\nagentpool terminate <session-id> --dry-run --json\nagentpool terminate <session-id> --json\n```\n\n`spawn` defaults `--initial-prompt-mode` to `provider_default`. For Codex CLI\nthis resolves to `arg`, which passes the first task as the Codex prompt argument\ninstead of relying on a paste-and-submit startup cycle. Providers that expose\nreasoning controls also accept process-local overrides such as\n`--reasoning-effort high`; Codex also accepts `--service-tier priority`.\nAgentPool does not edit your provider config.\n\nFor AgentPool-created edit isolation, choose worktrees explicitly:\n\n```bash\nagentpool spawn \\\n  --provider <provider-id> \\\n  --repo . \\\n  --task \"Make the small patch.\" \\\n  --role implementer \\\n  --isolation worktree\n\nagentpool worktrees list --repo .\nagentpool worktrees cleanup --session-id <session-id> --dry-run --json\nagentpool worktrees cleanup --session-id <session-id>\n```\n\nWorktree isolation is not forced by default. Users often have their own\nworktree setup and cleanup rules, so AgentPool only creates a worktree when\nrequested through `--isolation worktree` or policy configuration.\n\n## Usage And Capacity\n\n```bash\nagentpool usage-summary --refresh --json\nagentpool usage-summary --refresh --no-interactive --json\nagentpool stats --since 7d --json\nagentpool usage-summary --refresh --backend codexbar --json\nagentpool usage-summary --refresh --backend ccusage --provider claude-code --json\n```\n\n`usage-summary` returns a `providers` object keyed by provider id. It is not\nordered and it is not a recommendation list. Each row includes `usable`,\n`unusable_reason`, quota windows, confidence, age/staleness, and reset timing when\nthe provider exposes it. The older CLI `capacity-summary` command is retained\nas a human convenience alias; MCP also exposes `get_capacity_summary` as a\ncompatibility alias for `get_usage_summary`.\n\nThe default buffer is `policy.min_remaining_percent = 10`. If any reported\nquota window is below that buffer, the provider row is marked unusable for the\nsummary. Staleness is reported as age information only; it does not by itself\nmake a provider unusable. If you want cached summary reads to refresh\nautomatically after a threshold, set `policy.usage_auto_refresh_after_seconds`\nin `~/.agentpool/config.yaml`.\nAgentPool still does not pick an alternative provider for you.\nMCP usage refreshes are intentionally bounded and may return `partial=true`;\nuse the CLI commands above when a shell-capable agent needs a complete live\nrefresh. Use `--no-interactive` or `AGENTPOOL_NO_INTERACTIVE_USAGE=1` when a\nshell script must avoid provider TUI fallback probes.\n\n## Provider Matrix\n\n| Provider id | Command | Usage status in v0.1 | Model pinning |\n| --- | --- | --- | --- |\n| `codex-cli` | `codex` | native local app-server rate-limit probe; CodexBar optional | `--model` + config-scoped reasoning/service tier |\n| `cursor-cli` | `agent` or `cursor-agent` | optional CodexBar Cursor usage; native CLI usage is interactive `/usage` only | `--model` + read-only `--mode ask` |\n| `claude-code` | `claude` | temporary `/usage` probe; ccusage telemetry optional | `--model` + `--effort` |\n| `devin-cli` | `devin` | Devin/Windsurf plan-status API from existing CLI auth, with `/usage` fallback | `--model` |\n| `copilot-cli` | `gh copilot` | GitHub Copilot usage API from env or `gh auth token` | forwarded `--model` |\n| `droid-cli` | `droid` | unknown unless surfaced by future safe probe | process-local settings file + `--reasoning-effort` |\n| `opencode` | `opencode` | configured adapter; usage unknown in this alpha | `--model` with provider/model ids |\n\nCompatibility note: the PRD calls Factory's coding product `factory-droid`, but\nAgentPool exposes it as `droid-cli` because the installed command is `droid`.\nDo not add a duplicate `factory-droid` inventory row unless a distinct harness\nappears.\n\n## Privacy Posture\n\nAgentPool is local-first, but usage probes can still be sensitive because they\nread existing CLI auth state and may call provider APIs on explicit refresh.\n\nAgentPool does not:\n\n- store provider credentials;\n- read browser cookies by default;\n- scrape browser dashboards;\n- trigger login flows;\n- silently accept paid overage.\n\nAgentPool does store:\n\n- SQLite session, event, usage snapshot, artifact, and lease metadata;\n- transcript and artifact files under `~/.agentpool/artifacts` by default;\n- generated runtime settings that are not credentials.\n\nRun:\n\n```bash\nagentpool doctor --privacy --json\n```\n\nSee [SECURITY.md](SECURITY.md) and\n[docs/usage-detection.md](docs/usage-detection.md).\n\n## MCP\n\nStart the MCP server:\n\n```bash\nagentpool mcp\nagentpool mcp --toolsets default,stats\nAGENTPOOL_MCP_LOCKDOWN=1 agentpool mcp\n```\n\nExample host config:\n\n```bash\nagentpool mcp-config --client generic\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"agentpool\": {\n      \"command\": \"agentpool\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nVerified install helpers (deeplink or one-liner shell command):\n\n```bash\nagentpool mcp-config --client cursor --absolute-command --install\nagentpool mcp-config --client claude-code --absolute-command --install\nagentpool mcp-config --client codex --absolute-command --install\nagentpool mcp-config --client copilot-cli --absolute-command --install\n```\n\nRaw config generators:\n\n```bash\nagentpool mcp-config --client claude-code --json\nagentpool mcp-config --client codex\nagentpool mcp-config --client cursor\nagentpool mcp-config --client claude-desktop --json\n```\n\nUse `--absolute-command` if the MCP host does not inherit your shell `PATH`.\nVerified per-host steps live in [docs/mcp-clients.md](docs/mcp-clients.md).\nTeam templates: [.cursor/mcp.json.example](.cursor/mcp.json.example),\n[.mcp.json.example](.mcp.json.example), and [docs/examples/README.md](docs/examples/README.md).\nMCP Registry metadata: [server.json](server.json). It advertises the\n`agentpool-cli` PyPI package and should be bumped with each release. Release\nchecklist: [docs/release.md](docs/release.md).\nProvider setup guides:\n[Cursor](docs/setup-cursor.md),\n[Cursor Agent CLI](docs/setup-cursor-cli.md),\n[Codex](docs/setup-codex.md),\n[Claude Code](docs/setup-claude-code.md),\n[Copilot](docs/setup-copilot.md),\n[Droid](docs/setup-droid.md), and\n[Devin](docs/setup-devin.md).\n\nMCP-connected agents should read these once on connect:\n\n- `agentpool://onboarding`\n- `agentpool://skill.md`\n- `agentpool://preferences.md`\n\nThen use tools for live operations. The user-owned preferences file also shows\nup through `agentpool preferences` and `get_delegation_preferences()`. It may\nsay to use your native subagent system instead of AgentPool for some tasks. The\ndefault MCP toolset is deliberately small: inventory, usage snapshot, usage\nsummary, provider models, preferences, spawn, observe, poll, send, interrupt,\ncollect, artifact manifest, transcript paging, and terminate. Add opt-in\ntoolsets with `agentpool mcp --toolsets default,stats,sessions,leases,worktrees`.\n\nShell-capable agents can use `agentpool skills get agentpool` instead of MCP\nresources to load the same core usage guidance from the installed CLI.\n\nCoding agents with shell access should prefer the CLI path. It is more\ntoken-efficient because large worker output stays in artifact files and\n`observe`/`collect` return compact manifests by default. MCP remains first-class\nfor MCP-native hosts and no-shell environments. See\n[docs/agent-cli-and-mcp.md](docs/agent-cli-and-mcp.md).\n\n## Development Checks\n\nDevelopment and CI checks are documented in [CONTRIBUTING.md](CONTRIBUTING.md).\n",
  "bytes": 11500,
  "sha": "34af7ee1b6950f2bf222515ed57d37dd492c1e3a75d4ce66bea03d145cc6e26a",
  "repo_slug": "sidduhere/agentpool",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sidduhere_agentpool_5593e7f3/readme"
}