| name | relay-fanout |
| description | Run a fan-out relay pattern for independent subtasks. Use when the same kind of work can be split across files, components, services, or targets with minimal coordination. |
| argument-hint | [task] |
| disable-model-invocation | true |
Run a relay fan-out for this task:
$ARGUMENTS
How spawning works
Workers are spawned using Claude Code's built-in Agent tool, not the relay MCP tools. The relay is only used for communication between agents.
- You must use
subagent_type: "relay-worker" when spawning workers. Only relay-worker subagents get the Agent Relay MCP server, inbox-polling hooks, and the worker protocol. Regular subagent types (e.g. researcher, general-purpose) cannot communicate via relay.
- Run all workers in background mode (
run_in_background: true) so they execute concurrently.
- Each worker's prompt must include the workspace key so the worker can authenticate. See the spawn example below.
- The
SubagentStart hook automatically injects relay bootstrap instructions into every spawned worker.
- Do not introduce extra setup scripts or dependencies in this workflow. Use the existing plugin hooks, Agent Relay MCP tools, and
relay-worker agent definition only.
- Use relay MCP tools (
send_dm, check_inbox) to monitor worker progress.
Protocol
- Pick a stable coordinator name such as
relay-lead. On every relay tool call you make as the coordinator, include as: "relay-lead" so your messages, inbox checks, and reactions stay attributed to the lead.
- Set up the workspace. Try calling
register_agent with a coordinator name like relay-lead. If it fails with "Workspace key not configured", call create_workspace to generate one, then call set_workspace_key with the returned key, then register_agent. Save the workspace key — you will pass it to every worker.
- Tell the user they can follow along with the conversation. Print the full observer URL with the real key value:
https://agentrelay.com/observer?key=<the actual key>. Do not print a placeholder — print the real URL the user can click. This is mandatory.
- Confirm the work is truly parallelizable. Every worker should be able to finish without waiting on another worker's output.
- Decide the worker count from the task shape. Prefer 2 to 8 workers, but keep the count low enough that you can still monitor ACKs and completions reliably.
- Partition the work into independent units. Each unit should have its own files, target, or scope boundary and should not require shared intermediate state.
- Spawn one worker per unit using the Agent tool. You must include the workspace key in the prompt:
Agent(
subagent_type: "relay-worker",
run_in_background: true,
prompt: "You are relay-worker-N. Your lead is relay-lead.
Workspace key: <the actual key>.
CRITICAL: On every relay tool call, include as: \"relay-worker-N\". Without as, your messages can be attributed to another agent.
Your unit: [specific target/scope].
Files: [list of files/directories].
Deliver: [concrete output]."
)
- Each worker's prompt must include:
- the workspace key
- the unit it owns
- the exact files, directories, or target it should handle
- its assigned relay name and who its lead is
- a reminder to use
as: "<worker-name>" on every relay tool call
- Wait for ACK from every worker via relay inbox with
check_inbox(as: "relay-lead"). Missing ACK means the worker is not ready.
- Let workers run independently. Only send follow-up DMs for blockers, missing ACKs, or a global decision that changes all units, always using
as: "relay-lead" for coordinator messages.
- Collect all DONE messages, verify the outputs, and merge the final summary. Call out any units that finished partially or encountered blockers.
Rules
- Do not use this pattern when stage N depends on stage N-1. That is a pipeline.
- Do not give multiple workers the same files unless duplicate review is intentional.
- Keep the task wording uniform so worker outputs are easy to compare and merge.
- Workers cannot spawn their own subagents — only the lead can spawn workers.
