agent-relay
/agent-relay
Use when you need Codex to coordinate multiple agents through Agent Relay for peer-to-peer messaging, lead/worker handoffs, or shared status tracking across sub-agents and terminals.
- Author
- agentworkforce ↗
- Repository
- relay ↗
- Licence
- Apache-2.0
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 10
- Scripts
- 4
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
- 4 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: hooks/prompt-inbox.sh, hooks/session-start.sh, hooks/stop-inbox.sh, scripts/setup.sh
What it does and when to use it
Use when you need Codex to coordinate multiple agents through Agent Relay for peer-to-peer messaging, lead/worker handoffs, or shared status tracking across sub-agents and terminals.
Original author description
Use when you need Codex to coordinate multiple agents through Agent Relay for peer-to-peer messaging, lead/worker handoffs, or shared status tracking across sub-agents and terminals.
How it works
- Auto-setup
- Startup protocol
- Critical rule
- Working rules
- Message templates
- Worker patterns
- Worker ACK fallback
- Handoff template
SKILL.md preview
--- name: agent-relay description: Use when you need Codex to coordinate multiple agents through Agent Relay for peer-to-peer messaging, lead/worker handoffs, or shared status tracking across sub-agents and terminals. --- # 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`). 3. **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 observer` and 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-dms` or `--expires`, and revoke it with `agent-relay observer revoke <id>`. 4. **Check the relay inbox.** Call `check_inbox` to see if there are any pending messages or task assignments. 5. **Send an ACK.** If you received a task assignment, send `ACK: <one-sentence understanding>` to your lead via `send_dm`. If the assignment is unclear, send `BLOCKED: <question>` instead of guessing. 6. **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:** 1. Ensure workspace exists (`set_workspace_key` or `create_workspace`). 2. Register the lead (`register_agent`). 3. Give the other running process the workspace key and tell it to call `register_agent` with a stable name. 4. Send the assignment via `send_dm(to: "worker-name", text: "...")`. 5. Poll lead inbox for ACK (`check_inbox`). **Worker steps:** 1. Call `set_workspace_key` with the shared key. 2. Register with `register_agent`. 3. Check inbox (`check_inbox`). 4. Send ACK to lead via `send_dm`. 5. Perform the assigned scope. 6. 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:** 1. Ensure workspace exists and lead is registered. 2. Spawn the worker with `add_agent(name: "worker-name", cli: "codex", task: "...")`. 3. Include `https://agentrelay.com/skill`, the lead name, exact scope, and completion criteria in the task prompt. 4. Poll lead inbox for ACK (`check_inbox`). 5. Release the worker with `remove_agent` after the work is accepted. **Worker steps:** 1. Follow the `using-agent-relay` role from `https://agentrelay.com/skill`. 2. 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: 1. Check whether the worker appears in `list_agents`. 2. If this is a running process, have it call `register_agent`. 3. If this should be a spawned worker, call `add_agent` with `name`, `cli`, and `task`. 4. Send (or re-send) the assignment via `send_dm`. 5. Poll the lead inbox again for ACK. 6. If still no ACK after a second attempt, report the exact failed step to the user. ## Handoff template ```text 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: ```text Type: Codex sub-agent (use relay-worker if your Codex surface provides sub-agent spawning) ```
Files in this package (10)
- README.md 5 KB
- SKILL.md 7 KB
- agents/openai.yaml 1 KB
- codex-config/config.toml 1 KB
- codex-config/relay-worker.toml 1 KB
- hooks/hooks.json 1 KB
- hooks/prompt-inbox.sh 4 KB
- hooks/session-start.sh 7 KB
- hooks/stop-inbox.sh 4 KB
- scripts/setup.sh 9 KB
Versions
The database has no other skills named agent-relay.
Database snapshot: 13.11.2026 · package version a839cbc46573 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 1 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100using-agent-relay
Use when you are a registered relay agent (a spawned worker, or a lead that called register_agent) coordinating with peers in real time over current Agent Relay MCP tools - messaging, channels, threads, reactions, search, inbox, actions, and worker spawn/release. For role… - 100using-agent-relay
Use when you are a registered relay agent (a spawned worker, or a lead that called register_agent) coordinating with peers in real time over current Agent Relay MCP tools - messaging, channels, threads, reactions, search, inbox, actions, and worker spawn/release. For role… - 81relay-setup
Set up Codex Agent Relay for the first time or open its Agent and model settings. Use after installing this plugin, or when the user wants to change the relay target. Do not select or change the receiving model without the user's choice. - 96peer
Use when you need to talk to another coding agent (Claude Code or Codex) running on this machine or another one, see what other agents are doing, wait for one, or start one — and whenever a message from NAME@HOST (a `[from NAME@HOST]` line, or Claude's "Message from @NAME@HOST")… - 90multi-agent-collaboration
Coordinate multiple agents on implementation or research with isolated ownership, reproducible handoffs, independent checks, and evidence-based conflict resolution. Use when parallel or peer-agent work is requested or already in progress. - 100tma1-peer
List recent sessions on this project by agent — peer agents (Codex, OpenClaw, Copilot CLI) or your own past sessions. Invoke when the user wants you to read another agent's review feedback, see what someone else tried, act on cross-agent context, or recall your own earlier work…