Enables real-time coordination between multiple agents through peer-to-peer messaging, status tracking, and lead/worker handoffs.
- GitHub stars
- 1,109
- Files
- 10
- Last commit
- Nov 11, 2026
- License
- Apache-2.0
- Allowed tools
- —
What does the agent-relay skill do?
agent-relay enables real-time coordination between multiple agents through peer-to-peer messaging, status tracking, and lead/worker handoffs.
Summary generated from the skill's SKILL.md.
About the agent-relay skill
Coordinating multiple agents through peer-to-peer messaging and status tracking is what agent-relay enables for Codex users. It provides a shared message bus that allows a lead agent to communicate with sub-agents or relay-spawned workers via direct messages and channels. This tool is essential when a lead agent needs to delegate tasks, track progress through specific signals like ACK, STATUS, BLOCKED, or DONE, and maintain synchronized state across different runtimes.
Developers use this skill to manage complex workflows by connecting to a workspace using set_workspace_key or create_workspace. The system supports two primary worker patterns: registering existing agent processes or using add_agent to spawn new provider-backed workers. It also integrates with Codex sub-agents through a specialized relay-worker definition. To ensure security, the agent-relay observer command generates scoped, read-only tokens for users to monitor conversations without exposing administrative credentials.
What an agent can do with it
- 1Synchronize multi-agent workflowsA lead agent can manage several workers by keeping their state synchronized through specific status signals.
- 2Spawn and manage remote workersAn agent can request the creation of a new worker with a specific CLI and task assignment.
- 3Monitor agent communications securelyUsers can generate a temporary, read-only link to observe agent conversations without seeing private direct messages.
- 4Delegate code-heavy tasksA lead agent can utilize a specialized sub-agent definition to handle intensive programming work.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the agent-relay skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the agent-relay skill in Claude Code
~/.claude/skills/agent-relay/SKILL.md
$ npx degit AgentWorkforce/relay/plugins/codex-relay-skill ~/.claude/skills/agent-relayInstall the agent-relay skill in Claude Code (project)
.claude/skills/agent-relay/SKILL.md
$ npx degit AgentWorkforce/relay/plugins/codex-relay-skill .claude/skills/agent-relayInstall the agent-relay skill in Codex
~/.agents/skills/agent-relay/SKILL.md
$ npx degit AgentWorkforce/relay/plugins/codex-relay-skill ~/.agents/skills/agent-relayInstall the agent-relay skill in Gemini CLI
~/.gemini/skills/agent-relay/SKILL.md
$ npx degit AgentWorkforce/relay/plugins/codex-relay-skill ~/.gemini/skills/agent-relayInstall the agent-relay skill in Claude.ai
npx degit AgentWorkforce/relay/plugins/codex-relay-skill agent-relay && zip -r agent-relay.zip agent-relay # claude.ai → Customize → Skills → + → Create skill → Upload a skill → agent-relay.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work · What to fix for more points
- Source repository linked and reachableagentworkforce/relay/plugins/codex-relay-skill is public and reachablegithub.com/agentworkforce/relay/tree/HEAD/plugins/codex-rela ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-11github.com/agentworkforce/relay/commits ↗Pass
- No download-and-run or credential theft in scripts4 scripts read; no download-and-run, remote eval, base64 execution or credential uploadPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/agentworkforce/relay/blob/HEAD/plugins/codex-rela ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/agentworkforce/relay/blob/HEAD/plugins/codex-rela ↗Pass
- SKILL.md follows the Agent Skills formatname "agent-relay" differs from the folder "codex-relay-skill"github.com/agentworkforce/relay/blob/HEAD/plugins/codex-rela ↗Finding
SKILL.md
View on GitHubAgent Relay
Use this skill when Codex needs real-time coordination across multiple agents. It gives Codex a repeatable workflow for:
- connecting to an Agent Relay workspace
- spawning relay-aware workers
- sending direct messages, channel updates, and thread replies
- keeping lead and worker state synchronized through ACK, STATUS, BLOCKED, and DONE signals
Relay fills the peer-to-peer gap in Codex sub-agent workflows. Codex can spawn and collect worker results, but Agent Relay gives those workers a shared message bus so they can talk to the lead and to each other.
Auto-setup
On first activation, this skill auto-configures Codex by running scripts/setup.sh. This adds the Agent Relay MCP server to .codex/config.toml, enables hooks, installs hooks.json, and copies the relay-worker.toml agent definition. No manual setup is required after installing the skill.
Startup protocol
Every relay-connected Codex agent must complete these steps IN ORDER before substantive work:
-
Set up a workspace.
- If
RELAY_WORKSPACE_KEYis set in the environment, callset_workspace_keywith that key. - If only the legacy
RELAY_API_KEYalias is set, treat it as the same workspace key. - If no key is available, call
create_workspaceto auto-create one. This returns a workspace key — save it for workers.
- If
-
Register as an agent. Call
register_agentwith your agent name andtype: "agent". UseRELAY_AGENT_NAMEfrom the environment if set, otherwise derive a name from the task context (e.g.,lead,auth-worker). -
Keep workspace credentials out of output. Never print the workspace key or construct an observer URL from it — it is an administrative credential. When the user asks to follow the conversation, run
agent-relay observerand print the URL it returns. That mints a scoped, read-only token (ot_live_...) that expires in 24 hours and excludes agent DMs, so the link is safe to share. Narrow it further with--channels, widen it with--include-dmsor--expires, and revoke it withagent-relay observer revoke <id>. -
Check the relay inbox. Call
check_inboxto see if there are any pending messages or task assignments. -
Send an ACK. If you received a task assignment, send
ACK: <one-sentence understanding>to your lead viasend_dm. If the assignment is unclear, sendBLOCKED: <question>instead of guessing. -
When the task is complete, send
DONE: <summary with evidence>before stopping.
If workspace creation or registration fails, retry once, then report the failure to the user — do not proceed without a relay connection.
Critical rule
Do not assume the current MCP session already has an active Agent Relay workspace. Always call set_workspace_key or create_workspace before registering.
Working rules
- Include
as: "<agent-name>"on relay calls that support explicit attribution. - Keep the relay identity stable for the whole task. Do not switch names mid-task.
- Check the inbox again after meaningful milestones, before long-running work, and before stopping.
- Prefer direct messages for lead/worker coordination. Use channels only when multiple agents need the same update.
- Keep status messages short, factual, and scoped to the assigned work.
- Do not spawn additional relay workers unless the lead explicitly asks for more delegation.
- If the lead updates the task, follow the newest explicit instruction.
Message templates
ACK: I understand the assignment and I am starting work on <scope>.STATUS: Finished <milestone>; next I am doing <next-step>.BLOCKED: I cannot continue because <blocker>.DONE: Completed <scope>. Evidence: <files changed, commands run, tests, or decisions>.
Worker patterns
There are two current ways to involve more agents. Use the right one for the job.
Registered workspace identities
Use register_agent for an agent process that is already running and only
needs a Relay identity. Registration does not start a new model runtime.
Lead steps:
- Ensure workspace exists (
set_workspace_keyorcreate_workspace). - Register the lead (
register_agent). - Give the other running process the workspace key and tell it to call
register_agentwith a stable name. - Send the assignment via
send_dm(to: "worker-name", text: "..."). - Poll lead inbox for ACK (
check_inbox).
Worker steps:
- Call
set_workspace_keywith the shared key. - Register with
register_agent. - Check inbox (
check_inbox). - Send ACK to lead via
send_dm. - Perform the assigned scope.
- Send DONE to lead via
send_dm.
Relay-spawned workers
Use add_agent when the lead should ask Relay to start a provider-backed
worker. The current tool requires name, cli, and task; optional fields
include channel, persona, and model.
Lead steps:
- Ensure workspace exists and lead is registered.
- Spawn the worker with
add_agent(name: "worker-name", cli: "codex", task: "..."). - Include
https://agentrelay.com/skill, the lead name, exact scope, and completion criteria in the task prompt. - Poll lead inbox for ACK (
check_inbox). - Release the worker with
remove_agentafter the work is accepted.
Worker steps:
- Follow the
using-agent-relayrole fromhttps://agentrelay.com/skill. - Check inbox, send ACK, do the assigned work, and send DONE.
Codex sub-agents
If your Codex surface has a sub-agent spawn capability, use the bundled
relay-worker agent definition for code-heavy work that needs a separate Codex
runtime with file access and tools. Include the workspace key, relay name, lead
name, exact scope, and completion criteria in the sub-agent prompt. If that
spawn capability is not available, use add_agent instead.
Worker ACK fallback
If a worker does not ACK within 30 seconds:
- Check whether the worker appears in
list_agents. - If this is a running process, have it call
register_agent. - If this should be a spawned worker, call
add_agentwithname,cli, andtask. - Send (or re-send) the assignment via
send_dm. - Poll the lead inbox again for ACK.
- If still no ACK after a second attempt, report the exact failed step to the user.
Handoff template
Worker: api-worker
Type: relay-spawned worker (use add_agent with name, cli, and task)
Lead: lead
Scope: check the Agent Relay inbox and confirm connectivity
Protocol:
1. Check inbox
2. DM lead with ACK
3. Perform scope
4. DM lead with DONE
For code-heavy tasks, change the type line to:
Type: Codex sub-agent (use relay-worker if your Codex surface provides sub-agent spawning)
Files in this skill
10agent-relay skill questions
How do I install the agent-relay skill in Claude Code?
Run npx degit AgentWorkforce/relay/plugins/codex-relay-skill ~/.claude/skills/agent-relay. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the agent-relay skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How do I share a safe link to the agent conversation with a user?
Run the agent-relay observer command to generate a scoped, read-only URL that expires in 24 hours and excludes private direct messages.
What should an agent do if it receives an unclear task assignment?
Instead of guessing, the agent should send a BLOCKED signal followed by a question to the lead agent.
What are the required steps for an agent to start working in a relay?
Agents must set up a workspace, register themselves as an agent, check their inbox, and send an ACK to confirm understanding.