PeerHub

A durable communication layer for collaborating AI peers. The Core owns only Peer, Stream, Record and Offset. Runtime delivery, observations, diagnostics, work continuity and collaboration capabilities are extensions.

Install

Requires Python 3.11–3.14. Choose one:

pipx install peerhub
uv tool install peerhub
pip install peerhub

A winget package is not provided.

Develop from this checkout

Requires Python 3.11–3.14.

python -m pip install -e ".[dev]"
peerhub --help
peerhub --version

This describes current source, not a newly published release. The public command is peerhub; the temporary milestone-specific entrypoint has been retired. python -m peerhub and python -m peerhub.cli use the same public CLI.

Core recipe

The Core stores Peers, Streams, immutable Records, and per-peer Offsets. These commands use a new core-demo Stream in the selected store and call no provider:

peerhub peer register --peer reader --name "Demo reader"
peerhub stream create --stream core-demo --members reader
peerhub record append --stream core-demo --author-peer reader --kind message --body '"Hello"' --idempotency-key core-demo-001 --created-at 2026-10-10T00:00:00Z
peerhub record read --stream core-demo --after 0 --limit 10
peerhub offset get --peer reader --stream core-demo
peerhub offset advance --peer reader --stream core-demo --position 1 --revision 1
peerhub offset get --peer reader --stream core-demo

On an existing Stream, advance to the position you actually read and pass the revision returned by offset get; the revision is a compare-and-swap guard. Keep the same body, timestamp, and idempotency key when retrying an append.

Everyday commands

# Persist the prompt, execute one provider, and persist its response.
peerhub ask cx "Summarize this repository" --stream review --request-id review-001

# Explicit collection may contact provider CLIs.
peerhub observation refresh --peers cx cc ag
peerhub observation refresh --peers cc --system-dir D:\tools\portable  # explicit provider installation directory

# Read committed observations without probing or writing.
peerhub diag
peerhub diag quota --json
peerhub diag health
peerhub diag --live --interval-seconds 2
peerhub diag --view rich

# Collect quota evidence and watch the dashboard in one loop.
peerhub monitor --interval-seconds 60
peerhub monitor --view plain --cycles 1

# Review with a second provider using a declared profile.
peerhub ask cc "Explain the Core Peer, Stream, Record and Offset flow" --stream learning --request-id learning-001 --profile cc.standard --json

The two ask examples require the corresponding vendor CLI to be installed and authenticated, and spend provider quota. See the adapter guide.

Builtin provider names are cx/codex, cc/claude and ag/agy. Custom Peer identities can be registered with peer register --peer worker --adapter cx.

ask supports explicit --profile, --model, --effort, --writable, --resume, --timeout-seconds, optional --silence-timeout-seconds, --max-output-bytes, --author-peer and --json. Profile policy resolves workspace → global → packaged defaults; it does not assert measured model availability. Retrying the same --request-id reuses a completed response. A different prompt or binding conflicts, and an uncertain execution requires explicit reconciliation before another execution. By default, each ask starts a fresh session with bounded Stream catch-up. For CLI peers (cc, cx, ag), --resume reuses the native vendor session of this peer/stream when compatible; otherwise it starts a fresh session with bounded catch-up. Repeat the flag on each continuing ask. --json includes effective_mode, fallback_reason, and injected_record_ids when the Bridge exposes delivery details.

--writable is off by default. It maps to cc --permission-mode acceptEdits, cx -s workspace-write (default -s read-only), and ag --mode accept-edits. cx resume inherits the sandbox of the initial session and does not accept -s; writable mode is therefore part of the session binding, and changing it starts a fresh generation.

Quota is collected separately from diagnostics. diag --fresh has been replaced by observation refresh. Unmeasured values remain UNKNOWN or another explicit evidence state, and expired measurements become STALE. --workspace is an ask option; for monitor and observation refresh use the global --db, e.g. peerhub --db <workspace>/.peerhub/core.db monitor.

diag --live repeatedly reads committed snapshots only. --cycles N bounds the number of frames; --json emits one JSON object per line in live mode. Watching never refreshes quota or changes stored data.

The monitor/diag screen shows a threat summary, a stable pool table with usage, PACE in percentage points, reset countdown, conditional forecast and freshness, then credits, latest asks, probe health and one legend/controls line. PACE is measured usage minus elapsed window percentage; positive means faster than even. Forecasts require 5 percentage points used and 10% elapsed (20% for windows of at least one day); projected reset use of at least 105% is a threat. Below the support gates the screen says “not enough data”. Inferred anchors remain conditional and predictive accuracy is not established.

Monitor runs collection cycles every N seconds (--interval-seconds), collecting initially and then every Kth cycle (--collect-every). On a TTY with VT support, both dashboard styles redraw in place, with countdown updates at most 1 Hz; PACE and forecast ETA remain anchored to the measurement. Live diagnostics overwrite each snapshot every N seconds. Non-TTY or unavailable VT output appends one frame per cycle without escapes; JSON emits one object per cycle. NO_COLOR suppresses colour while retaining supported cursor controls.

Store selection and existing data

The store is .peerhub/core.db. Discovery picks the nearest one (current directory, <cwd>/peerhub, then parents); --db PATH or PEERHUB_DB choose explicitly. peerhub diag health reports store_selection (the path and how it was chosen: env, explicit, discovered, workspace-default, default). Developer scratch (live-gate JUnit etc.) goes under .peerhub/work/; the top of .peerhub/ holds the database and its restore.epoch metadata.

