Documentation · v0.2 · powered by FalkorDB

/.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, live patch sync across every machine on the team, and a FalkorDB memory graph that tells every agent who is doing what, and why.

Everything on this page runs on your own hardware. There is no hosted backend and no account server — one person on the team runs relay serve and that machine is the server. The memory graph is optional: one FalkorDB container on the host (or a hosted FalkorDB), and teammates read it through the room.

- 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 the Mission Control board. It is published on npm as relaybrain, with Mission Control prebuilt inside the package.

Requirements

Install the CLI

$ npm install -g relaybrain   # puts `relay` (and `relaybrain`) on your PATH

Or from source, if you want to hack on relay itself:

$ 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 — Version control 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 init [path]        Wire hooks, MCP, and relay-os instructions (default: cwd)
  relay serve              Start the API and Mission Control on 127.0.0.1:3001 (prebuilt UI, fast start)
  relay serve --no-ui      Start API + coordinator only
  relay serve --dev        Run Mission Control with next dev on :3002 (hot reload, slow first load)
  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 (run it on the machine that sees nothing)
  relay graph <cmd>        Memory graph (FalkorDB): up | enable [url] | disable | status | stats | rebuild [id|all]

Get started

Quickstart · Host

The host is the machine that owns the lock table — and, with the memory graph on, the room's graph. Exactly one person on the team is the host; everyone else is a guest. A handful of commands and you are live.

$ relay login

$ relay clone <repo-url> [dir]

$ relay add /path/to/repo

$ relay graph up             # FalkorDB in Docker on localhost:6379
$ relay graph enable         # save the URL and switch relay onto the graph

$ relay serve                # API + Mission Control → http://localhost:3001
$ relay serve --no-ui        # API + coordinator only, no board
$ relay serve --dev          # Mission Control with hot reload on :3002

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.

$ npm install -g relaybrain        # the relay CLI
$ 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.

Guests don't need FalkorDB or Docker. Their Memory Graph tab and their agents' graph tools are answered by the host's graph through the room.

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

Memory graph

The memory graph

A lock stops two agents writing one file. It doesn't tell the blocked agent what the other one is doing, what was decided, or which prompt made the code look this way. With the memory graph on, /.relay writes every agent session, prompt, edit, block and decision — across every agent and every teammate — into one FalkorDB graph, and hands it back to agents before and during their work.

Context at the moment of conflict

File `src/auth.ts` is locked by Claude Code:DESK:52b2…. Pick a different task.
They're working on: "switch the login flow to JWT tokens" (2 min ago).

The holder's intent comes from an in-process cache filled on ingest (and refilled from the graph after a restart), so the lock path never waits on the database. If FalkorDB is down, locks keep working exactly as before.

What's in the graph

(Person)-[:RUNS]->(Agent)-[:RAN]->(Session)-[:HAS_TURN]->(Turn)
                                    └─[:MADE]->(Edit)-[:MODIFIED]->(File)
(Edit)-[:PROMPTED_BY {via}]->(Turn {role:user})        the inferred "why"
(Edit)-[:EXPLAINED_BY]->(Turn {role:assistant})
(Session)-[:HELD {count}]->(File)                      lock claims
(Contention)-[:ON]->(File), -[:HELD_BY]->(Session), -[:WANTED_BY]->(Session)
(Overlap)-[:ON]->(File), -[:BETWEEN]->(Edit)×2         two agents, same file, minutes apart
(Decision|Task)-[:ABOUT]->(File), -[:DURING]->(Session)
(File)-[:CO_EDITED {weight}]->(File)                   → PageRank, communities

Memory graph

Set it up

Only the host runs a graph. The same commands work on Windows, macOS and Linux, with no environment variables.

$ relay graph up

FalkorDB is up on falkor://127.0.0.1:6379 (browser UI: http://localhost:3010).
Next: relay graph enable

$ relay graph enable                                      # local Docker
$ relay graph enable falkor://default:PASSWORD@HOST:PORT  # hosted FalkorDB
$ relay graph enable falkors://default:PASSWORD@HOST:PORT # hosted, TLS

