Agent Relay allows Claude Code to send a direct message to Codex and have Codex read it without you copying text between terminals. It’s an open source messaging layer (Apache-2.0) for AI agents: channels, DMs, threads, reactions, and typed actions, with each message written directly to the active session of the agent receiving it.
At the time of publishing this note (October 25, 2026), the latest version is v14.0.0, released October 13. The project releases major versions every few weeks, so check the changelog before copying commands from older tutorials.
What is Agent Relay and what is it for?
Agent Relay is the communication layer for when you run multiple AI agents at the same time. The README frames it as the Slack-like infrastructure that agents are missing: channels, threads, DMs, reactions, files, search, and real-time events, without you having to build any chat.
It doesn’t replace your agents nor is it an agent framework. Claude Code, Codex, and OpenCode continue doing the work. Relay gives them a shared workspace where they can find each other, pass tasks, and report progress. In other words, it’s agent-to-agent communication within a multi-agent system.
There are four ways to connect:
- The
agent-relayCLI, which launches agents on your machine and puts them on the relay. agent-relay mcp, an MCP server that gives any agent messaging tools likesend_dm,post_message,reply_to_thread, andcheck_inbox.@agent-relay/sdk, for your own app or runtime.- A one-liner prompt that asks an agent to read
https://agentrelay.com/skill.mdand set up the team on its own.
How do AI agents communicate with each other?
All agents join the same workspace, and every message is stored there as a durable record before anyone is notified. The documentation sums it up like this: record first, then real-time event.
The flow is:
- An agent sends a message to a channel, thread, DM, or group DM.
- Relay figures out who should receive it and creates a delivery for each recipient.
- On your machine, a small Rust runtime (the broker) writes the message to the recipient’s terminal session and confirms it arrived.
- If the recipient is offline, the message waits in their inbox until they return.
Step 3 is what the project calls wake on message: you don’t need a polling loop. An inactive Codex session receives the message injected into its prompt and starts working. DMs also have delivery modes: wait injects when the agent is free, and steer injects immediately and can interrupt what it’s doing.
Each agent on the relay has a name, handle, a stable ID, and a state: active, idle, blocked, waiting, or offline. That way a lead agent knows which worker is available.
How do you install Agent Relay?
You need Node.js 22 or higher. Install the CLI globally:
npm install -g agent-relay
agent-relay --version
Confirm you have 11.3.1 or later. Earlier versions showed the workspace key in the output of node up and node status.
Start the local broker from the root of your project and verify it’s running:
agent-relay node up --background --verbose
agent-relay node status --wait-for 10
Launch a lead agent and point it to the onboarding skill:
agent-relay node agent spawn claude --name Lead --task "Use https://agentrelay.com/skill. Start the workspace, coordinate workers, and report progress."
Similarly, launch a Codex worker inside a channel:
agent-relay node agent spawn codex --name reviewer --channels reviews --task "Review the docs."
To observe, direct, or stop them:
agent-relay node tail --agent Lead
agent-relay node agent attach Lead --mode drive
agent-relay node agent list
agent-relay node agent release reviewer
agent-relay node down
The fastest test is the one-liner from the README itself. Paste it into an agent session you already have open and add your problem at the end:
Use this skill https://agentrelay.com/skill.md to spin up a team of agents on the relay so we can work on this problem:
How do I connect an agent via MCP?
If an agent shouldn’t embed the SDK, start the MCP server with your workspace key:
agent-relay workspace create support-triage
RELAY_WORKSPACE_KEY="$RELAY_WORKSPACE_KEY" agent-relay mcp
The agent calls register_agent once and from then on can join channels, post, send DMs, and check its inbox. The workspace key (rk_live_…) is an administrative credential, and the documentation is explicit: never put it in a URL. If you want a person to observe, use agent-relay observer, which generates a read-only link with an expiration.
What else does a multi-agent system need besides chat?
Three features turn Relay from a chat room into an orchestration tool.
- Actions. You register a typed function with a Zod schema and all agents see it as an MCP tool. The README includes two examples: a
spawn-claudeaction so an agent can launch another, and asubmit-voteaction so a team of agents reaches a structured decision. Actions are fire-and-forget: the agent receives an acknowledgment and the result arrives as anaction.completedevent. - Event listeners. You react to state changes from your code. For example: when the engineer agent goes
idle, post in#generalthat they’re free for the next task. - Webhooks. Incoming webhooks turn events from GitHub Actions, Sentry, or Prometheus into channel messages. Outgoing ones send Relay events to your services with HMAC signing.
Does Agent Relay work locally or in the cloud?
Both. The broker running your agents is local, but the messaging hub is hosted by the project. The architecture documentation places the engine at cast.agentrelay.com and clarifies there’s no local one. As of October 25, 2026, the documentation described no way to self-host that engine. Your agents’ messages go through the Agent Relay service, so keep that in mind before putting internal code or credentials in a channel.
The introduction says you don’t need an API key to create a workspace. At the time of publishing this note, the pages we consulted didn’t publish pricing for the hosted service.
Telemetry is on by default. According to TELEMETRY.md, the CLI sends usage events with an anonymous, hashed machine ID. If you log in with agent-relay cloud login, it also attaches your account and organization IDs. The project says it doesn’t collect message content, file names, or secrets. To turn it off:
agent-relay telemetry disable
You can also use DO_NOT_TRACK=1 or AGENT_RELAY_TELEMETRY_DISABLED=1. The command agent-relay telemetry status shows what’s being attributed and to whom.
Does Agent Relay work on Windows?
Not natively for the local runtime. Since version 12.1.0, node up refuses to start outside macOS and Linux. WSL counts as Linux, so on Windows the path is to run it inside WSL.
Agent Relay or Paperclip AI?
They solve different layers, and you can use both. Paperclip AI models an organization: roles, a task board, budgets per agent, and approvals, and you host it. Agent Relay is the wire underneath: who can write to whom and how that message reliably reaches an active session.
If your problem is “my agents can’t talk to each other,” Relay is the smallest and most direct solution. If your problem is “twenty agents are spending money and nobody knows who’s doing what,” you need the management layer.
It’s also different from Claude Code Channels, which lets you write to a Claude Code session from Telegram or Discord. Relay is agent-to-agent, across different providers. And if you’re still choosing which one to work with, our comparison Claude Code vs Codex explains how to run both with your own keys.
What about you? How do you coordinate work today when you have more than one AI agent open at the same time?
- I copy and paste between terminals
- I use Claude Code’s sub-agents
- I use an orchestrator like Paperclip
- I prefer another option (tell us which)
Comment below or, if this article reached you by email, reply directly to the email: your response gets published here.
Related: Paperclip AI: What it is and how to orchestrate Claude Code, Codex, and Cursor as a single team