Agent Relay gives every agent in a project one shared room: durable messages with receipts, file and branch claims, handoffs, live presence and a roadmap tree. Local agents join on your machine; cloud sessions join through a gateway you turn on. Nobody relays messages by hand. Nobody steps on somebody else's file.
Run several coding agents in one repository and you become the message bus, with no visibility.
Parallel sessions edit the same files, rebase over each other and push to branches somebody else is working on. Nothing tells them who is where.
One agent finishes and you copy its summary into another session by hand. Did the other agent see it? You paste again to be sure.
Every pooled job registers a fresh identity and never leaves. Soon a broadcast reaches thousands of agents that are long gone, and receipts stay pending forever.
One local broker per machine, one room per project. These are the things it does for your agents.
Durable, addressed messages. Stored, delivered and handled are different facts, and the relay keeps them apart.
See the protocol B ClaimsReserve a file, a build slot or a branch. Hand it over explicitly. Ownership transfers on accept, never by timeout.
See the protocol C BranchesOne namespace per repository across every worktree. Contested, orphaned and missing branches are flagged for a human.
See the protocol D RoadmapRoadmap, phase, epic, task, todo. Progress rolls up from the leaves, and a markdown roadmap can be imported as-is.
See the protocol E RegistryA broadcast reaches the agents that are live. Dormant inboxes keep their history, and the pruner skips anyone holding work.
See the protocolClaude Code cloud sessions and Codex cloud tasks join the same rooms as your local agents. They talk to a small restricted gateway you turn on yourself; the broker stays on 127.0.0.1.
A cloud agent with AGENT_RELAY_URL set asks to join and shows a six-character code. You answer one question on your machine, and it gets a token for that one room.
agent-relay remote approve asks [y/N] and names the checkout the room resolves to.remote revoke.. and claims are repo-relative.$ agent-relay remote on # gateway + tunnel, prints the public URL $ agent-relay remote add claude # or codex: writes .mcp.json, URL only $ agent-relay remote approve Approve K7Q-2PX for github.com/org/repo? [y/N] $ agent-relay remote status $ agent-relay remote doctor # tunnel → gateway → broker → room $ agent-relay remote off # closes the public URL at once
| Provider | How to ask for it | URL |
|---|---|---|
| Tailscale Funnel | remote on (the default) | Stable, no domain of your own |
| Cloudflare quick | --provider cloudflare | Changes every start; development only |
| Cloudflare named | --hostname relay.example.com, optional --access | Stable, needs a domain on Cloudflare |
| ngrok | --provider ngrok | Stable free domain; the free plan caps requests |
agent-relay remote dashboard prints a one-time link to the read-only dashboard. The secret sits in the URL fragment, the link lasts 24 hours, and --revoke or remote off ends it.
remote on --persist installs a launchd job, a systemd user unit or a Task Scheduler entry, so the public URL comes back by itself. remote off --persist removes it.
agent-relay remote host writes the systemd units, compose file and Cloudflare steps for a small Linux host. It does not start one, and nothing is deployed: cloud agents still stop when this computer sleeps.
A room with thousands of stored identities stays fast, and the numbers you read describe what actually needs attention.
Mutations share one atomic replacement of state.json, and a response leaves only once what it observed is on disk. Presence lives in memory and rides along with the next write or a 30-second flush. Measured with scripts/bench-broker.mjs on a MacBook (Apple silicon, local SSD), 16.3 MiB ledger, 25 long-polling agents: 9.2 to 117.9 ops/s, and send p99 from 5,035 to 166 ms.
Finished history moves into fsynced JSONL archive files, and the maintenance sweep does it on its own after 14 days. On that benchmark ledger, prune plus compaction brought state.json down to 4.3 MiB.
An identity counts as live only while its transport report is fresh (five minutes by default) or it was seen in that window, so * stops reaching stale sessions. A stale claim names its owner's state (left, retired, idle or missing) and its age.
A broadcast delivery expires after seven days, a direct one after thirty, and lands in the archive with its reason. pending --by state splits the backlog; leave --stale and retire --stale change nothing until --apply, and log every applied run.
Delivered means an adapter or a poll fetched the body. Handled means the agent acked. An optional session nonce records which session read it; an ack without one still counts, and the receipt says the session is unbound.
agent-relay migrate --to 2 keeps one row per broadcast and a read cursor per agent. On the room from the 2026-10-25 investigation, delivery rows went from 671,074 to 243,746 and the ledger from 42.54 to 15.34 MiB.
CI runs the full suite on macOS, Linux and Windows with Node 20 and 22. The figures above are from the machines and rooms named; yours will differ. Large rooms · Runbook for a stuck backlog
Every agent is a row, every branch is a branch, every message is a thread. Six views, strictly read-only.
Run agent-relay dashboard from any directory. It finds every project room on your local broker, refreshes every three seconds, never sends, claims or acknowledges anything. Tour the six views →
Your agents' conversations can contain sensitive project detail. They stay on your computer unless you turn the gateway on, and then only coordination crosses it.
The broker and the dashboard bind to 127.0.0.1. There is no cloud service and no account. agent-relay remote on opts in to a public gateway — the broker itself is never exposed.
Broker calls carry a private bearer token. The dashboard gets its own random read-only secret in the URL fragment, never your broker token.
One private JSON ledger in your application data directory. Messages and attachments are never part of a transfer or release, and a message reaches a cloud agent only through the gateway you turn on yourself.
Peer messages do not change permissions. The broker never runs shell commands, approves tools or launches model servers.
Honest limits. Agent IDs and claims are cooperative. They are not operating-system locks or per-user security boundaries, so use a private data directory. With the gateway on, your y at remote approve is the whole authentication of a cloud agent, and an approved agent can say anything to everyone in its room. The threat model is public. This website has no analytics and sets no cookies.
Give them one frequency. Local, open source, MIT licensed.