Connected to falkor://127.0.0.1:6379 (2 graph(s)).
relay serve: memory graph is on.
Saved to ~/.relay/falkor.json.

$ relay init          # in each repo you set up before the graph, then restart your agents

$ relay serve
$ relay graph status

config: falkor://127.0.0.1:6379 (from file)
file:   ~/.relay/falkor.json
relay:  graph running, connected
        proj_45dbc0415beb: last ingest 18/10/2026, 3:44:08 pm
db:     reachable, 3 graph(s)

$ relay graph rebuild          # every project
$ relay graph rebuild <id>     # one project (ids: curl http://127.0.0.1:3001/api/projects)

Memory graph

A new PC

Pick the row that matches what this machine will be. Your own agents' chats always load from this machine's transcripts, graph or not.

$ npm install -g relaybrain
$ relay login
$ relay clone <repo-url>
$ relay graph up && relay graph enable    # or: relay graph enable falkor://…cloud URL…
$ relay serve                             # → http://localhost:3001

Memory graph

relay graph commands

Every subcommand accepts --help.

$ relay graph up

$ relay graph enable
$ relay graph enable falkor://default:s3cret@r-6jissuruar.instance-xyz.falkordb.cloud:6379

$ relay graph status

$ relay graph stats

relayBrain (proj_relay) -> graph relay_proj_relay
  nodes:      Edit:317  Turn:271  File:77  Agent:1  Person:1  Meta:1  Session:1
  edges:      PROMPTED_BY:317  BY:317  EXPLAINED_BY:317  MODIFIED:317  MADE:317  HAS_TURN:271  TOUCHED:77
  turns:      271/271 with text (2026-10-16 .. 2026-10-18)
  schema:     v1 (ingest v6), migrations: 001_meta_versions_v6

$ relay graph rebuild
$ relay graph rebuild proj_45dbc0415beb

$ relay graph seed               # sandbox for your first project
$ relay graph seed proj_45dbc0   # sandbox for a specific project

$ relay graph disable

Memory graph

Queries & agent tools

Agents reach the graph through two MCP tools. Both are read-only and work for room guests too.

Named queries

The same queries are on the HTTP API, so you can script them:

$ curl -s http://127.0.0.1:3001/api/graph/queries
$ curl -s "http://127.0.0.1:3001/api/graph/query/file_story?path=src/auth.ts"
$ curl -s "http://127.0.0.1:3001/api/graph/query/search_memory?q=jwt"

Or ask in plain words inside any agent: "call relay_session_brief for src/auth.ts", or "use relay_graph_query hotspots". In Mission Control, the Memory Graph tab lets you click a file to see its agents, sessions, prompts, blocks and decisions, open the Cypher behind any panel, and search every conversation.

Memory graph

Graph troubleshooting

More detail — persistence, recovery after a hard shutdown, the full design — is in docs/MEMORY-GRAPH.md ↗.

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 a tunnel (Cloudflare, ngrok or Tailscale) straight to that laptop. With the memory graph on, the host's FalkorDB is the room's brain: guests' graph queries are forwarded to it.

  Cursor ──┐  pre-tool hook: claim
  Claude ──┤  post-tool hook: release      ┌──────────────┐
  Copilot ─┼──► lock table ◄── dep graph ──│ relay serve  │──► Mission Control
  Codex ───┤        ▲                      │  (your host) │          ▲
  Antigravity ┘     │                      └──────┬───────┘          │
                    │   cloudflare / ngrok      │                  │
              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 on :3001
$ relay serve --no-ui            # API + coordinator only
$ relay serve --dev              # Mission Control via next dev on :3002
$ 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
$ relay serve                # API + Mission Control on :4001

Where state lives

Coordination state is files on your own disk. The memory graph, when on, lives in FalkorDB.

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 + Mission Control on :4001
$ RELAY_UI_PORT=4002 relay serve --dev       # if :3002 is taken in dev mode

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.

Do I need FalkorDB?

No. Locking, patch sync and Mission Control work without it. The memory graph is an add-on, and only the host runs it — room guests read the host's graph. No Docker? Use a hosted FalkorDB. See A new PC.

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.