Use global --db PATH before the command, or PEERHUB_DB, to select a store explicitly. An explicit missing path is never redirected to another store. ask --workspace DIR uses that directory's store unless a database was explicitly selected. Read-only commands do not create a missing store.

Monitor and diagnostics refuse a missing selected database with exit 5 before any probes. Create it explicitly with peerhub --db <path> peer register --peer <id> --name <name>. Observation refresh also refuses a missing automatically selected store, including in a non-repository directory; an explicit --db or PEERHUB_DB retains its existing collection bootstrap behaviour.

Common tasks

Resume across two turns (--resume)

To continue an active multi-turn conversation with the same vendor session:

# Turn 1: Initial prompt on a dedicated stream
peerhub ask cx "Explain the store schema" --stream convo-01 --request-id turn-001

# Turn 2: Continue using the native session
peerhub ask cx "Now show an append example" --stream convo-01 --request-id turn-002 --resume

Recover from a blocked stream

When a turn encounters a timeout, silence abort, or disconnect, the stream may enter blocked_uncertain. Retrying the same --request-id cannot replay an uncertain execution because it may have partially executed remotely. To recover safely, start subsequent turns on a new stream:

# Inspect the current health and failure state
peerhub diag health --stream convo-01

# Recover: include a short summary of the committed context in the new prompt
peerhub ask cx "Context: We reviewed the Core schema; Peer, Stream, Record and Offset are the four primitives. Next, show an append example." --stream convo-02 --request-id rec-001

A fresh stream cannot see the old stream's records. Replace the example context with a short summary of your committed work and the next safe action. Inspect the old records with peerhub record read --stream convo-01 --after 0 --limit 10 if needed; an uncertain remote action may already have occurred, so do not assume it failed or replay its request ID.

Offline read-only checks

diag inspects local database state and committed snapshots without contacting provider networks or consuming quota:

# Read-only store and stream diagnostics
peerhub diag
peerhub diag health
peerhub diag quota --json

Upgrade

pipx upgrade peerhub
# or
uv tool upgrade peerhub
# or
pip install --upgrade peerhub

Uninstall

pipx uninstall peerhub
# or
uv tool uninstall peerhub
# or
pip uninstall peerhub

Note: Uninstalling the package removes executable entrypoints but retains the local database and artifacts in .peerhub/. To delete store data, remove the .peerhub/ directory manually.

Package structure

peerhub/
  core/          Peer, Stream, Record, Offset; SQLite storage
  extensions/    Bridge, Observation, Diag, Artifact, Work, Search, Routing, …
  cli/           public parser and command handlers
  config_data/   packaged provider model defaults
tests/
  communication/ Core, delivery, observations, migration and package gates
  continuity/    extension host, artifacts, work, skills, backup and eval
  collaboration/ federation, memory, search, routing, orchestration and approval
tools/
  command_inventory.py
  traceability.py
  release_evidence.py

Milestones describe development progress, not runtime ownership. Frozen specifications, historical evidence and existing durable wire/storage identifiers retain their original names. See the cleanup decisions and AG review.

Doc map

• Documentation map: Single documentation map and navigation index.
• CONTRIBUTING.md: maintainer setup, tests, feedback, and release gates.
• Adapter guide and CLI reference: provider invocation and troubleshooting.
• Configuration and model profiles: store selection and profile defaults.
• Usage/evolution guide: Core flow and milestone scope.
• Structure cleanup: current ownership and retired surfaces.
• M2 contracts: extension host and durable continuity contracts.

Limitations

• On Windows, cx --writable cannot write into directories with owner-only ACLs (e.g. pytest tmp dirs, tempfile.mkdtemp); use a normally created directory.
• Paths containing spaces or special characters can expose quoting problems in external Windows launchers. See the recorded path hazards.
• Node.js based CLIs depend on their runtime and launcher installation; portable layouts may resolve differently. See the CLI observations and adapter reference.
• Windows console or pipe encoding can affect non-ASCII output. See the recorded encoding failure and adapter reference.

These are environment warnings; historical observations do not establish a current failure on every installation.

Validation

python -m pytest -q
pyright
python tools/command_inventory.py --check
python tools/traceability.py --upto 9

# Real provider canaries spend quota: local only, never in CI (refuses when CI is set).
python -m tools.live_gate --yes

Real providers are opt-in: set PEERHUB_LIVE=1 and select live, slow, e2e or canary under tests/communication/live; live fixtures refuse CI. -m live selects exactly the six M1 live-tier tests; slow/e2e release cases use their own markers. The gate partitions those stages. Optional canary tests are outside the release catalog and measure usage, native resume recall, writable sentinel creation and cancellation using standard profiles. Use python -m tools.live_gate --yes --only canary --peer cx for lower-cost measurements; these results are not release evidence. See the local live gate guidance for call budgets and skip behavior. Soak is separately opt-in with PEERHUB_SOAK=1. Local checks do not promote a milestone or authorize a release; candidate-matched CI, live and package evidence still apply.

Historical evidence is retained separately: the 2026-10-04 archived snapshot has VERIFIED-LOCAL records, and the recorded CI head has VERIFIED-CI records. Those records preserve their original paths and apply only to the recorded snapshot/head, not this changed worktree.