# ๐ bridge-harness
### Real-time messaging between AI coding agents โ **no matter the provider.**
Give **Claude Code** and **Pi** one bridge and they talk to each other *live* โ
asking, answering, going back and forth on their own. No files. No copy-paste.
No polling. Just a conversation between agents.
[](https://www.npmjs.com/package/@cocodrino/bridge-harness)
[](https://www.npmjs.com/package/@cocodrino/bridge-harness-pi)
[](https://nats.io)
[](LICENSE)
---
## ๐ฌ See it in action
These aren't chat windows โ they're **real coding agents** wiring a fix together
in real time. You start the thread; they carry it:
```text
โญโ ๐ต Claude Code โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ Pi, review the auth module while I refactor the payments โ
โ flow โ ping me with anything you find. โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โ
โก delivered over NATS ยท Pi wakes up on its own
โผ
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ ๐ฃ Pi Agent โโฎ
โ On it. โฆ Found 2 issues in middleware.ts (lines 42 & 88). โ
โ Missing token expiry check + a timing-unsafe compare. Patch? โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โ
โก asyncRewake fires ยท Claude answers instantly
โผ
โญโ ๐ต Claude Code โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ Yes please. Send the patch, I'll wire it in and run tests. โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โ
โผ
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ ๐ฃ Pi Agent โโฎ
โ Sent. ๐ฏ Tests green on my side too. Nice teamwork. โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
no files ยท no copy-paste ยท no polling ยท pure real-time
```
Most multi-agent setups make **you** the messenger: copy output from one agent,
paste it into another, repeat. `bridge-harness` deletes that job. The agents
address each other directly over a local NATS server and **react automatically**.
---
## โจ Why it's different
- โก **Real-time.** [NATS](https://nats.io) pub/sub โ sub-millisecond, in-process. No polling, no webhooks.
- ๐ง **Reactive, both ways.** Claude sends โ Pi wakes and processes (`triggerTurn`). Pi replies โ Claude wakes (asyncRewake). A true loop, not a one-shot.
- ๐ **Provider-agnostic.** The transport doesn't care who's behind the agent โ different vendors, same conversation.
- ๐๏ธ **No intermediate files.** No scratch file, no `/tmp` handoff, no relay script. Agents talk directly.
- ๐ฏ **Reach anyone by identity.** DM `agent:` and it lands across any project or git worktree โ no shared room or matching config.
- ๐ **Global discovery.** `list_agents` shows everyone online (and their project); late joiners still see who's already there.
- ๐ **Isolated rooms.** Rooms are project-scoped, so each worktree keeps its own lobby without cross-talk.
- ๐ **Local or remote.** Same machine, LAN, or cloud NATS โ same conversation, anywhere.
---
## ๐ The reactive loop
```mermaid
sequenceDiagram
participant C as ๐ต Claude Code
participant N as โก NATS bridge
participant P as ๐ฃ Pi Agent
C->>N: send "review the auth module"
N-->>P: deliver โ Pi wakes automatically
P->>N: send "found 2 issues, patch?"
N-->>C: deliver โ asyncRewake fires
C->>N: send "yes, wiring it in"
N-->>P: deliver
Note over C,P: no files ยท no copy-paste ยท pure real-time
```
---
## ๐๏ธ Architecture
```text
๐ต Claude Code ๐ฃ Pi Agent
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ MCP server โ โ Pi extension โ
โ + rewake hook โโโโโโโโโโโโโโโโโโโโโโโโโโโบโ (native API) โ
โโโโโโโโโโฌโโโโโโโโโ NATS subjects โโโโโโโโโโฌโโโโโโโโโ
โ bridge.{project}.* โ
โโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโผโโโโโโโโโโโ
โ NATS Server โ
โ localhost:4222 โ
โ (auto-start) โ
โโโโโโโโโโโโโโโโโโโโโโโ
```
**Claude Code side** โ an MCP server exposing the bridge as tools:
`send` ยท `read` ยท `list_agents` ยท `join_room` ยท `whoami` ยท `who_is_in` ยท `use_bridge`.
A background **asyncRewake hook** wakes Claude the instant a message arrives โ
zero user intervention.
**Pi side** โ a TypeScript extension on Pi's native `ExtensionAPI` that delivers
incoming messages via `pi.sendMessage({ triggerTurn: true })`, so Pi **reacts on
its own**, and exposes the `agent_bridge` tool to send proactively.
---
## ๐ Quick start
**Prerequisites:** Node 18+, `nats-server` in PATH (`brew install nats-server`), Pi with extension support.
**Claude Code โ one command:**
```bash
npm install -g @cocodrino/bridge-harness
bridge-harness-setup # registers the MCP server + reactive hook
```
Restart Claude Code. Tools `send`, `read`, `list_agents`, `join_room`, `whoami`,
`who_is_in`, and `use_bridge` become available.
**Pi โ one command:**
```bash
pi install npm:@cocodrino/bridge-harness-pi
```
Both running? The bridge is live. **Tell one agent to message the other.**
---
## ๐ฎ Usage
```text
# Claude Code โ Pi
send to: "agent:pi" message: "Review the auth module and report back."
โ Pi wakes up automatically and starts working.
# Pi โ Claude Code
agent_bridge action: "send" to: "agent:claude-code"
message: "Auth review done. Found 2 issues."
โ Claude wakes up automatically (asyncRewake) and reads it.
# Who's online?
list_agents โ [{ "agentId": "pi-88191", "displayName": "Pi Agent @ pi-harness-fix" }]
# Hop both agents onto a shared channel, wherever they launched
use_bridge bridge: "debugging-session"
```
**Debug CLI:**
```bash
node dist/cli/index.js send --to pi "hello from terminal"
node dist/cli/index.js read --watch
node dist/cli/index.js agents
```
---
## ๐ก Subjects & routing model
```text
bridge.dm.{agent} # direct messages โ GLOBAL (by identity)
bridge.registry # identity + discovery (join / leave / who-there / here) โ GLOBAL
bridge.presence # heartbeats / online status โ GLOBAL
bridge.{project}.room.{room} # room messages โ scoped to a project
```
**The key model:** DMs and discovery are **global by identity** โ you can `send` to
`agent:` and it reaches that agent across **any** project or git worktree, and
`list_agents` shows everyone (with their `project`). **Rooms are project-scoped**, so
each worktree keeps an isolated lobby; a room only reaches agents in the same project.
To reach an agent in another worktree, **DM it by `agentId`** โ no room-joining or
`use_bridge` needed. Use `use_bridge` only to *share a room* with another project.
**DM durability (JetStream).** `bridge.dm.*` is captured by a JetStream stream
(30-min / 100-per-recipient retention), so the rewake hook wakes Claude for **every**
DM โ including replies that arrive during its restart โ through a durable consumer that
gets redelivered anything it missed, and offline recipients catch up on reconnect within
the window. Rooms stay ephemeral core-NATS. The bundled `nats-server` auto-start enables
JetStream (`-js`); a remote server must run with it too.
`{project}` defaults to `BRIDGE_PROJECT`, or the **git worktree name** (`basename`
of `git rev-parse --show-toplevel`), or the cwd name outside a repo. Each worktree
has its own isolated rooms โ override with `BRIDGE_PROJECT` to share them.
---
## ๐ Remote agents
Agents don't have to share a machine. `nats-server` listens on `0.0.0.0:4222`:
```bash
# Same LAN โ point both at Machine A's NATS
BRIDGE_NATS_URL=nats://192.168.1.10:4222 bridge-harness-mcp
BRIDGE_NATS_URL=nats://192.168.1.10:4222 pi
# Over the internet โ cloud NATS (fly.io, Railway, any VPS)
BRIDGE_NATS_URL=nats://your-server.fly.dev:4222 bridge-harness-mcp
```
For internet-facing servers, enable [NATS auth + TLS](https://docs.nats.io/running-a-nats-service/configuration/securing_nats).
Same NATS URL = same bridge: DMs and discovery work across everyone connected; rooms stay grouped by project.
---
## โ๏ธ Environment variables
| Variable | Default | Description |
|---|---|---|
| `BRIDGE_PROJECT` | git worktree name (falls back to `basename(cwd())`) | Scopes your **rooms** (isolated per worktree). DMs and discovery are global and ignore this. |
| `BRIDGE_NATS_URL` | `nats://localhost:4222` | NATS server URL โ change for remote agents |
| `BRIDGE_AGENT_ID` | `{base}-{pid}` | Pin a stable agent ID across restarts (how others DM you) |
| `BRIDGE_DISPLAY_NAME` | agent base name (cmux-aware) | Human-readable name shown in `list_agents` |
---
## ๐ Project structure
```text
bridge-harness/
โโโ src/
โ โโโ shared/ # NATS subjects, config, identity
โ โโโ nats-manager/ # auto-start, health check, cleanup
โ โโโ mcp-server/ # MCP server for Claude Code
โ โโโ cli/ # debug CLI
โโโ packages/
โ โโโ bridge-harness-pi/
โ โโโ src/index.ts # Pi extension (TypeScript, ships as source)
โโโ hooks/
โ โโโ bridge-rewake.js # asyncRewake hook for Claude Code reactivity
โโโ tests/ # unit tests (vitest, no NATS required)
```
---
## ๐งช Tests
```bash
npm test
```
Unit tests cover the NATS manager, MCP tools, Pi extension behavior, and the
rewake hook โ all without a live NATS server.
---
**Give two agents one bridge, and watch them figure it out together.**
MIT ยฉ cocodrino