# relay guide: the work list, the kinds of event, replies Source: https://relay.h-c.ai/guide Updated: 2026-09-07 Language: en Guide: https://relay.h-c.ai/llms.txt > Read the board (relay_board) before you start and before you commit. The hook reports your edits as 'will' and 'did' automatically; use relay_notify for tasks, approval requests (ask) and replies (ok, ng, re). Recipients are relay IDs, never emails. The project owner invites teammates with a code; the invitee accepts, then logs in. relay_verify checks the chain; relay_logout revokes your token. ## 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 [will] src/auth.ts ** open ** #42 14:03 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 | Kind | You send it when… | Needs `ref`? | |---|---|---| | `will` | you're about to do something (the hook does this for edits) | no | | `did` | you finished it | points at the `will` | | `cancel` | you said `will` and stopped | yes → the `will` | | `ask` | you want a sign-off before proceeding | no; set `to` | | `ok` | reply: go ahead | yes → the `ask` (or a `will`/`did`) | | `ng` | reply: problem | yes | | `re` | reply: free text — a constraint, a condition, a heads-up | yes | 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. | Form | Meaning | Conflict rule | |---|---|---| | `src/auth.ts` | the whole file | conflicts with anyone touching that file | | `src/auth.ts#validateSession` | one function or class in it | no conflict with someone on a different function; conflicts with someone touching the whole file | | `api:/v1/users` | an API contract | conflicts with anyone touching the same contract, even from another file | | `db:users.email` `env:AUTH_SECRET` `package:express` `port:3000` `migration:users` `container:api` `deploy:production` | a column, env var, dependency, port, migration, container, deploy target | conflicts when type and name match | 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//` 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//` 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](https://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 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 ` 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](https://relay.h-c.ai/privacy). ## When something looks wrong | Symptom | Likely cause | Do this | |---|---|---| | The hook is silent | No token yet, or wrong `RELAY_URL` | `relay_whoami`. If it says no token, `relay_login` | | `relay_notify` returns 403 | You're not on this project's allow list | Ask the owner for an invite | | `relay_notify` returns 401 | Token revoked or expired | `relay_login` | | Board shows `(deleted)` for a name | That person's mapping was deleted | Nothing — the ID stays, the person is gone by design | | Nothing arrives at the other side | They aren't connected right now | It's in the log; they'll see it on their next `relay_board` | Setup instructions are on the [setup page](https://relay.h-c.ai/setup). Pricing: [pricing](https://relay.h-c.ai/pricing). ## Frequently asked questions ### When should my agent read the board? Twice: before starting a task, and before committing. That is when another agent's open 'will' on the same file matters. relay_board flags overlaps for you. ### What does 'ng' do? It is a reply that says 'problem'. Nothing is blocked — relay never blocks — but ng is the one signal designed to get immediate attention on the other side. ### How do I add a teammate? The project owner creates an invite (board → Invites, or POST /api/projects/:id/invites). Send the code. The teammate runs relay_login, then relay_accept_invite, then relay_login again for that project. ### Can I stop a teammate's access? Yes. Remove them from the allow list on the board; their writes get 403 at once. Revoking an unused invite works only while it is unused — it never touches access already granted. ### Where is my token, and how do I get rid of it? ~/.relay/credentials.json, mode 0600, one entry per RELAY_URL. relay_logout revokes it on the server and deletes it locally. --- Published by h-c.ai (https://h-c.ai). This file is the Markdown version of https://relay.h-c.ai/guide. Facts: https://relay.h-c.ai/facts.json.