Documentation · v0.1.0

/.relay docs

/.relay is the coordination layer for AI coding agents. Claude Code, Cursor, Copilot, Codex and Antigravity all write to the same files and none of them know the others exist. /.relay gives them one shared lock table, a dependency-aware view of the blast radius, and live patch sync across every machine on the team.

Everything on this page runs on your own hardware. There is no hosted backend, no database, and no account server — one person on the team runs relay serve and that machine is the server.

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

What is in here

Get started

Installation

/.relay is a Node CLI plus a local API and a Next.js board. Everything ships in one repository, so installing means cloning it and linking the CLI onto your PATH.

Requirements

Install the CLI

$ git clone https://github.com/prakrititz/relayBrain
$ cd relayBrain
$ npm install                # deps for the CLI, API and Mission Control
$ npm link                   # puts `relay` on your PATH

Confirm the binary resolves:

$ relay help

Relay — GitHub Desktop for AI agents

  relay login              Sign in with GitHub (uses gh CLI, or device flow if GITHUB_CLIENT_ID is set)
  relay logout             Clear the local session
  relay whoami             Show the signed-in GitHub user
  relay clone <url> [dir]  git clone + register workspace + install agent hooks
  relay add <path>         Attach an existing local repo
  relay serve              Start API on 127.0.0.1:3001 and Mission Control on :3002
  relay serve --no-ui      Start API + coordinator only
  relay push               Send your dirty working-tree files to the shared room
  relay pull               Apply the host's current dirty files onto this clone
  relay status             Health check
  relay mcp-url            Print the MCP config for this room's shared context endpoint
  relay doctor             Why the Coordinator board is empty

Get started

Quickstart · Host

The host is the machine that owns the lock table. Exactly one person on the team is the host; everyone else is a guest. Four commands and you are live.

$ relay login

$ relay clone <repo-url> [dir]

$ relay add /path/to/repo

$ relay serve                # API → 127.0.0.1:3001 · Mission Control → :3002
$ relay serve --no-ui        # API + coordinator only, no board

Get started

Quickstart · Teammate

Guests run their own relay against their own filesystem. They do not share a working tree with the host — they share a lock table and a patch stream.

$ relay login                     # their own GitHub identity
$ relay clone <same-repo-url>     # their own clone
$ relay serve                     # their own local relay
# then: Mission Control → Team → Join, paste the host's invite link
$ relay pull                      # take the host's current working state

From that point on, the two machines see one lock table. A claim on the guest's machine is arbitrated against the host over the tunnel, and the board mirrors the host's locks back down.

Get started

Your first coordinated write

Open your agent as you normally would and ask it to edit a file. Nothing about your workflow changes — the hooks fire underneath.

lock table — 4 held
├── src/auth/session.ts   # @pony   · claude  · write
├── src/api/routes.ts     # @unnath · cursor  · write
├── lib/db/client.ts      # @arjun  · codex   · write
└── ui/Header.tsx         # @pony   · copilot · write
    └── dep-blocked: ui/Nav.tsx, ui/Layout.tsx

Now have a second agent try the same file. Instead of a silent overwrite discovered three hours later at the merge, the write is refused at the edit and the agent is told who holds it.

Confirm the whole chain is healthy at any time:

$ relay doctor

Core concepts

File locking

Every agent write goes through a claim/release cycle against a shared, TTL-based lock table. A pre-tool hook fires before the agent touches a file and claims it. A post-tool hook fires after and releases it. If another agent holds the file, the claim fails and the write never lands.

agent wants to write src/auth/session.ts
        │
        ├─ pre-tool hook ──► POST /api/locks/claim
        │                       ├─ free?          → granted, TTL starts
        │                       ├─ held by other? → REFUSED (+ holder identity)
        │                       └─ dep-affected?  → REFUSED (+ blast radius)
        │
        ├─ the edit runs
        │
        └─ post-tool hook ─► POST /api/locks/release
                                └─ change fans out as a patch to the room

Locks are TTL-based and auto-expire, so a crashed agent or a killed terminal cannot wedge a file permanently. Hooks call the host directly over HTTP — arbitration never depends on the board being up.

Core concepts

Dependency-graph locking

Files do not exist independently. Editing one module can break a dozen importers, so path-exact locking is not enough. /.relay parses imports with tree-sitter and asks the real question: does this change affect a file another agent is working on? — not merely is this exact path locked?

Agents stay parallel wherever the graph says they are independent. The blast radius is what gets serialized.

Languages parsed

Core concepts

Rooms & the host model

A room is one host machine plus the guests connected to it. There is no cloud component: relay serve binds the API to 127.0.0.1:3001, and sharing means opening an ngrok tunnel straight to that laptop.

  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 ─────┴──────────────────┘

Room state is written to room.json and carries the role (host or guest), the tunnel URL, the host project id, and a member token for invite-only rooms.

Core concepts

Patch sync

Your teammate has their own filesystem, their own environment, and their own agents. /.relay does not copy projects around — it propagates patches of the dirty working tree, so both clones converge on the same uncommitted state without anyone committing.

$ relay push     # send your dirty working-tree files to the room
$ relay pull     # apply the host's current dirty files onto this clone

