Claude Pool
Managed pool of Claude Code sessions — daemon and socket API.
Claude Pool runs a persistent daemon that manages a pool of pre-started Claude Code sessions. Sessions are automatically kept alive, offloaded when idle, and restored on demand. Any number of clients can connect to the same pool simultaneously.
Status
🚧 In development — core functionality working, integration-tested with real Claude sessions.
Architecture
┌─────────────────────────────────────────────┐
│ Clients (connect via Unix socket) │
│ • claude-pool CLI (separate package) │
│ • Open Cockpit (Electron app) │
│ • Python package (planned) │
│ • Any tool speaking newline-delimited JSON │
├═══════════════════ socket ══════════════════┤
│ Claude Pool daemon (one per pool) │
│ • Pool lifecycle (init/resize/destroy) │
│ • Session management + LRU eviction │
│ • In-process PTY management (creack/pty) │
│ • Session offload/restore │
│ • Terminal attachment (raw PTY pipes) │
└─────────────────────────────────────────────┘
See docs/architecture.md for full details.
Install
Prerequisites: Go 1.23+, Claude Code installed and on $PATH.
git clone https://github.com/EliasSchlie/claude-pool
cd claude-pool
make install # builds + symlinks to ~/.local/bin/
claude-pool install # installs global hooks + Claude Code skill (run once per machine)
make install symlinks claude-pool (daemon) and claude-pool-cli (CLI) into ~/.local/bin/. Ensure that directory is on your $PATH.
claude-pool install writes the global hook runner into ~/.claude-pool/hook-runner.sh, registers SessionStart and PreToolUse hooks in ~/.claude/settings.json, and installs the Claude Code skill at ~/.claude/skills/claude-pool/SKILL.md. Run claude-pool uninstall to reverse.
Quick Start
# 1. Initialize a pool (starts daemon, creates 3 slots)
claude-pool-cli init --size 3
# 2. Run a task and wait for the result
claude-pool-cli start --prompt "summarize this repo" --block
# 3. List sessions
claude-pool-cli ls
# 4. Send a follow-up to an existing session
claude-pool-cli followup --session abc123 --prompt "add tests" --block
# 5. Tear down when done
claude-pool-cli destroy --confirm
Usage
Sending Prompts
# Start a session and block until done (prints output)
claude-pool-cli start --prompt "fix the login bug" --block
# Start a session in the background; get the session ID
claude-pool-cli start --prompt "refactor auth module"
# → {"sessionId":"a7f2x9","status":"processing"}
# Follow up on an existing session
claude-pool-cli followup --session a7f2x9 --prompt "add error handling" --block
# Wait for any busy session (auto-detects parent when called from Claude Code)
claude-pool-cli wait --timeout 60000
Observing Sessions
claude-pool-cli ls # list active sessions
claude-pool-cli ls --status idle,processing # filter by state
claude-pool-cli ls --verbosity nested # include child sessions
claude-pool-cli info --session abc123 # full session details
claude-pool-cli capture --session abc123 # get output immediately
Pool Management
claude-pool-cli health # pool status and slot counts
claude-pool-cli resize --size 5 # grow/shrink slot count
claude-pool-cli config --set flags="--model claude-opus-4-5"
claude-pool-cli pools # list all known pools
Named Pools
Each pool is fully independent — its own daemon, directory, and config:
claude-pool-cli --pool work init --size 3
claude-pool-cli --pool work start --prompt "review the PR"
claude-pool-cli --pool scratch init --size 1 --flags "--model claude-haiku-3-5"
Attaching to a Session (Live Terminal)
# Start without a prompt to claim a slot interactively
claude-pool-cli start
# → {"sessionId":"x9k2m1","status":"idle"}
# Attach for live PTY I/O (like SSH into the session)
claude-pool-cli attach --session x9k2m1
# Disconnect with ~. (tilde-dot on a fresh line)
Session Lifecycle
claude-pool-cli stop --session abc123 # interrupt or cancel
claude-pool-cli archive --session abc123 # mark done, hide from ls
claude-pool-cli archive --session abc123 --recursive # include children
claude-pool-cli unarchive --session abc123 # restore archived session
Debug
claude-pool-cli debug logs --follow # tail daemon log
claude-pool-cli debug slots # slot states and session mapping
claude-pool-cli debug input --session abc123 --data $'\x03' # send Ctrl+C
Session States
EliasSchlie
EliasSchlie
