peer-relay

A deliberately dumb message relay that lets two separate Claude Code instances — run by two different developers, on two different machines — exchange direct questions and answers without sharing or merging their context.

It is an MCP server that behaves like a tiny mailbox. The only thing that ever crosses between the two instances is the literal text of a question and the literal text of an answer (plus a couple of small, self-written fields). Nothing else.

Relay, not knowledge base. peer-relay is intentionally dumb. No context syncing. No state mirroring. No background memory. No "let me read your repo for you."

Why

Two developers are working on related things. Dev A's Claude Code needs something only Dev B (or Dev B's codebase) knows — "why does the session token expire after 15 minutes?". Today you'd Slack the human, who asks their Claude, who answers, who pastes it back.

peer-relay lets Dev A's Claude ask Dev B's Claude directly and asynchronously, while keeping the two working contexts completely separate. A's repo, files, and conversation never touch B's, and vice-versa. Only the question and the answer move.

Related MCP server: Agent HQ

The trust model (what is and isn't stored)

This is the whole point, so it's worth being precise.

The relay stores ONLY these fields:

It never stores, inspects, or fuses:

• file contents or file trees

• repository state, diffs, or branches

• conversation history or working memory

• anything auto-collected from either developer's environment

Why you can believe that

The guarantee is structural, not a pinky-promise in prose:

• The storage contract in src/storage/types.ts names every field that can exist. There is no generic metadata, payload, context, or blob field anywhere.

• The SQLite schema in src/storage/sqlite.ts has exactly those columns and nothing else — no JSON catch-all column, no key/value side table. The only multi-value field, sources, is constrained to a flat array of strings.

• context_hint and sources are written by the humans-in-the-loop Claudes themselves, in their own words. The server does not and cannot auto-collect them.

To make the relay store anything richer, you would have to change that interface and that schema — a visible, reviewable diff. That's the design.

Grounding answers (and not propagating nonsense)

The biggest risk in letting one Claude answer another is confident-but-unfounded claims crossing the wire and being treated as fact. peer-relay mitigates this at the prompt layer:

• answer_question strongly prompts the answering Claude to ground its answer in concrete sources — file paths, file:line refs, commit hashes, PR numbers, decision docs.

• It instructs the answerer to say so explicitly when it is unsure or answering from memory rather than a verifiable source.

• check_answers reminds the asker to treat answers as claims from another developer, to prefer verifying cited sources, and to weight "from memory" answers accordingly.

Sources are encouraged but not required — sometimes the honest answer is "from memory, not verified."

MCP tools

The flow is poll-based and asynchronous: A ask_peer → B check_questions → B answer_question → A check_answers.

Quick start (Docker)

The whole thing is one container plus a shared secret. One of you hosts it; both of you connect.

1. Host the relay

git clone https://github.com/jmgomezl/peer-relay.git
cd peer-relay

# pick a shared secret — BOTH devs will use this exact value
echo "PEER_RELAY_ROOM_TOKEN=$(openssl rand -hex 32)" > .env

docker compose up -d

That's it. The relay is now on http://localhost:8787/mcp, with a persistent volume for the mailbox and a built-in health check. cat .env to get the token to share with the other dev.

No Docker? Use Node ≥ 20 instead: npm install && npm run build && PEER_RELAY_ROOM_TOKEN=... PEER_RELAY_HOST=0.0.0.0 npm start.

2. Make it reachable by the other developer

The other dev's Claude Code has to be able to hit that URL. Pick whichever matches your situation:

⚠️ Security: the server speaks plain HTTP and the room token is a bearer secret. Do not send it over the open internet unencrypted — put HTTPS in front (a tunnel does this for you, or use a reverse proxy like Caddy/Traefik). On a trusted LAN/VPN, plain HTTP is fine.

3. Each dev registers it in Claude Code

Both devs point at the same URL and same room token, but send a different x-peer-id. See examples/dev-a.mcp.json and examples/dev-b.mcp.json.

Dev A's .mcp.json (in their project root):

{
  "mcpServers": {
    "peer-relay": {
      "type": "http",
      "url": "https://your-relay-url/mcp",
      "headers": {
        "x-room-token": "the-shared-secret-from-step-1",
        "x-peer-id": "alice"
      }
    }
  }
}

Dev B's is identical except "x-peer-id": "bob". Restart Claude Code (or /mcp to reconnect) and the four peer-relay tools appear.

That's the entire pairing: same room token = same mailbox; distinct peer ids = the two sides.

4. Use it

In Dev A's Claude Code:

Ask my peer why the session token expires after 15 minutes — mention it's about the auth refactor in src/auth/session.ts.

Claude calls ask_peer. Later, in Dev B's Claude Code, "check questions from my peer" surfaces it; B answers with sources; A's "check for answers" retrieves it.

Heads-up — polling, no push. The relay does not notify either side. Each dev has to ask their Claude to "check for questions/answers." That's intentional for v1; a question waits in the mailbox until the peer polls.

Managing the container

docker compose logs -f      # watch it
docker compose down         # stop (mailbox volume is kept)
docker compose down -v      # stop and wipe the mailbox

The mailbox persists in the peer-relay-data volume across restarts. See .env.example for all env vars.

Pairing & auth model

• One shared room token authenticates the room. Present it as x-room-token: <token> or Authorization: Bearer <token>. A wrong/missing token gets 401.

• Peer id (x-peer-id) says which side you are. In a room, a question asked by alice is visible to everyone who is not alice — for a strict 1:1 pair, that's exactly bob.

• That's all the auth there is in v1. No accounts, no OAuth. Keep your room token secret; rotate it by changing it on both sides.

What this is NOT

• ❌ Not a context-sync tool. It does not mirror, merge, or replicate either developer's working context, files, or conversation. The two contexts stay fully separate.

• ❌ Not a knowledge base. It doesn't index, embed, summarize, or "remember" anything for later retrieval. It's a queue of literal Q&A text, nothing more.

• ❌ Not an auto-context collector. It never reads your repo or environment to enrich a question. If the peer needs orientation, the asker writes a context_hint by hand.

• ❌ Not a team router. v1 is strictly one-to-one between two known devs. No fan-out, no channels-of-many.

• ❌ Not an oracle. Answers are claims from another Claude. Grounding via sources is encouraged precisely because answers can be wrong.

Storage layer

Storage sits behind the Storage interface. The default implementation is SQLite (src/storage/sqlite.ts) for zero-setup local dev. To move to Postgres later, implement the same interface — no changes to the tools or transport. The narrow interface is also what keeps the trust model enforceable: there's simply no method to store anything beyond the documented fields.

Development

npm run dev        # watch-mode server (tsx)
npm test           # end-to-end test: A asks, B answers, A reads it back
npm run typecheck  # tsc --noEmit

The e2e test (test/e2e.test.ts) drives a full ask→answer→read cycle through the queue against an in-memory SQLite store, plus room isolation and double-answer rejection.

Roadmap (explicitly out of scope for v1)

• On-chain / HCS audit trail as a separate signing layer (not in v1).

• Team-wide routing beyond 1:1.

• A web UI.

• Auth beyond the shared room token.

License

MIT — see LICENSE.