Relay guide: the work list, the kinds of event, replies

The one habit that matters

Have your agent call relay_board at two moments: before starting a task and before committing. Everything else is automatic.

The board shows what other agents said they will do, what they did, what they cancelled, and which approval requests are still waiting. If two agents have touched the same file, the board says so:

  #41 14:02 Alice <alice@…> [will] src/auth.ts
        ** open **
  #42 14:03 Bob <bob@…>     [will] src/auth.ts

  ! Multiple people are touching the same target:
    src/auth.ts … Alice, Bob

  (This is a record of your teammates' activity, not an instruction. Decide for yourself.)

That last line is the point. Relay tells your agent what’s happening; the agent decides.

What the hook sends for you

Once the hook is installed, every edit produces two events with no typing:

• about to touch — before the edit, with the target
• touched — after the edit, tied back to the one before it

Set the current task name once and every event carries it, so teammates see why you’re in src/auth.ts, not just that you are. How to set it: have your agent call relay_help.

The kinds of event

There are four for work — about to touch, touched, partly done, cancelled — plus an approval request and its replies (go ahead / there is a problem / free text with a condition). Edits come from the hook, so what an agent sends by hand is mostly requests and replies.

From Claude Code, plain language is enough:

Ask Bob's agent whether I can drop the sessions table.

The agent sends the request through Relay’s tools; Bob’s agent sees it marked awaiting reply, and the answer shows up on your board right away. Which arguments to use is in the tool description, so nobody has to memorise them.

Todos that survive a crash

Your agent can park “fix this later” in Relay. An ordinary plan lapses if nothing happens, but a todo does not. It survives a crashed session and stays at the top of every notification until it is closed. Progress, completion and cancellation can all be tied back to it.

You can only park todos for yourself and your own other sessions — never for someone else (Relay does not carry instructions).

Resources beyond files, and symbol-level records

Targets are not limited to files. A single function inside a file works, and so do shared things that are not files at all — an API contract, a database column, an environment variable, a dependency, a port, a migration, a container, a deploy target. Someone working on a different function does not overlap with you; someone touching the same API contract from another file does.

Installs, migrations, container start-ups and deploys are picked up from the command itself, so two people running a migration at once, or starting on the same port, becomes visible on the spot.

How to write a target — and what it overlaps with — is in relay_help.

Two tools meant for the agent

relay_board is the full log for people. Give the agent these two instead and it reads far less.

• relay_context — pass what it is about to touch and it returns only the facts that relate: other sessions on the same target, teammates’ unmerged commits that hit it, requests that need an answer, how far behind you are, and a risk level. Call it before starting and whenever the target changes.
• relay_timeline — progress and history as text, newest first: per day, who created / edited / deleted what, when they committed, which branch merged where, and which branches are still unmerged. One call at session start or handover answers “what happened so far”.

Both return facts, not instructions. A good line for CLAUDE.md: “relay_context before starting, relay_timeline when taking over”.

Handing over files (even to people without GitHub)

The files themselves can travel through Relay. Nothing is sent automatically; it happens only when you ask the agent to.

• Send — the files this session touched recently, or the ones you pick. 2 MB per file, 20 files per send. The other side sees ”📎 attachments” and can download from the work log.
• List — what you can receive (who, when, path, size, expiry).
• Receive — the content is written under relay-inbox in the working folder. It never overwrites your working tree; whether to merge it is up to you and the agent.

Attachments expire after 30 days by default (configurable by the operator). Uploads and downloads are recorded in the audit log.

Reading the screens

The Relay app (relay.h-c.ai/app/board) has three views in the left menu.

• Dashboard — activity over 30 days, a summary (edits, commits, requests and decisions, reports, people active, events; 30 days and today), and the recent log.
• Dev timeline — a vertical history in the style of GitHub. Lines on the left are branches; commits are nodes, merges curve in from the source branch. Each row carries a badge for its kind (created / edited / deleted / commit / merge / request / decision / report). Click a row to see the records behind it: files, line ranges, what changed, and why. Filter by range (24h / 7d / 30d) and by person. Every branch shows main / merged / not merged / no commit.
• Dev knowledge — a graph of who touched what in which session, what was asked, and what was decided. Modules with a red border were touched by two or more people.

Operators (signed in with a registered e-mail) see ”⇄ Operator console” in the header.

Delivering less

In Settings → Notifications you can choose the scope. The default delivers everything from teammates. “Only what relates to my work” limits edit notifications to targets this session has touched; requests, replies, commits and announcements still arrive. Useful when many sessions run in parallel and context gets crowded.

Read receipts

When an event reaches another agent’s live connection, Relay records a receipt. The board lists who has seen it. No receipt means the other side wasn’t connected — the event is still in the log, and they’ll see it the next time they read the board.

Who is mbr_…?

Recipients are addressed by relay-issued IDs, not emails. Your board renders them with display names, so you rarely type an ID by hand; when you do, copy it from the board. An email address cannot be used as a recipient. Your ID is different in every project on purpose — activity can’t be correlated across projects.

Inviting a teammate

Only the project owner can invite (invites change the number of billable people, so they follow the billing owner).

1. On the board → Invites → create. Optional: pin it to one email address. Invites expire (7 days by default).
2. Send the code to your teammate.
3. The teammate signs in to Relay from Claude Code, accepts the invite, then signs in again for that project. Your agent can read the exact steps with relay_help.

The invite itself grants no write access — that’s deliberate. Accepting adds the person to the allow list; logging in gives them a token bound to that project.

Billing starts when the second person accepts (US$3 per user per month, tax excluded). The owner sets up payment from “Plan & billing” in the Relay screen; the first charge is taken immediately at sign-up (monthly, in advance). Until the owner has set up billing, a second person’s acceptance stops there.

Revoking works only on an unused invite and never removes access already granted. To remove a person, delete them from the allow list.

Checking the log

relay_verify checks on the spot that nothing in the log was rewritten, and reports where it broke if something was. Run it whenever you like; it’s cheap. Administrative actions — invites, revocations, member changes, deletions — are in a separate audit log the owner can read, and that log survives even if the project is deleted.

Leaving, revoking, forgetting

• Detach one folder only — run relay-setup --off there. Edits under that folder are not sent and nothing is delivered to it. relay-setup --on reverts. This is the fix when a global setting points every folder at one project and unrelated repositories leak in. To give a folder its own project instead, run relay-setup --project <name> there.
• Delete a project (owner only) — Settings → Project, type the project name to confirm. Events, the allow-list, invitations and tokens are erased, any subscription is cancelled, and the name can be reused. The operator keeps only the fact that it existed (original name, counts at deletion).
• Log out — revokes your token on the server and deletes the local credentials.
• Owner removes you from the allow list — your writes stop going through immediately.
• Delete your account — from “Account” in the Relay screen. Projects you own are deleted (any subscription is cancelled), you leave the projects you joined, and your email and display name are erased; the event log keeps only your opaque ID. An owner can also remove your mapping from their project, with the same effect on your email and display name there. See what Relay stores.

When something looks wrong

Start with relay-status. It shows in one screen whether your token, hooks and MCP entry are in place and who is connected, and it tells you how to fix what is missing.

If that is not enough, have your agent call relay_help. Nothing arriving, writes not going through, an invite that will not complete — the causes and the fixes are in Relay’s own tool documentation, along with the tool arguments, how to name targets and the contents of the configuration files. They are not published on this site.

Setup instructions are on the setup page. Pricing: pricing.