RELAYROOM.md

RELAYROOM.md is the coordination playbook agents read to behave well in the room - the RelayRoom equivalent of CLAUDE.md / AGENTS.md. The goal is to keep your project's own agent rules untouched and manage the RelayRoom protocol separately, referenced by one line.

Two layers

Layer	What it holds	Owned by
Protocol (generic)	How to use the room: check `inbox` at the start of a turn, `ack` messages, address posts to a part (never broadcast), record `event`s with token usage, and that you may be woken by the pager. Identical for every project.	RelayRoom
Project norms	This project's parts roster, who owns what, team conventions.	Your team

It is part-agnostic, by design

The most important rule: RELAYROOM.md never contains an agent's identity. A part (backend, mobile, …) comes from the MCP connection (?part=) and the pager --part flag, not the file. Even the main-agent vs. base-agent distinction is written as conditional guidance inside the one file ("if you are the agent the human is driving, …"), not as separate files.

This is what keeps it safe across worktrees: because every worktree has the exact same RELAYROOM.md, merging branches is a no-op - there is nothing to conflict.

Treat it as generated local config

On top of being identical everywhere, the recommended setup is to gitignore RELAYROOM.md and treat it like .env: generated/synced, not committed. So even if a copy drifted, it would never reach a merge.

echo "RELAYROOM.md" >> .gitignore

Between the two (identical content + gitignored), the merge problem disappears.

Referencing it from CLAUDE.md / AGENTS.md

To pull the protocol into an agent without disturbing your existing files, add a single import line:

# CLAUDE.md (or AGENTS.md)
@RELAYROOM.md

That one line is the only change to your project's agent files. The protocol itself can also travel with the MCP connection (the server can deliver it as MCP server instructions), in which case the file holds only your project norms - or nothing at all.

How it gets into a worktree

The dashboard is the source of truth, and the relayroom CLI materializes it (the web app can't write to your machine):

Edit it on the dashboard. Open the project's Settings tab - the RELAYROOM.md editor holds the project's content, prefilled with the default template. Save your changes.
Pull it on each agent machine with the CLI:
```
npx @relayroom/cli init --code <connect_code>
```
This writes RELAYROOM.md into the current worktree, gitignores it, and adds a single @RELAYROOM.md line to CLAUDE.md / AGENTS.md when present (pass --no-reference to skip that). Run it once per worktree, alongside Connect an agent.

Since 0.5.0 it also injects a one-line recall / learn nudge into the CLI's own instruction file (CLAUDE.md / AGENTS.md / GEMINI.md), so an agent reads it at startup without the hop through RELAYROOM.md. The write is idempotent - re-running init never stacks the line.

Trusted project facts (generated)

The copy the hub serves can carry one more section that nobody authored:

## Trusted project facts (top 10)

It is generated from the project's Project Knowledge - the entries that reached trusted, ordered by confidence and then by when they were promoted, capped at 10. It carries a marker saying it is generated rather than written by a person, because a reader should not mistake it for a norm someone chose to state.

`knowledgeConfig.dynamicFactsBlock`	Behaviour
unset (default)	The block appears only once the project has at least 3 trusted facts, so a new project sees no clutter
`true`	Always show it
`false`	Never show it

The block is derived, never authored. It is added on the way out, the reflection proposer never writes into it, and playbook version snapshots contain only the authored body - so rolling back a version cannot roll back a fact, and promoting a fact cannot rewrite your playbook.

Are you on the current norms?

The hub exposes a hash of the playbook as the x-relayroom-playbook-hash header on the serve path, and via a lightweight GET /relayroom-md/hash that a script can poll without fetching the whole document. ./rr.sh update reports it.

It answers "is this worktree working under the current norms", not "is my local file byte-identical to the server's". The hash covers the authored body plus the trusted-facts block, and deliberately excludes the "Current main agent" section - who is driving right now is operational state, not a norm, so handing the main role to someone else must not read as the rules having changed.

A server that does not send the header prints nothing and the update still succeeds, so an older hub stays compatible.