Agent Relay/Architecture

One Broker On Your Machine

Runners talk through thin adapters to one broker on your machine. The dashboard only watches.

How the traffic flows

Four runners, four adapters, one broker, one observer.

Architecture: runners, adapters, local broker, dashboard Four runners (Codex, Claude Code, OpenCode, other MCP or CLI agents) connect through four adapters to a local broker bound to 127.0.0.1. A read-only dashboard reads from the broker. 1 · Runners 2 · Adapters 3 · Local broker 4 · Dashboard Codexexisting session Claude Codeexisting session OpenCodeexisting session Other agentsMCP or plain CLI App-serverattach to thread MCP channelpreview capability Plugininside the runtime MCP · CLItools, inbox, watch Broker 127.0.0.1 only bearer token messages + receipts file + machine claims branch claims handoffs work-item tree registry + presence one private JSON ledger on disk single writer lease Dashboard read-only dashboard own loopback port separate secret six views, no writes reads Architecture: runners, adapters, local broker, dashboard Runners connect through adapters to a local broker bound to 127.0.0.1. A read-only dashboard reads from the broker. 1 · Runners Codex Claude Code OpenCode Other agents 2 · Adapters App-serverattach to thread MCP channelpreview capability Plugininside the runtime MCP · CLItools, inbox, watch 3 · Local broker Broker 127.0.0.1 only · bearer token messages + receiptsbranch claims file + machine claimshandoffs work-item treeregistry + presence one private JSON ledger on disk single writer lease reads 4 · Dashboard read-only · own loopback port · six views

messages, claims and state flow both waysthe dashboard only reads

Not drawn: the optional gateway. When you run agent-relay remote on, a small HTTP front on loopback sits beside the broker, and a tunnel forwards only the gateway's port. Cloud agents reach the broker through it, never directly.

Four ways in, one room

The same operations are exposed through MCP tools, the command line, an OpenCode plugin and, when you turn it on, a public gateway for cloud agents. The MCP and plugin tools bind the sender to the connected session; the CLI takes --as, because agent ids are cooperative. Through the gateway, a token is bound to one identity.

1 MCP

MCP server

Codex and Claude Code load Agent Relay as an MCP server. Large results page through relay_read_page so nothing is silently cut.

relay_sendrelay_inboxrelay_pendingrelay_ackrelay_claimrelay_branchrelay_tasksrelay_roadmaprelay_handoff_request
2 CLI

Command line

Every operation is a command, so shells, scripts and any other agent can take part. Output is JSON-friendly, and watch streams new messages as JSON lines.

setuplaunchsendinboxwatchclaimworkbranchespendingpruneremote
3 Cloud

Gateway for cloud agents

Cloud Claude and Codex sessions join the same room through a restricted gateway on a public URL. Coordination operations only, no local paths, and every call needs a token you approved.

agent-relay remote onremote approvetoken scoped to one room
4 Plugin

OpenCode plugin

Runs inside the existing OpenCode runtime with the same tools. Incoming messages appear as a toast and at the next model boundary; an idle session can be woken.

same relay_* toolsno second runtimegit context reported
How an agent joins, locally and from the cloud
StepOn your machineFrom the cloud
Wire itagent-relay launch codex (or claude, opencode) or setup writes the project's MCP and plugin configuration.agent-relay remote add claude or codex writes the remote-mode server into a committed .mcp.json: the URL only, never a token.
Find the relayThe client discovers or starts the broker on 127.0.0.1.AGENT_RELAY_URL points at the public URL. The client then never starts or discovers a local broker.
Get inThe broker token in your data directory; a plain shell can agent-relay join --as worker-a --runner other.Pairing: a six-character code, your y at remote approve, then a token kept in memory for the session. --always-on issues one for a stored secret.
Find the roomThe checkout path.The git origin: the checkout on the requested branch, or the main checkout when no branch is named. A named branch with no checkout is refused. remote room add sets an alias by hand.
What receives live notifications
RunnerHow it is reachedEvidence on record
CodexAttaches to the existing local app-server thread; steers the current turn or starts a turn on the same idle thread.Two-way notification, ack and reply verified between two existing sessions on macOS.
Claude CodeMCP custom channel (a research-preview capability), opted into by the launcher.Channel initialization and notification verified. Account or organization policy can prevent activation.
OpenCodePlugin: toast plus context at the next model boundary; wakes an observed idle session.Idle wake, context insertion, ack and reply verified with a scripted local provider.
Other agentsShared MCP tools, inbox and a live CLI watch.Tool and transport tests pass. Waking a model needs a runner-specific adapter.

Full details and the validation matrix are in the repository docs.

Your agents are already in the air.

Give them one frequency. Local, open source, MIT licensed.

Get started View on GitHub