AgentPool

AgentPool

複数のコーディングエージェントのサブスクリプション（Codex、Claude Code、Cursor、 Copilot、Devin、Droid）を契約していても、同時に使うのは1つだけです。ほかは、 使用中のプロバイダーが5時間または週ごとの上限に達するまで使われず、その後は作業が 止まってしまいます。

AgentPoolは、契約しているすべてのコーディングエージェントのサブスクリプションについて、 現在の使用上限を読み取り、まだ余裕のあるものに作業を委任できるローカルのPython CLI兼 MCPサーバーです。すでに料金を支払っている容量を活用し、上限に達して作業を止めるのではなく、 そのまま続けられます。

AgentPoolは自動ルーティング機能ではなく、コントロールプレーンです。プロバイダー、 モデル、セッション、成果物、リース、およびベストエフォートの使用状況／容量の状態を リアルタイムで公開し、委任された作業を明示的なワーカーセッションとして実行します。 プロバイダーとモデルを選ぶのは、引き続きユーザーまたはエージェントです。AgentPoolは 上限を可視化して、情報に基づく選択を可能にします。選択が自動的に行われることはありません。

v0.1アルファ版では、保守的な方針を採用しています。

• デフォルトのランタイムはtmuxです。Terminal Controlは設定した場合にのみ利用できます。
• プロバイダーは明示的に選択します。provider=autoは拒否されます。
• 使用状況／容量のサマリーには信頼度が付与され、プロバイダーIDがキーになります。
• CodexBarとccusageは、インストールまたは設定されている場合に使用できる任意の使用状況ヘルパーです。
• AgentPoolはプロバイダーの認証情報を保存せず、ブラウザーの使用状況ページをスクレイピングせず、 モデルの順位付け、コードの統合、コードのプッシュも行いません。

要件

• Python 3.11以降。
• PATH上のtmux。
• 任意：Terminal Controlランタイムを使う場合は、PATH上のtermctrl。
• ワークツリーによる分離と差分の収集にGitが必要です。
• ライブランタイムを利用するにはmacOSまたはLinuxが必要です。WindowsはWSLのようなシェル経由を除き、 v0.1の対象ではありません。

インストール

AgentPoolはPyPIにagentpool-cliとして公開されています。インストール後のコマンドは agentpoolです。

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

続いて、次を実行します。

agentpool setup codex
agentpool doctor --deep --privacy

agentpool-cliパッケージはmacOS、Linux、Windowsにインストールできますが、ライブターミナル ランタイムに対応しているのはmacOSまたはLinuxです（WindowsではWSL経由）。

任意のTerminal Control設定：

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

ソースからインストールする場合：

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

または、開発用チェックアウトから実行します。

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

GitHubリリースからのインストール（タグに固定したwheelを使用し、PyPIは不要）にも 対応しています。

scripts/install.sh latest

初回起動、アップグレード、MCPの設定については、docs/install.mdを 参照してください。

クイックスタート

AIエージェントの場合は、まず同梱されているバージョン対応のスキルを読み込みます。

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

最後のコマンドは、最も頻繁に実行するものです。設定済みの各サブスクリプションについて、 残りの上限、リセット時刻、usableフラグが表示されるため、次のタスクをどのプロバイダーに 委任するかをすぐに確認できます。

プロバイダーを明示的に選択して、読み取り専用ワーカーを起動します。

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の--initial-prompt-modeのデフォルト値はprovider_defaultです。Codex CLIでは これがargに解決され、貼り付けて送信する起動手順に頼らず、最初のタスクをCodexのプロンプト引数として 渡します。推論制御を公開しているプロバイダーでは、--reasoning-effort highなどの プロセス単位の上書きも利用できます。Codexでは--service-tier priorityも利用できます。 AgentPoolはプロバイダーの設定を編集しません。

AgentPoolが作成する編集用の分離環境には、ワークツリーを明示的に選択します。

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>

ワークツリーによる分離はデフォルトでは強制されません。ユーザー独自のワークツリー設定や クリーンアップルールを使っていることが多いため、AgentPoolがワークツリーを作成するのは、 --isolation worktreeまたはポリシー設定で指定された場合のみです。

使用状況と容量

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 は、プロバイダー ID をキーとする providers オブジェクトを返します。並べ替えられておらず、推奨リストでもありません。各行には、usable、unusable_reason、クォータの各期間、信頼度、経過時間／古さ、およびプロバイダーが提供する場合はリセット時刻が含まれます。以前の CLI コマンド capacity-summary は、利用者向けのエイリアスとして引き続き使用できます。MCP でも、互換性エイリアスとして get_capacity_summary が get_usage_summary と同じ機能を提供します。

デフォルトのバッファーは policy.min_remaining_percent = 10 です。報告されたクォータ期間のいずれかがこのバッファーを下回ると、サマリーではそのプロバイダーの行が利用不可としてマークされます。古さは経過時間の情報としてのみ報告され、それだけでプロバイダーが利用不可になることはありません。しきい値を超えた後にキャッシュ済みのサマリーを自動更新するには、~/.agentpool/config.yaml で policy.usage_auto_refresh_after_seconds を設定します。 AgentPool が代替プロバイダーを選択することはありません。 MCP の使用状況の更新は意図的に制限されており、partial=true が返される場合があります。シェルを使用できるエージェントで完全なライブ更新が必要な場合は、上記の CLI コマンドを使用してください。シェルスクリプトでプロバイダーの TUI フォールバックプローブを回避するには、--no-interactive または AGENTPOOL_NO_INTERACTIVE_USAGE=1 を使用してください。

