relayBrain

The problem

Eighteen months ago you had one coding assistant. Today you probably have three running at once — Claude in one terminal, Cursor in another, Copilot in the editor. They all write to the same files, and not one of them knows the others exist.

Now put four people on that repo. That's twelve agents, editing the same code, blind to each other. You find out at the merge. Or you don't find out at all.

Git solved this for humans — but Git assumes people committing at human speed, minutes apart, one branch each. Agents write at machine speed, in parallel, in the same directory. There is no layer for that.

The fix

- 12 agents · 12 blind writers · conflicts discovered at merge
+ 12 agents · 1 lock table · conflicts prevented at the edit

Relay sits under every agent as a coordination layer. Pre-tool hooks claim a lock before an agent writes; post-tool hooks release it. If one agent is modifying a component, another cannot silently overwrite those changes.

One host, no backend. One person runs relay serve — that machine is the server. Everyone else connects over an ngrok tunnel, straight to that laptop. Nothing lives on infrastructure you do not own.

The four pillars

Quick start

Host — the machine everyone else connects to:

relay login              # GitHub identity (uses the gh CLI)
relay clone <repo-url>   # clone + register workspace + install agent hooks
relay serve              # API → 127.0.0.1:3001 · Mission Control → :3002

Then open Mission Control → Team → Share to mint the ngrok invite link.

Teammate:

relay serve              # their own local relay
# join with the host's invite link on the Team tab
relay pull               # take the host's current working state

Now start agents as usual. Hooks claim and release locks automatically — nobody has to remember a command.

How it works

  Cursor ──┐  pre-tool hook: claim
  Claude ──┤  post-tool hook: release      ┌──────────────┐
  Copilot ─┼──► lock table ◄── dep graph ──│ relay serve  │──► Mission Control
  Codex ───┤        ▲                      │  (your host) │          ▲
  Antigravity ┘     │                      └──────┬───────┘          │
                    │       ngrok tunnel          │                  │
              teammate's relay ◄──── patches ─────┴──────────────────┘

Locks and the board are separate subsystems — hooks arbitrate straight against the host, while the board is fed by a mirror. relay doctor walks that chain and tells you which link is broken.

Commands

Mission Control

Started by relay serve — runs on your own machine, no hosted account.

Collisions prevented counter (persisted to ~/.relay/data/projects/<id>/collisions.json and mirrored to <repo>/.relay/collisions.json).

MCP — shared room context

Any MCP client can read the room's context, even on a machine with no relay installed:

relay mcp-url    # prints a ready-to-paste mcpServers block

Coordination tools (relay_claim_file, relay_release_file, relay_status) run against each member's own local relay. The room endpoint is read-only for anyone off the host machine.

Hooks

relay clone / relay add / relay init install pre-tool (claim), post-tool (release), pre-read, stop hooks, Relay MCP (relay_room_brief for /relay ask), and the relay-os instruction block into every agent surface:

Languages parsed for the dependency graph: TypeScript/JavaScript, Python, Go, Rust, Java, C#, C/C++, PHP, Ruby.

Dependencies

Env vars: RELAY_PORT (3001) · RELAY_UI_PORT (3002) · RELAY_UI_ORIGIN

Documentation

Full documentation lives in docs/.

Roadmap

• Git worktree isolation — every agent in its own workspace off the same repository, free to experiment and test independently, integrated back into main when the work is ready.
• Richer conflict resolution on top of the existing OT / patch layer.