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.
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.4.0"
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. 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
| Command | What it does |
|---|---|
peerhub adapter discover |
Find which peer CLIs (agy/claude/codex) are installed and ready |
peerhub ask PEER PROMPT |
Dispatch a prompt to a real peer CLI (defaults to --capability-tier READ_ONLY) |
peerhub broadcast PROMPT --peers ag,cx |
Fan out one prompt to multiple peers with unified consensus |
peerhub diag |
Live multi-peer quota telemetry, headroom, and failover routing |
peerhub status |
Workspace health check |
peerhub config validate |
Check every config layer (workspace/global/built-in) resolves cleanly |
peerhub backup workspace / backup restore |
Live SQLite-snapshot backup and restore |
See peerhub --help for the full command list — including the governance/room/session surface (consensus, task, lesson, room, duty, session, ...), grouped into its own tier since it's primarily an API contract for automated multi-peer coordination (hub.py-parity), not something a human types day to day.
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.
Status
Released as v0.4.0. peerhub ask and the full governance/room/session command surface are real, working, and dispatch through peerhub's own governance, admission, and process-supervision layers today — not a stub. D-CTX (dispatch-context credential verification, closing the consensus-vote impersonation gap) is fully wired end-to-end as of this release. hub.py remains the authoritative system for production multi-peer coordination; peerhub is a real, tested candidate replacement, not yet a cutover.
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/real-dispatch integration tests (needs real CLIs installed & authenticated, real wall-clock time)
pyright # static type check, should report 0 errors
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.
1 maintainer
Metadata
1 maintainer
Release files for peerhub 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| peerhub-0.4.0.tar.gz | 468.7 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| peerhub-0.4.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.0 MB
Release files / peerhub-0.4.0.tar.gz
| Download URL | peerhub-0.4.0.tar.gz |
|---|---|
| Size | 468.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5d77d86804e5605ef7a1dd8cf81f8f841a0fd35f72414d3b147a3448b28e6fc0
|
|
BLAKE2b-256 checksum How to use checksums |
c884be3dd90baf88bc9487c707aaf909ce691c2a0ee80207a1aa47681112429e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logRelease files / peerhub-0.4.0-py3-none-any.whl
| Download URL | peerhub-0.4.0-py3-none-any.whl |
|---|---|
| Size | 577.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1865c4455569c3c039b680843351de820c015e51cbfaeef781fbe6683cb2785d
|
|
BLAKE2b-256 checksum How to use checksums |
a1ad4e73ca9fe5d0816436d055788a455aeeba70ffc65b5384d64e5c3407c8c5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logSecurity for peerhub 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for peerhub-0.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
