pairwave · living architecture

The whole system — packaged → installed → live — with what's tested and what isn't. Click any node.
4packages
32source modules
104automated tests ✓
0central servers
E2Eencrypted
Tested (automated) Live-verified Built, not e2e-tested here Needs you Planned v2
② Live Architecture
① Setup & Packaging
③ Security & Safety
④ Test & Status Matrix
Person A · their machine (trusted) Person B · their machine (trusted) The shared room · ciphertext only · no one can read it MCP · stdio localhost E2E · WSS MCP · stdio localhost
Claude Code · A
the human's AI · gets 24 pair_* tools
/pairwave skillapproves MCP
Companion · A (brain)
trusted · holds the key · no project/shell access
engineruntimefloorguardbrainpermissionsledgerhandoffpersist+6 — click
Dashboard · A
127.0.0.1 · decrypts locally
approvalsbrain railSAS
Relay
UNTRUSTED · ciphertext only
fan-out by room2-peer capTTL store
Claude Code · B
mirror of A · independent session
/pairwave skillapproves MCP
Companion · B (brain)
identical to A · own key & identity
same 16 modulesown .pairwave/click to explore
Dashboard · B
127.0.0.1 · their own port
approvalsbrain railSAS

Click any node to inspect it

The two machines are mirrors. The relay between them is dumb and untrusted — it only moves sealed bytes.

Everything left of the relay is Person A's trusted machine; everything right is Person B's. The only thing that crosses the internet is end-to-end-encrypted, signed, tamper-evident ciphertext.

One prompt → fully set up

Person A runs one line (or pastes it to Claude Code: "run this")
1
One-line installer — checks Node 20+ & git. live-verified
2
Clones the app to ~/.pairwave/app (outside your project), builds it, self-heals a force-pushed update. live-verified
3
Installs global pairwave + link fallback for locked-down machines. live-verified
4
Wires THIS project: .pairwave/config.json, the MCP server in .mcp.json, the /pairwave skill, gitignore. tested
5
Prints a ready-to-send block for the friend (invite embedded) + tells you to type /pairwave. tested

Per-person vs shared

Each side self-contained; only the encrypted room is shared.
Per person (local)Shared (the room)
Node 20+ & gitroomId + passphrase (invite)
the built app cloneone relay (either side, or Render)
identity keypairthe encrypted message DAG
project .pairwave/ (log, outbox, quarantine, handoff)the working agreement (charter)
companion + localhost dashboardthe shared brain (memory)
Claude Code + MCP approvalSAS verification of each other

Needs installing

  • ● Node.js 20+ — required, checked
  • ● git — required, checked
  • ○ cloudflared — only for remote `relay --public`
  • ✓ zod · libsodium · ws · MCP SDK — installed automatically

The relay — 3 ways, your choice

A
Same wifi → pairwave relay. tested
B
Remote, no account → pairwave relay --public (Cloudflare tunnel). live-verified e2e
C
Remote, no install → Deploy-to-Render button. config verified

Can anyone break into a room?

AttackWhy it fails
Find the relayNeeds the 192-bit invite passphrase (relay never has it)
EavesdropXChaCha20-Poly1305; roomId bound as AEAD AD
Forge / tamperEd25519 sigs + hash-DAG — fails on arrival & reload
Impersonate at inviteSAS six-word check, out-of-band
Third joinerRelay caps at 2 peers; no passphrase = ciphertext only
Hostile peer actionDanger guard + dual gates + zero companion disk/shell access

Safety barriers (every inbound action)

!
Danger guard — deletions, terraform, force-push, DB wipes, protected paths → forced high-risk, never auto-approved. tested
1
Gate 1 — Pairwave popup: accept the request? tested
2
Gate 2 — Claude Code's own prompt when your AI applies it. by design
⊘
Secret scanner blocks keys leaving; keys never travel the channel. tested

Stays alive & recoverable

  • ● Durable signed log + crash-safe outbox (redelivers after a drop) stress-tested
  • ● Reconnect with replay; floor auto-recovers; presence tracked
  • ● Handoff file on every shutdown → resume with full memory tested
  • ● Corrupt state degrades to defaults, never crashes
  • ● AI self-repair runbook + fork→PR contribute-back flow

Honest limits (v1)

  • done Forward secrecy — content rides an ephemeral ECDH key; a later passphrase leak can't read recorded traffic. (per-message ratchet is the deeper v2)
  • v2 >2-person rooms — model is deliberately 2-party
  • Relay sees metadata (sizes, timing, presence) — never content
  • A compromised endpoint or a lying trusted peer is out of scope

Test & status matrix — 104 automated + live proofs

AreaCoverageStatus
Crypto core (protocol)17: seal/open, tamper/forge/replay fail-closed, SAS, hash-DAG, forward-secrecy ECDH key agreementtested
Relay (untrusted bus)6: E2E via real WS, ciphertext-only store, replay, presence, 2-peer captested
Companion brain76: floor/hops, gates, guard, secrets, quarantine, ledger, brain, git no-overlap, forward-secrecy e2e, engine+runtime e2e, stresstested
Git coordination7: path-ownership ledger, overlap detection, earlier-wins, proactive refusal, releasetested
CLI / install wiring5: invite codec, project wiring, no-clobber, idempotencytested
Stress (real sockets)floods (zero loss, same order), relay outage+recovery, 300KB, fork convergencetested
Install from GitHub URLclean run, exit 0; self-heal of force-pushed clonelive-verified
Internet round-trip2 companions, real relay, real internet: peers + SAS + decryptlive-verified
Dashboard UIbrowser: chips, popup, approve flow, brain rail, human chat onto wirelive-verified
This mapbrowser: renders, tabs switch, every node opens its detail, zero console errorslive-verified
Remote tunnel (`--public`)cloudflared tunnel opened, healthz reachable, 2 companions connected + exchanged E2E through itlive-verified
Live two-human sessionyou + Joao in real Claude Code — the final proofneeds you
npm publishprepped (PUBLISHING.md); needs your npm loginneeds you
Forward secrecyephemeral X25519 ECDH content key; relay ciphertext unreadable with only the passphrase — proven e2etested
Per-message ratchet / N-partydeeper FS (rolling keys) + >2 people — real design + review requiredplanned v2
Pairwave · Free for noncommercial use (PolyForm NC 1.0) · github.com/goofypluto999/pairwave · open docs/architecture.html in any browser