プロバイダーマトリクス

プロバイダー ID	コマンド	v0.1 での使用状況	モデルの固定
codex-cli	codex	ネイティブのローカル app-server レート制限プローブ。CodexBar は任意	--model ＋ 設定スコープの推論／サービスタイア
cursor-cli	agent または cursor-agent	任意の CodexBar Cursor 使用状況。ネイティブ CLI の使用状況は対話型の /usage のみ	--model ＋ 読み取り専用の --mode ask
claude-code	claude	一時的な /usage プローブ。ccusage テレメトリは任意	--model ＋ --effort
devin-cli	devin	既存の CLI 認証情報を使った Devin／Windsurf のプランステータス API。利用できない場合は /usage にフォールバック	--model
copilot-cli	gh copilot	環境変数または gh auth token を使った GitHub Copilot 使用状況 API	--model を転送
droid-cli	droid	今後、安全なプローブで取得可能になるまでは不明	プロセス内の設定ファイル ＋ --reasoning-effort
opencode	opencode	設定済みアダプター。このアルファ版では使用状況は不明	プロバイダー／モデル ID を指定した --model

互換性に関する注記：PRD では Factory のコーディング製品を factory-droid と呼んでいますが、インストールされるコマンドが droid であるため、AgentPool では droid-cli として公開しています。別個のハーネスが登場しない限り、factory-droid の重複したインベントリー行は追加しないでください。

プライバシーに関する方針

AgentPool はローカルファーストですが、使用状況プローブは既存の CLI 認証情報を読み取り、明示的な更新時にプロバイダー API を呼び出す場合があるため、機密性を伴う可能性があります。

AgentPool が行わないこと：

• プロバイダーの認証情報を保存すること。
• デフォルトでブラウザーの Cookie を読み取ること。
• ブラウザーのダッシュボードをスクレイピングすること。
• ログインフローを開始すること。
• 有料の超過利用を通知なしに承認すること。

AgentPool が保存するもの：

• SQLite のセッション、イベント、使用状況スナップショット、アーティファクト、リースのメタデータ。
• デフォルトでは ~/.agentpool/artifacts 以下のトランスクリプトおよびアーティファクトファイル。
• 認証情報を含まない、生成されたランタイム設定。

実行方法：

agentpool doctor --privacy --json

SECURITY.md および docs/usage-detection.md を参照してください。

MCP

MCP サーバーを起動します。

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

ホスト設定の例：

agentpool mcp-config --client generic

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

検証済みのインストールヘルパー（ディープリンクまたはシェルのワンライナーコマンド）：

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

生の設定を生成するツール：

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

MCP ホストがシェルの PATH を継承しない場合は、--absolute-command を使用してください。 ホストごとの検証済み手順は、docs/mcp-clients.md に記載されています。 チーム用テンプレート：.cursor/mcp.json.example、 .mcp.json.example、および docs/examples/README.md。 MCP Registry のメタデータ：server.json。このメタデータでは agentpool-cli PyPI パッケージを告知しており、リリースのたびに更新してください。リリース チェックリスト：docs/release.md。 プロバイダーのセットアップガイド： Cursor、 Cursor Agent CLI、 Codex、 Claude Code、 Copilot、 Droid、および Devin。

MCP に接続するエージェントは、接続時に以下を一度読み込んでください。

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

その後、リアルタイムの操作にはツールを使用してください。ユーザーが所有する設定ファイルは、 agentpool preferences と get_delegation_preferences() を通じても参照できます。タスクによっては、 AgentPool ではなくネイティブのサブエージェントシステムを使用するよう指示されている場合があります。 デフォルトの MCP ツールセットは意図的に小さくしています。内容は、インベントリ、使用状況のスナップショット、使用状況の概要、プロバイダーモデル、設定、起動、観察、ポーリング、送信、中断、収集、アーティファクトマニフェスト、トランスクリプトのページング、および終了です。オプトインのツールセットは、agentpool mcp --toolsets default,stats,sessions,leases,worktrees で追加してください。

シェルを利用できるエージェントは、MCP リソースの代わりに agentpool skills get agentpool を使用して、 インストール済み CLI から同じ基本的な使用ガイダンスを読み込めます。

シェルにアクセスできるコーディングエージェントは、CLI の使用を優先してください。ワーカーの大きな出力は アーティファクトファイルに保持され、observe／collect はデフォルトで簡潔なマニフェストを返すため、 トークン効率が高くなります。MCP は、MCP ネイティブのホストやシェルを利用できない環境向けの第一級の選択肢です。 docs/agent-cli-and-mcp.md を参照してください。

開発チェック

開発および CI のチェックについては、CONTRIBUTING.md に記載されています。