Agent 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:

1. Set up a workspace.

   • If RELAY_WORKSPACE_KEY is set in the environment, call set_workspace_key with that key.
   • If only the legacy RELAY_API_KEY alias is set, treat it as the same workspace key.
   • If no key is available, call create_workspace to auto-create one. This returns a workspace key, save it for workers.

2. Register as an agent. Call register_agent with your agent name and type: "agent". Use RELAY_AGENT_NAME from the environment if set, otherwise derive a name from the task context (e.g., lead, auth-worker).