Skip to main content
The relay is for sessions that are open at the same time. One can hand work to another, ask it a question, or claim a file so nobody collides. It exists so you stop copying context between terminals by hand.

​
Give every session a title

Why it works. A title is a stable name for a live session, and everything else addresses that name rather than a session id you would have to look up. base relay sessions lists titled sessions in the global registry, which is what task and ping targets resolve against. The gotcha. Do this first, in every session. Until a session has a title it cannot be addressed and cannot receive anything. A session you forgot to register is invisible, not merely hard to reach.

​
Handing over real work

Why it works. A task carries a briefing document, so the receiving session has everything it needs to work without asking you. It fires in that session’s hooks until it is picked up, and it crosses workspaces through the global tier. The gotcha. The receiver clears it with base relay done refund-handling. Until then it keeps firing, which is the point: a task that stops reminding the receiver is a task that gets dropped. Next rung. Keep the slug and the briefing document’s filename identical. That way the slug shown in base relay tasks is enough to find the document.

​
Asking a quick question

Why it works. A ping has no document and no completion step. It interrupts the receiver mid-turn, and their reply is what clears it. The gotcha. An unanswered ping keeps re-firing in the receiver’s session. Reply to clear it:
When to use which. If it needs a document, it is a task. If it fits in three sentences, it is a ping. Sending a task’s worth of context as a ping means that context has nowhere to live afterwards.

​
Waiting instead of polling

Why it works. wait blocks and costs nothing while it waits. A polling loop spends a tool call and some context on every tick and finds nothing almost every time. Narrow what it wakes for with --from, --type and --project, and bound it with --timeout (default 300 seconds).

​
Not colliding

Why it works. Claims are advisory. Nothing enforces them, and an expired claim simply stops appearing. What they buy you is that base relay board shows who is where before two sessions open the same file. The gotcha. --force on release takes someone else’s claim. Use it when a session died holding one, not to win an argument.

​
When a message seems not to arrive

Delivery happens through hooks, and hooks only fire on a tool call. A receiving session sitting idle never sees a waiting message. It has to do something before it notices.
This is the single most common confusion with the relay, and it looks exactly like a message that was never sent. The second gotcha. base relay poll and base relay board are scoped to the workspace, while tasks and pings route through the global session registry. So “No relay stores exist” from board is not evidence that a message did not arrive. base relay sessions showing the target as live is the more trustworthy signal.

​
The lower-level primitive

--type takes claim, release, notify, unblock, contract-change, ready-to-merge, question or answer. --to takes a title, a session id, phase:<n>, or all. The gotcha. base relay poll consumes the messages it reads. Use --peek when you want to look without clearing.

​
Tearing it down

The store is deliberately disposable: it is a working surface for a milestone, not a permanent record. export writes a read-only snapshot first if you want to keep any of it, and dispose previews until you pass --force.

​
Wrapping it in star commands

Everything above is the command line. If you would rather type *task builder implement partial refunds than the full command, that is a star command you write yourself:
base does not ship these. The relay commands are the product; the shorthand is yours.

​
Next

Handoffs and forks

The other seam: work that spans sessions rather than running beside them.

Sessions reference

Every relay verb and flag.