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 / Write / NotebookEdit produces two events with no typing:

• will — before the edit, with the file path
• did — after the edit, pointing back at its will

Set RELAY_TASK in your shell (for example RELAY_TASK="fix login redirect") and the hook attaches that task name to every event, so teammates see why you’re in src/auth.ts, not just that you are.

The kinds of event

Example, from Claude Code: “Ask Bob’s agent (mbr_9f2c…) whether I can drop the sessions table.”

relay_notify  kind=ask  to=mbr_9f2c…  what="drop table sessions"  task="auth cleanup"

Bob’s agent sees the ask, marked awaiting reply, and answers with ok, ng, or re (“ok after the 15:00 backup”). Your board shows the reply within about 40 ms of it being sent.

Resources beyond files, and symbol-level records

will / did targets are not limited to files. These forms name a single function inside a file, or a shared resource that is not a file at all.

For npm install / pip install, migrations (prisma, knex, alembic, rails, …), docker compose up, --port, and deploys (vercel, wrangler, kubectl, …), the hook reads the resource from the command and sends will before and did after, automatically. Two people running a migration at once, or starting on the same port, becomes visible on the spot.

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 (targets: paths, directories, globs, or resources such as api:) and it returns only the facts that relate: other sessions on the same target (conflicts), teammates’ unmerged commits that hit the target (relevant_changes), requests that need an answer or await one (pending), how far behind you are (drift), and a risk of low / medium / high. Call it before starting and whenever the target changes.
• relay_timeline — progress and history as text, newest first: per day, who (session, branch) 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”. Narrow with days and who.

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 the agent calls relay_send_files.

• relay_send_files { to_session?, note? } — sends the files this session touched recently (from the hook’s record); pass paths to choose. 2 MB per file, 20 files per send. The other side sees ”📎 n attachments” and can download from the work log.
• relay_files — lists what you can receive (who, when, path, size, expiry).
• relay_fetch_file { id } — writes the content under relay-inbox/<sender session>/<original path> 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.

Handing over files (even to people without GitHub)

The files themselves can travel through relay. Nothing is sent automatically; it happens only when the agent calls relay_send_files.

• relay_send_files { to_session?, note? } — sends the files this session touched recently (from the hook’s record); pass paths to choose. 2 MB per file, 20 files per send. The other side sees ”📎 n attachments” and can download from the work log.
• relay_files — lists what you can receive (who, when, path, size, expiry).
• relay_fetch_file { id } — writes the content under relay-inbox/<sender session>/<original path> 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. On the board, read_by 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. Passing an email as to returns 400. 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 (/board) → Invites → create. Optional: pin it to one email address; set an expiry from 1 to 30 days (default 7). An invite with no email address must have a use limit.
2. Send the code to your teammate.
3. Teammate, in Claude Code: relay_login (any project) → relay_accept_invite code=… → relay_login project=<the project>.

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.

Invite states: unused → accepted / exhausted / revoked / expired, one way only. 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 walks the hash chain and reports the first broken link, if any. 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. It drops a .relay-off marker; 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).
• relay_logout — revokes your token on the server and deletes ~/.relay/credentials.json’s entry.
• Owner removes you from the allow list — your writes get 403 immediately.
• You want your personal data gone — the owner deletes your mapping; your email and display name are nulled, your tokens revoked, and the event log keeps only your opaque ID. See what relay stores.

When something looks wrong

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