Ever worked with two or more agents and find them edit over each other, losing work?
Relay coordinates them, atomic file claims, broadcasts, messages.

In your editor

You know this pattern from pairing. You and a colleague are both editing the same file. You stop, ask them to commit first, then rebase. Or you split the work by file before you start. Or you both push and resolve the merge conflict afterwards. Coordination at the human level, slow, but workable. With multiple AI agents on one machine, the human-coordination loop falls apart.

What Relay does

Relay is the in-flight coordination layer between Twira sessions on the same machine. When session A claims a file, the claim writes to `<project>/.Twira/sessions.db`; every other session sees it. When B tries to claim the same file, its request queues; A’s release auto-grants in arrival order. Conversations between sessions thread through a separate store (`<project>/.Twira/orchestration.db`). Broadcasts go to every active session, tag-filtered so the right people see the right alerts. Eight modes covering claims (start / release / broadcast) and messaging (check / read / reply / complete / list). Both `team` and `relay` aliases resolve to the same underlying tool, pick whichever reads natural.

How it actually works

When you run more than one Twira-aware AI session on the same codebase, two Claude Code windows on the same project, one Claude and one Cursor, one human and one agent both editing, they need a way to coordinate. Without it, they trample each other: two sessions refactor the same function, two sessions rename the same type, two sessions touch the same migration. Relay is the lightweight messaging and file-claim layer that lets parallel Twira sessions talk to each other and stay out of each other’s way.

The problem in one sentence. You are mid-refactor in Session A. Session B has just started on what they think is a separate task, but their first action is going to modify a file you are about to rewrite. Without coordination, B finishes first, you finish second, B’s changes are silently overwritten, neither side knows, and at least one of you has to redo the work. With Relay, B sees A holds the file claim, asks A to hand it over, A finishes the refactor and releases, B is auto-granted the file and proceeds, all without either human in the loop unless they want to be.

Eight modes cover the full coordination loop, four for messaging between sessions, two for broadcasts and claims, two for housekeeping. Each one is a thin verb over the underlying stores.

relay_start, open a new relay conversation with another session. Session A says: "I am about to change the User type signature in src/types/user.ts. Anyone else touching this?" Optionally tagged (shared-type-change, api-breaking, config-update) so other sessions filter on what matters to them.

relay_check, periodically ask "any open relays addressed to me or relevant to my current task?" Returns the waiting conversations the receiving session has not yet read.

relay_read, pull the full thread of a specific relay to understand context before replying.

relay_reply, add a turn to the conversation. "Acknowledged, I will rebase my work on top of yours; let me know when you are done." The thread becomes a proper back-and-forth, persisted alongside the original.

relay_complete, when both parties have confirmed, the owner of the conversation marks it done so it stops appearing in relay_check results. Closed threads stay in the store for audit, just out of the active queue.

relay_list, list recent relays for the project, filterable by status (active, waiting, complete). Useful for the morning "what happened overnight" check, or for a human dropping into a long-running multi-agent run.

relay_broadcast, announce to every session on the project at once: "I just changed the shared User type, every session needs to rebase its callers." Each broadcast carries an optional tag and an optional files list; other sessions filter broadcasts by tag so the right people see the right alerts and the wrong people are not interrupted.

relay_release, release the file claims you were holding. Pass all: true to release every claim from your session, or files: [...] to release specific ones. The release auto-grants any pending requests other sessions had queued for those files, they get the green light the moment you let go, in the order they arrived.

File-claim coordination is the lock layer behind the messaging. When a session claims a file, the claim is written to .Twira/sessions.db through the CoordinationStore. Other sessions trying to claim the same file are queued; on release, the queue auto-grants in arrival order. This is the mechanism that makes "B asks A to hand over the file, A releases, B proceeds" work without either side polling or guessing, the coordination is structural, not advisory.

Two persistent stores back the whole thing. Relay message threads live in .Twira/orchestration.db (the same conversations and messages tables the Team tool uses for its session history). File claims and the grant queue live in .Twira/sessions.db. Both are local SQLite, both survive restart, both are queryable directly if you ever need to debug coordination state, the schema is plain, indexed, and inspectable from sqlite3 on the command line.

Both team and relay resolve to the same MCP tool, pick whichever name reads naturally to the agent or human writing the call. Twira registers relay as an alias for the underlying team MCP tool. Calling team with mode: "relay_start" and calling relay with action: "start" reach the same handler. The alias exists because once you are working with relays you stop thinking of it as "team", it is its own surface, and the tool name should match the mental model.

Scope and limits, read these before evaluating. Relay coordinates Twira-aware sessions on the same machine, running against the same project. It is not a multi-machine sync layer (sessions on different developers’ machines do not see each other), not a substitute for version control (commit your work; Relay handles in-flight coordination, not history), and not a chat tool for humans (messages are agent-to-agent shorthand, not conversation). For multi-machine coordination, the right answer is git plus your team’s usual review workflow. Relay fills the narrow gap between "I am working on this" and "I have committed it", the multi-agent, single-machine case.

Setup is zero. Relay is enabled on every Pro licence, gated through the multi_agent feature flag. Both .Twira/sessions.db and .Twira/orchestration.db are auto-created on first use, with WAL mode and busy-timeout configured. No daemon to run, no port to open, no config to write.

What it isn’t

• ·One machine only. Sessions on different developers’ machines do not see each other. For multi-machine coordination, that is what git + your team’s normal review flow is for.
• ·Not a chat tool for humans. Messages are agent-to-agent shorthand, not conversation. If you need real conversation, Slack and email exist.
• ·Not a version-control replacement. Relay handles in-flight coordination; commit your work when you are done. Relay fills the gap between *"I am working on this"* and *"I have committed it."*
• ·Pro tier. Enabled on every Pro licence. No configuration needed, the coordination and orchestration databases are auto-created on first use.