skills.rest
AgentWorkforce
AgentWorkforceOFFICIAL
Explore all skills by this author →
Website𝕏@agent_relayGitHub

agent-relay

Coordinate multiple Codex agents through Relaycast messaging with ACK and DONE signaling.

812|65|Updated Dec 17, 2025
Search Tags:#messaging#mcp#coordination#Hooks#CODEX#Multi-Agent#relaycast
One-click install
npx skills add https://github.com/AgentWorkforce/relay --skill agent-relay
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: agent-relay
Source: https://github.com/AgentWorkforce/relay/tree/main/plugins/codex-relay-skill
Command: npx skills add https://github.com/AgentWorkforce/relay --skill agent-relay

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires agent-relay, and includes scripts (resource) components.

What problem does it solve?

Codex sub-agents can only report results back to their parent, leaving no way for workers to message each other or the lead in real time. This Skill gives Codex agents a shared message bus with channels, direct messages, and inbox polling so multi-agent teams stay synchronized.

Core Features & Use Cases

  • Auto-setup installer: On first activation, scripts/setup.sh idempotently adds the Agent Relay MCP server to .codex/config.toml, enables hooks, and installs the relay-worker agent definition.
  • Structured coordination protocol: Enforces a startup sequence (workspace setup, registration, inbox check, ACK) and completion signaling with STATUS, BLOCKED, and DONE messages.
  • Hook-driven inbox awareness: SessionStart, UserPromptSubmit, and Stop hooks auto-connect to Relaycast, inject unread messages into context, and block exit while messages remain unread.
  • Use Case: A lead Codex agent spawns two relay-workers to refactor separate subsystems; workers ACK their assignments, exchange peer updates through Relaycast channels, and send DONE with evidence before exiting.

Quick Start

Install the skill into .agents/skills/agent-relay and ask Codex to coordinate a task with relay workers using ACK and DONE signaling over Agent Relay.

Frequently Asked Questions about agent-relay

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I coordinate multiple Codex agents with Agent Relay?▼

Install the skill into .agents/skills/agent-relay, then invoke it with a coordination request. The skill auto-runs scripts/setup.sh to configure the MCP server and hooks, after which the lead registers, spawns workers, and exchanges ACK and DONE messages via Relaycast.

How do I spawn a relay-worker sub-agent in Codex?▼

Delegate a bounded task to the relay-worker custom agent installed at .codex/agents/relay-worker.toml. Include the worker relay name, lead name, workspace key source, exact scope, and completion criteria in the prompt so the worker can ACK and report DONE.

Does Agent Relay require an existing workspace API key?▼

No. If RELAY_API_KEY is unset, the session-start hook auto-creates a new workspace on first use and persists the key and token under ~/.relay. Set RELAY_API_KEY beforehand only to join a specific existing workspace.

What happens if a relay worker does not ACK the assignment?▼

If no ACK arrives within 30 seconds, the lead checks list_agents, re-registers running processes or respawns workers with add_agent, resends the assignment via send_dm, and polls again. After a second failed attempt it reports the exact failed step to the user.

Can Codex stop while unread relay messages exist?▼

No. The Stop hook (stop-inbox.sh) checks the Relaycast inbox and returns a block decision listing unread messages, forcing the agent to read and respond before exiting. The UserPromptSubmit hook also injects unread messages into context.

Related Skills

Explore More Software Engineering Skills→
theflysurfertheflysurfer

julien-mcp-codex-cli

Install Codex CLI MCP server by merging codex-cli into .mcp.json.

Community
Advanced
seshxnseshxn

swarm-code-review

Coordinate multi-lane code reviews by specialist agents and aggregate findings into a prioritized report.

Community
Advanced
vinhnxvvinhnxv
6

git-worktree

Run each worker in its own git worktree with sequential merges.

Community
Advanced
supportersimulatorsupportersimulator
2

fleet-healer

Automate fleet health diagnostics and restore degraded NATS, HTTP, SSH, and seed channels.

Community
Advanced