peerbridge-mcp

Start in 30 seconds

1. Download PeerBridgeControlRoom-0.1.0a6-windows-x64-portable.zip from the Alpha 6 release.
2. Compare the ZIP's SHA-256 with SHA256SUMS.txt on the release page.
3. Extract the complete ZIP to a writable folder and double-click Launch PeerBridge.cmd.

The portable build does not install a service, modify an existing Python environment, or include provider credentials. Local workspace data stays under %LOCALAPPDATA%\PeerBridge\workspace. Prefer source installation? Continue to Install from source.

PeerBridge is more than a collection of chat tabs. Its provider-native adapter layer keeps Codex JSON-RPC, Claude Code stream-json, Grok/Kimi ACP, provider APIs, and local runtimes as separate capability contracts. Every Agent is bound to a stable identity, selected model, permission policy, room context, task, and evidence trail.

Use it for parallel implementation and review, bounded technical debate, task ownership, approved shared memory, mutual scoring, cross-agent audits, and human-controlled release work. PeerBridge runs locally on SQLite, keeps provider credentials out of chat and project history, and preserves a SHA-linked record of messages, decisions, evidence, scores, permissions, and handoffs.

Human or Agent messages can wake the room, collaboration stops on consensus, blockers, stagnation, or explicit limits, and the operator can intervene at any time.

Technical differentiators

flowchart LR
    A["Provider-native adapters"] --> C["Per-Agent capability union"]
    C --> P["Capability-aware approval broker"]
    P --> W["Governed worktree and writer lease"]
    W --> R["Parallel review and bounded collaboration"]
    R --> E["SHA-linked evidence and Proof Bundle"]
    H["Human operator"] --> P
    H --> R

Run the provider-free maintainer showcase with one command:

python examples\demo_workflow.py --workspace demo-workspace --scope demo

Its public receipt proves that an overlapping second writer was rejected, two independent reviewers satisfied quorum, completion rehashed the synthetic artifact, and the audit chain verified with zero writes. It contains no provider credential or lease capability. See the claim-to-test evidence map.

Status: alpha. The coordination and audit core is tested, but the public API and database schema may change before 1.0.

Operational continuity and commercialization are explicit design boundaries. See memory and long-running operations and the open-core boundary. Tailscale Serve remains the private browser transport; Tailcat CLI connectivity is visible and enabled by default but remains independently allow-listed. Roadmap entries are not capability claims.

Why

Running two coding agents against one repository creates predictable failure modes:

• both agents edit the same files;
• one agent assumes a peer is online when it is not;
• chat messages are lost or acknowledged globally instead of per consumer;
• a review approves stale files rather than the files that were actually tested;
• the human cannot see who owns a task or why it was marked complete.

PeerBridge addresses those coordination failures without making either agent the boss. One task has one writer lease, peers can review each other, and a human can intervene.

Architecture

flowchart LR
    H["Human operator"] --> M["Local control room"]
    C["Codex / Claude Code"] --> S1["PeerBridge stdio process"]
    A["Grok / Kimi / DeepSeek / Gemini / local Agents"] --> S2["PeerBridge stdio process"]
    M --> S3["PeerBridge stdio process"]
    R["Private mobile UI"] -->|"Tailnet HTTPS"| T["Tailscale Serve"]
    T -->|"loopback only"| S4["Human MCP message gateway"]
    S1 --> DB[("Shared SQLite store")]
    S2 --> DB
    S3 --> DB
    S4 --> DB
    DB --> L["SHA-linked audit events"]
    DB --> W["Mailbox, leases, reviews, proofs"]

Each MCP client launches its own stdio server process with a distinct --agent-id. Those processes coordinate through one project-local .peerbridge/peerbridge.sqlite3 database. SQLite WAL mode and BEGIN IMMEDIATE transactions serialize state changes.

Local desktop surfaces

PeerBridge is one local desktop product, not a hosted web service. Both desktop surfaces use the same local Python, SQLite, and MCP core:

• Modern Workbench renders HTML/CSS inside the packaged native WebView2 window. Its loopback HTTP server accepts only the current process capability token and is never a public website.
• Pixel Control Room is the original Tk desktop surface.

A fresh workspace shows a local two-preview chooser before the Control Room opens. The selection is stored in .peerbridge/ui-preferences.json; later launches open that surface directly until the operator changes Appearance and restarts.

Features

• In-app Agent Cockpit with Grid, Focus, and Timeline views plus stable per-session Terminal, Activity, Answer, and Evidence tabs.
• Primary Agent controls show the real model/route, governed permission tier, and evidence- derived offline, online, working, or waiting state before a session starts. Observable events distinguish commands, reads, edits, web searches, waits, completion, and failure.
• Persistent official runtime profiles for Codex app-server, Claude Code stream-json, and installed Kimi Code or Grok through ACPX. Observe and Review remain read-only; Edit and Full development require an active human-approved governed Git worktree. Edit keeps normal networking while using each official client's standard policy: Codex workspace-write with escalation denied, Claude accept-edits without pre-authorized shell access, and ACPX read/search/edit/fetch grants with execute/delete/move denied. Full access records one session-scoped operator authorization and enables the provider's complete tool set only until that managed session stops.
• Explicit Agent-history import: Codex uses official app-server thread list/read, Grok uses grok sessions list, and Claude/Kimi use their documented local session records. The UI lists bounded metadata first, selects nothing by default, and reads only conversations the operator checks; JSON/JSONL file import remains available for every provider.
• Observable output only: PeerBridge never labels hidden chain-of-thought or uncaptured external terminal history as visible.
• A bounded read-only Git worktree viewer shows per-file additions/deletions and a colored unified diff while excluding credential/runtime pathspecs and redacting secrets and machine-private absolute paths.
• Implement + Review, Investigate + Debate, Re