push 3 file(s)
  src/auth/session.ts
  src/api/routes.ts
  lib/db/client.ts

Both commands are thin clients over the local API — if the relay is not running you get offline — run relay serve and a non-zero exit code, which makes them safe to use in scripts.

Reference

CLI reference

Every command /.relay ships. Expand one for usage, output, and the failure modes worth knowing.

Identity

$ relay login

signed in as Krishna V (@pony) via GitHub CLI

$ relay whoami

Krishna V (@pony)
project prj_8f31a2

$ relay logout

Workspaces

$ relay clone https://github.com/acme/api-server
$ relay clone https://github.com/acme/api-server ./api

cloned https://github.com/acme/api-server
workspace /Users/pony/code/api-server
registered api-server (prj_8f31a2)

$ relay add ~/code/api-server

added /Users/pony/code/api-server as api-server

Runtime

$ relay serve                    # API + Mission Control
$ relay serve --no-ui            # API + coordinator only
$ relay serve --port 4001        # move the API off 3001

$ relay status

{
  "ok": true,
  "port": 3001,
  "room": {
    "role": "host",
    "url": "https://a1b2c3.ngrok-free.app",
    "hostProjectId": "prj_8f31a2",
    "hostProjectName": "api-server",
    "hostWorkspacePath": "/Users/pony/code/api-server"
  }
}

Sync

$ relay push

push 2 file(s)
  src/api/routes.ts
  lib/db/client.ts

$ relay pull

pull 3 file(s)
  src/auth/session.ts
  src/api/routes.ts
  ui/Header.tsx

Diagnostics & integration

$ relay doctor
$ relay doctor --port 4001

relay doctor — room + Coordinator board

  ok    local API on http://127.0.0.1:3001
  ok    room joined as guest -> https://a1b2c3.ngrok-free.app
  ok    mirroring host project prj_8f31a2
  ok    host answers through the tunnel
  ok    host reports 4 lock(s) for the shared project

  board would render 4 lock(s):
        3 mirrored from the room, 1 claimed on this machine
        src/auth/session.ts  @pony  write

$ relay mcp-url

$ relay help
$ relay -h
$ relay --help

Cheat sheet

Reference

Agent hooks

relay clone and relay add install four hooks into your project: pre-tool (claim), post-tool (release), pre-read, and stop. They are written into each agent's own config format, so every tool participates without a plugin.

Verifying the install

$ ls -a .claude .cursor .codex .agents .github/hooks

Reference

MCP server

Any MCP client can read the room's shared context — even on a machine with no relay installed. Print the config and paste it into your agent:

$ relay mcp-url

{
  "mcpServers": {
    "relay-room": {
      "type": "http",
      "url": "https://a1b2c3.ngrok-free.app/mcp",
      "headers": {
        "ngrok-skip-browser-warning": "relay",
        "x-relay-room-token": "rmt_9f81…"
      }
    }
  }
}

Tools exposed

If you are a guest and no member token is on file, re-join with the invite link — the host may have made the room invite-only.

Reference

Mission Control

One board for every agent on every machine. Started by relay serve, running on your own hardware, with no hosted account behind it.

Panels

Reference

HTTP API

The CLI is a thin client over a local HTTP API. Anything the CLI does, you can script.

$ curl -s http://127.0.0.1:3001/api/health
$ curl -s http://127.0.0.1:3001/api/locks
$ curl -s -X POST http://127.0.0.1:3001/api/push -d '{}'

Requests that cross the tunnel to a host carry two headers: ngrok-skip-browser-warning: relay and, in invite-only rooms, x-relay-room-token.

Reference

Configuration

Environment variables

$ export RELAY_PORT=4001
$ export RELAY_UI_PORT=4002
$ export RELAY_UI_ORIGIN=http://localhost:4002
$ relay serve

Where state lives

There is no database. Everything is files on your own disk.

Bundled dependencies

Operations

Troubleshooting

Start here, always:

$ relay doctor    # run it on the machine that sees nothing

The board is empty but locking works

Expected, and the single most common report. Hooks claim straight against the host over HTTP; the board is fed by a separate lock mirror. If the mirror is not committing its polls, locks stay correct while the board stays blank.

  BROKE the host holds locks but this machine mirrors none of them.
        Locks still arbitrate correctly (hooks call the host directly); it is only
        the board that is fed by the mirror. Restart `relay serve` here.

Common failures

Port already in use

$ relay serve --port 4001                    # API only
$ RELAY_UI_PORT=4002 relay serve --port 4001  # both, plus set RELAY_UI_ORIGIN

Operations

FAQ

Do I need an account?

No. relay login reads a GitHub identity so locks can be attributed to a person, but there is no /.relay account server, no sign-up, and no hosted state.

Does this replace Git?

No — it sits under it. Git coordinates humans committing minutes apart. /.relay coordinates agents editing the same files right now. You still branch, commit and merge exactly as before.

What happens if the host goes offline?

Guests keep their own local relay and their own clone. Claims that need the host will fail loudly rather than silently succeed, and the board falls back to local locks until the tunnel is back.

My language is not in the dependency-graph list.

File locking still works exactly the same — every write is claimed and released. Only the blast-radius edges are missing, so /.relay will not know that editing your file affects someone else's.

What is next?

• 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.