Crate claude_pool

Expand description

Coordinator/worker orchestration for Claude Code.

claude-pool manages N Claude CLI instances behind a pool. A coordinator (an interactive Claude session with the pool MCP server in its .mcp.json) dispatches work to worker slots, monitors results, reviews outputs, and decides what merges. Workers are isolated Claude instances that execute one task at a time.

This crate provides the pool library. For the MCP server binary, see claude-pool-server.

§The Coordinator/Worker Model

The coordinator/worker split is the central organizing principle:

Coordinator: A long-running interactive Claude session. It holds the human’s context, makes sequencing decisions, reviews outputs, and calls pool_* MCP tools to delegate work. It does not execute tasks directly; it schedules work and acts on results.
Worker: A Claude slot executing a single task (a pool_run, a chain step, or a fan-out branch). Workers are stateless between tasks; they receive a prompt, do the work, and return output. The pool handles slot assignment, session resumption, and restarts.

This model matters because it separates what to do (coordinator) from how to do it (worker). The coordinator stays responsive; workers run in parallel without blocking the human’s session.

§Vocabulary

§Nouns

Term	Meaning
Coordinator	Interactive Claude session that schedules and reviews work
Worker	A slot executing one task; returns output to the coordinator
Slot	A managed Claude CLI instance; the execution unit
Chain	Ordered pipeline of steps where each step feeds the next
Fan-out	N independent tasks running in parallel across slots
Task	A single unit of work submitted to the pool
Tick	One iteration of the coordinator’s monitor loop

§Verbs

Term	Meaning
schedule	Coordinator decides what work to dispatch next
execute	A worker carries out the scheduled task
monitor	Coordinator polls for results (tick loop)
review	Coordinator inspects worker output before acting
merge	Coordinator accepts a worker result into the main branch
dispatch	Coordinator sends a task to the pool
fan out	Submit N independent tasks in parallel
chain	Submit an ordered pipeline of dependent steps

§When to Use What

Inline: Do the work yourself without the pool. Use when the task is fast, single-step, or requires coordinator context that is impractical to inject.

pool_run / run: One task, one result, blocks until done. Use for single bounded operations (file a ticket, run a check, rebase a branch).

pool_chain / chain: Ordered pipeline where each step depends on the previous. Use when work has a clear linear dependency graph: draft -> review -> revise -> commit, or scaffold -> implement -> test -> PR. If you find yourself writing “and then” more than once, chain instead of run.

pool_fan_out / fan out: N independent tasks in parallel. Use when the same operation applies to N independent targets (audit N crates, refactor N modules). No step depends on another; all run simultaneously.

§Coordinator Rhythm

A coordinator session follows a repeating rhythm:

Dispatch: Submit tasks (pool_submit, pool_submit_chain, pool_fan_out). Receive task or chain IDs.
Monitor: Poll for results (pool_result, pool_chain_result). Repeat until complete. Each poll is a tick.
Review: Inspect output. Check diffs, test results, summaries. Decide whether to accept, reject with feedback, or escalate.
Merge: Accept the result (pool_approve_result for reviewed tasks, or direct merge for unreviewed chains). Update coordinator state.

Chains compress this into a single dispatch/monitor cycle. Fan-outs run monitor in parallel. With pool_submit_with_review, the coordinator explicitly gates on the review step before the result is finalized.

§Model Selection

Workers do not need the most capable model for every task. Match the model to the task complexity:

Haiku: Bounded single tasks – file a ticket, run checks, tag a release, rebase. High-volume fan-outs where throughput matters more than depth.
Sonnet: Multi-file changes, code review needing judgment, planning steps where quality matters, most chain steps.
Opus: Large mechanical refactors where one error breaks compilation, complex architectural reasoning, tasks where you would send a senior engineer.

Override per-task or per-chain-step with the model field in RunOptions. The coordinator itself typically runs on Sonnet or Opus; workers can use cheaper models for routine work.

§Architecture

Coordinator (interactive Claude session)
  +-- .mcp.json includes "claude-pool"
        +-- claude-pool MCP server
              +-- slot-0 (Claude instance)
              +-- slot-1 (Claude instance)
              +-- slot-N

One server. N slots. Nothing else.

§Getting Started

For most use cases, import the prelude module:

use claude_pool::prelude::*;

This brings in the most commonly needed types: Pool, PoolBuilder, TaskRecord, TaskState, ChainResult, and related types.

Re-exports§

pub use pool::DrainSummary;
pub use pool::Pool;
pub use pool::PoolBuilder;
pub use pool::PoolStatus;
pub use pool::RunOptions;
pub use error::Error;
pub use error::Result;
pub use chain::ChainIsolation;
pub use chain::ChainOptions;
pub use chain::ChainProgress;
pub use chain::ChainResult;
pub use chain::ChainStatus;
pub use chain::ChainStep;
pub use chain::StepAction;
pub use chain::StepFailurePolicy;
pub use chain::StepResult;
pub use chain::execute_chain;
pub use store::InMemoryStore;
pub use store::JsonFileStore;
pub use store::PoolStore;
pub use supervisor::SupervisorHandle;
pub use supervisor::check_and_restart_slots;
pub use messaging::Message;
pub use messaging::MessageBus;
pub use worktree::WorktreeManager;
pub use auto::AutoConfig;
pub use auto::AutoHint;
pub use auto::AutoResult;
pub use auto::AutoRoute;
pub use auto::AutoStep;
pub use auto::RoutePreference;
pub use types::*;

Modules§

auto: Auto-routing: let a single LLM call pick run/fan_out/chain.
chain: Chain execution — sequential pipelines of tasks.
config: Configuration resolution for slots and tasks.
error: Error types for claude-pool.
messaging: Inter-slot messaging for pool communication.
pool: Core pool engine for managing Claude CLI slots.
prelude: Commonly used types for working with claude-pool as a library.
route_test: Test harness for auto-routing accuracy.
store: Pluggable storage backend for pool state.
supervisor: Background supervisor loop for slot health monitoring.
types: Core types for claude-pool.
worktree: Git worktree isolation for parallel slots.