peerhub

A lightweight, installable coordination layer for orchestrating multiple AI CLI agents (Claude, Codex, Antigravity, ...) as collaborating peers: dispatch, routing, consensus, and health. It's built to eventually replace an existing hand-rolled multi-peer coordination system (hub.py) with a proper, tested package.

Quick start

pip install peerhub

# Auto-detect which peer CLIs (agy/claude/codex) are installed and ready
peerhub adapter discover

# Genuinely dispatch a prompt to a real peer and get its response
peerhub ask ag "say hello in exactly three words"

# Live multi-peer quota telemetry, headroom, and failover routing
peerhub diag

# Check a workspace (reports "uninitialized" if no database yet)
peerhub status

peerhub ask works end-to-end today: it genuinely dispatches through peerhub's own governance, admission, and process-supervision layers and returns the real response. See "Key commands" below for the full reference, including the governance/room/session surface used by automated multi-peer coordination (consensus, task, lesson, room, duty, session, ...) — peerhub --help groups all of it into tiers so the everyday commands above aren't buried under the 30 total top-level commands, then prints the complete leaf-command catalog. -h, --help, and the Windows-style /? work at the root and after every nested command path.

Install

Option A: Install from PyPI (Recommended)

pip install peerhub

Option B: Install an exact GitHub release

pip install "git+https://github.com/greatgc-flow/peerhub.git@v0.9.1"

The commands above install the stable v0.9.1 line. Development changes after that release remain on main until the next version is cut.

Option C: Local editable development install

git clone https://github.com/greatgc-flow/peerhub.git
cd peerhub
pip install -e .          # runtime only
pip install -e .[dev]     # + pytest, pyright, hypothesis, alembic (needed to run tests/type-check locally)

Requires Python >= 3.11 (declared matrix 3.11-3.14 x ubuntu/windows: all 8 cells VERIFIED-CI, green CI run https://github.com/greatgc-flow/peerhub/actions/runs/37189754726, evidence docs/m1_impl/matrix_evidence/ci-run-37189754726.json; the earlier windows py3.11-3.13 local run is VERIFIED-LOCAL, evidence docs/m1_impl/matrix_evidence/windows-py3.11-3.13.json; any future cell without run evidence is UNVERIFIED, TD-18). This installs the peerhub package and registers a peerhub entrypoint on your PATH (verified via a real sdist build + install: pyproject.toml's [project.scripts] defines only peerhub, not a separate hub alias). python -m peerhub works too.

Key commands

peerhub --help is the authoritative command inventory. Every current top-level command is listed here with its one-line purpose.

Try it

Use a separate workspace for this walkthrough; every command below refers to the same ./peerhub-demo directory.

# Initialize the workspace first.
peerhub workspace init --workspace ./peerhub-demo

# Send one prompt, then fan the same kind of work out to two configured peers.
peerhub ask cx "Summarize this repository" --workspace ./peerhub-demo
peerhub broadcast "List one risk." --peers cx,ag --workspace ./peerhub-demo

# Create, start, and complete a task.
peerhub task create --workspace ./peerhub-demo --task-id docs-demo --summary "Refresh docs" --spec "Add a usage example." --creator cx
peerhub task claim-start --workspace ./peerhub-demo --task-id docs-demo --actor cx --request-id docs-demo-request --coordinator cx --attempt-id docs-demo-attempt
peerhub task complete --workspace ./peerhub-demo --task-id docs-demo --actor cx

# Propose a consensus round and cast its first vote.
peerhub consensus propose --workspace ./peerhub-demo --round-id docs-demo-round --title "Adopt docs" --question "Adopt the README update?" --body "Approve the proposed README example." --proposer cx --required cx,ag --eligible cx,ag
peerhub consensus vote --workspace ./peerhub-demo --round-id docs-demo-round --actor cx --choice agree

ask also accepts --workspace PATH (default .), --profile PROFILE_ID, --timeout-seconds/--silence-timeout-seconds/--max-output-bytes (process limits), and --json. Exit codes: 0 verified response, 2 usage/config/pre-spawn failure (unknown peer, executable not found, readiness probe failed), 3 definite peer/protocol failure, 4 uncertain execution (timeout, lost lease ownership), 130 interrupted. It requires the real peer CLI (agy.exe/claude.cmd/codex.cmd) to be installed and authenticated on your machine — ask will tell you clearly if it can't find or run one, rather than failing silently.

Scenario cookbook (all 30 command groups)

These are safe starting points, not a second command specification. Run peerhub /? for the generated 109-leaf catalog and peerhub <path> /? for the authoritative arguments and description at any depth.

Feedback loop

Use feedback add → list → resolve for product/process gaps, error report → review list → review resolve for repeatable runtime failures, and lesson propose → approve → activate → retire/supersede for rules learned from the evidence. These are durable workspace records rather than loose notes. The group-level /? pages contain copyable end-to-end examples. For package bugs, use the GitHub issue templates and include peerhub --version, peerhub config paths --json, peerhub config validate --json, and peerhub diag --json; remove prompts/transcripts or secrets before attaching output.

Status

Released as v0.9.1. Patch release resolving the two-layer Claude quota exhaustion classification and error propagation defect: stream-json 429 rejections are classified as quota exhaustion rather than generic protocol errors, and QUOTA_EXHAUSTED propagates directly through the dispatch terminal_error_code layer.

Released as v0.9.0. All twelve advertised AG/Claude/Codex profiles (standard, effort, deepthink, and pro for each peer) have reviewed packaged model bindings and live dispatch evidence. diag --live now polls the portable runtime without requiring an initialized workspace, labels measured quota separately from executable-only discovery, and refuses to recommend a critical quota/pacing target. The complete 109-leaf CLI supports -h, --help, and /? recursively, with generated descriptions, argument help, workflows, and feedback-loop examples. Adapter contracts and active docs now match AG 1.2.12, Claude Code 2.1.283 stream JSON, and Codex 0.157.1 JSONL. The full governance/room/session surface still dispatches through PeerHub's governance, admission, and process-supervision layers; intentional direct CLI boundaries remain enumerated in docs/design/peerhub-production-call-map-R1.json.

For the detailed development history — implementation status by feature, deferred items with their triggers, the hub.py-replacement roadmap, and the full architecture debate record — see docs/STATUS.md.

Run the tests

pytest -q                 # fast suite, no real CLI calls
pytest -q -m slow          # + the real-adapter integration tests (needs real CLIs installed & authenticated, real wall-clock time)
pytest -q -m e2e           # + genuine end-to-end `peerhub ask` dispatch through a real peer CLI (separate marker from slow -- also needs real CLIs)
pyright                    # static type check, should report 0 errors

The deterministic suite runs on every push and pull request. The slow and e2e tiers consume real provider quota, so they run on the dedicated peerhub-live self-hosted runner for releases and for changes to adapters, provider protocols, model bindings, or quota telemetry. PyPI publication is blocked until both live tiers pass. The runner must have authenticated agy.exe, claude.cmd, and codex.cmd commands on PATH. Fork pull requests never run automatically on that credential-bearing machine; after reviewing a fork, a maintainer can use the live workflow's manual dispatch on a trusted ref. Manual dispatch of the publish workflow validates and builds an artifact but does not publish it—only a published GitHub Release can reach PyPI.

Contributing / reporting issues

See CONTRIBUTING.md to contribute, report a bug, or request a feature.

This repo's own convention (see docs/history/design/2026-08/FACT-REFRESH-PROCEDURE-R1.md) is to never cite a specific "current passing count" in this file — it changes with nearly every commit. Run pytest -q yourself for the real, current number.