Claude Skill

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.

LLM Mart · 0 points · 27 views 100 listing impressions 0 install-command copies
Download agentworkforce-relay-plugins_codex-relay-skill-a8d2cab.zip · 14 KB

Install

skills CLI npx skills add https://github.com/AgentWorkforce/relay/tree/main/plugins/codex-relay-skill
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agentworkforce-relay@llmmart
Git git clone https://github.com/AgentWorkforce/relay.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agentworkforce/relay collection as a plugin from our marketplace. Git is the plain clone.

README

Codex Relay Skill

Codex-native multi-agent coordination via Relaycast.

What it does

This package gives Codex a reusable relay coordination layer so sub-agents can communicate through Relaycast instead of staying limited to parent-only result collection.

It includes:

  • a Codex skill that teaches lead and worker messaging protocol
  • an Agent Relay MCP dependency declaration
  • a template Agent Relay MCP config block for .codex/config.toml
  • a relay-worker custom agent template for .codex/agents/

With these pieces installed, Codex can:

  • coordinate teams through direct messages, channels, and threads
  • require ACK/DONE signaling from workers
  • let workers send peer-to-peer updates through Relaycast
  • reuse the same relay workflow across project-scoped and user-scoped setups

Installation

mkdir -p .agents/skills
cp -R plugins/codex-relay-skill .agents/skills/agent-relay

That's it. Everything else is automatic.

On first use, the skill self-installs by running scripts/setup.sh, which:

  • adds the Agent Relay MCP server to .codex/config.toml
  • enables features.codex_hooks = true
  • writes .codex/hooks.json with SessionStart, UserPromptSubmit, and Stop hooks
  • installs .codex/agents/relay-worker.toml

All of this is idempotent — safe to run multiple times, and it merges with existing config rather than overwriting.

For user-wide availability, install to $HOME/.agents/skills/agent-relay instead.

Optional: join an existing workspace

Set RELAY_API_KEY before launching Codex to join a specific Relaycast workspace:

export RELAY_API_KEY="rk_live_your_key_here"

If unset, a new workspace is auto-created on the first session.

Manual setup (advanced)

If you prefer to configure everything manually instead of using the auto-installer:

  1. Add to .codex/config.toml:
features.codex_hooks = true

[mcp_servers.agent-relay]
command = "npx"
args = ["-y", "agent-relay", "mcp"]
env = { RELAY_API_KEY = "", RELAY_BASE_URL = "https://cast.agentrelay.com", RELAY_AGENT_TYPE = "agent" }
  1. Copy hooks config:
cp .agents/skills/agent-relay/hooks/hooks.json .codex/hooks.json
  1. Install the worker agent:
mkdir -p .codex/agents
cp .agents/skills/agent-relay/codex-config/relay-worker.toml .codex/agents/relay-worker.toml

Usage

Use the skill directly

Invoke the skill explicitly:

$agent-relay Coordinate this refactor with two workers and keep all status updates in Relaycast.

Or describe the task naturally and let Codex match the skill from its description.

Spawn relay workers

Once relay-worker.toml is installed, delegate bounded tasks to the relay-worker custom agent and include:

  • the worker relay name
  • the lead relay name
  • the workspace-key source
  • exact task scope
  • completion criteria

Example:

Spawn a relay-worker named api-worker.
Have it check Relaycast, ACK me, update the API route tests only, send STATUS after the first green test run, and send DONE with evidence before exit.

Coordinate a team

Use Relaycast when workers need to message each other directly, not only the lead. Good fits:

  • parallel implementation across separate subsystems
  • lead/worker review loops
  • shared channel updates for longer-running tasks
  • cross-terminal or cross-machine collaboration

Environment variables

Variable Required Default Description
RELAY_API_KEY No "" in the template config Relaycast workspace key
RELAY_BASE_URL No https://cast.agentrelay.com Relaycast API base URL
RELAY_AGENT_TYPE No agent Default Relaycast agent type
RELAY_AGENT_NAME No unset Optional stable relay identity when your workflow wants a fixed name

Plugin structure

codex-relay-skill/
  SKILL.md                    # Codex skill manifest and workflow instructions
  README.md                   # Installation and usage docs
  agents/
    openai.yaml              # Agent Relay MCP dependency metadata
  codex-config/
    config.toml              # Template MCP server config for .codex/config.toml
    relay-worker.toml        # Template custom worker agent for .codex/agents/
  scripts/
    setup.sh                 # Auto-installer (runs on first skill activation)
  hooks/
    hooks.json               # Hook definitions (SessionStart, Stop, UserPromptSubmit)
    session-start.sh         # Auto-connect and state persistence
    stop-inbox.sh            # Block exit while unread messages exist
    prompt-inbox.sh          # Rate-limited inbox polling and context injection

Installed layout in a project typically looks like:

.agents/skills/agent-relay/   # Skill directory Codex scans
.codex/config.toml            # Runtime Agent Relay MCP server + features.codex_hooks
.codex/hooks.json             # Hook wiring (copied from skill)
.codex/agents/relay-worker.toml

Skill manifest

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

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 (relay)
  • agents
    • openai.yaml 224 B
      Loading…
  • codex-config
    • config.toml 358 B
      Loading…
    • relay-worker.toml 1.1 KB
      Loading…
  • hooks
    • hooks.json 887 B
      Loading…
    • prompt-inbox.sh 4.1 KB
      Loading…
    • session-start.sh 7.3 KB
      Loading…
    • stop-inbox.sh 3.9 KB
      Loading…
  • scripts
    • setup.sh 8.8 KB
      Loading…
  • README.md 5.3 KB
    # Codex Relay Skill
    
    Codex-native multi-agent coordination via Relaycast.
    
    ## What it does
    
    This package gives Codex a reusable relay coordination layer so sub-agents can communicate through Relaycast instead of staying limited to parent-only result collection.
    
    It includes:
    
    - a Codex skill that teaches lead and worker messaging protocol
    - an Agent Relay MCP dependency declaration
    - a template Agent Relay MCP config block for `.codex/config.toml`
    - a `relay-worker` custom agent template for `.codex/agents/`
    
    With these pieces installed, Codex can:
    
    - coordinate teams through direct messages, channels, and threads
    - require ACK/DONE signaling from workers
    - let workers send peer-to-peer updates through Relaycast
    - reuse the same relay workflow across project-scoped and user-scoped setups
    
    ## Installation
    
    ```bash
    mkdir -p .agents/skills
    cp -R plugins/codex-relay-skill .agents/skills/agent-relay
    ```
    
    That's it. Everything else is automatic.
    
    On first use, the skill self-installs by running `scripts/setup.sh`, which:
    
    - adds the Agent Relay MCP server to `.codex/config.toml`
    - enables `features.codex_hooks = true`
    - writes `.codex/hooks.json` with SessionStart, UserPromptSubmit, and Stop hooks
    - installs `.codex/agents/relay-worker.toml`
    
    All of this is idempotent — safe to run multiple times, and it merges with existing config rather than overwriting.
    
    For user-wide availability, install to `$HOME/.agents/skills/agent-relay` instead.
    
    ### Optional: join an existing workspace
    
    Set `RELAY_API_KEY` before launching Codex to join a specific Relaycast workspace:
    
    ```bash
    export RELAY_API_KEY="rk_live_your_key_here"
    ```
    
    If unset, a new workspace is auto-created on the first session.
    
    <details>
    <summary>Manual setup (advanced)</summary>
    
    If you prefer to configure everything manually instead of using the auto-installer:
    
    1. Add to `.codex/config.toml`:
    
    ```toml
    features.codex_hooks = true
    
    [mcp_servers.agent-relay]
    command = "npx"
    args = ["-y", "agent-relay", "mcp"]
    env = { RELAY_API_KEY = "", RELAY_BASE_URL = "https://cast.agentrelay.com", RELAY_AGENT_TYPE = "agent" }
    ```
    
    2. Copy hooks config:
    
    ```bash
    cp .agents/skills/agent-relay/hooks/hooks.json .codex/hooks.json
    ```
    
    3. Install the worker agent:
    
    ```bash
    mkdir -p .codex/agents
    cp .agents/skills/agent-relay/codex-config/relay-worker.toml .codex/agents/relay-worker.toml
    ```
    
    </details>
    
    ## Usage
    
    ### Use the skill directly
    
    Invoke the skill explicitly:
    
    ```text
    $agent-relay Coordinate this refactor with two workers and keep all status updates in Relaycast.
    ```
    
    Or describe the task naturally and let Codex match the skill from its description.
    
    ### Spawn relay workers
    
    Once `relay-worker.toml` is installed, delegate bounded tasks to the `relay-worker` custom agent and include:
    
    - the worker relay name
    - the lead relay name
    - the workspace-key source
    - exact task scope
    - completion criteria
    
    Example:
    
    ```text
    Spawn a relay-worker named api-worker.
    Have it check Relaycast, ACK me, update the API route tests only, send STATUS after the first green test run, and send DONE with evidence before exit.
    ```
    
    ### Coordinate a team
    
    Use Relaycast when workers need to message each other directly, not only the lead. Good fits:
    
    - parallel implementation across separate subsystems
    - lead/worker review loops
    - shared channel updates for longer-running tasks
    - cross-terminal or cross-machine collaboration
    
    ## Environment variables
    
    | Variable           | Required | Default                       | Description                                                          |
    | ------------------ | -------- | ----------------------------- | -------------------------------------------------------------------- |
    | `RELAY_API_KEY`    | No       | `""` in the template config   | Relaycast workspace key                                              |
    | `RELAY_BASE_URL`   | No       | `https://cast.agentrelay.com` | Relaycast API base URL                                               |
    | `RELAY_AGENT_TYPE` | No       | `agent`                       | Default Relaycast agent type                                         |
    | `RELAY_AGENT_NAME` | No       | unset                         | Optional stable relay identity when your workflow wants a fixed name |
    
    ## Plugin structure
    
    ```text
    codex-relay-skill/
      SKILL.md                    # Codex skill manifest and workflow instructions
      README.md                   # Installation and usage docs
      agents/
        openai.yaml              # Agent Relay MCP dependency metadata
      codex-config/
        config.toml              # Template MCP server config for .codex/config.toml
        relay-worker.toml        # Template custom worker agent for .codex/agents/
      scripts/
        setup.sh                 # Auto-installer (runs on first skill activation)
      hooks/
        hooks.json               # Hook definitions (SessionStart, Stop, UserPromptSubmit)
        session-start.sh         # Auto-connect and state persistence
        stop-inbox.sh            # Block exit while unread messages exist
        prompt-inbox.sh          # Rate-limited inbox polling and context injection
    ```
    
    Installed layout in a project typically looks like:
    
    ```text
    .agents/skills/agent-relay/   # Skill directory Codex scans
    .codex/config.toml            # Runtime Agent Relay MCP server + features.codex_hooks
    .codex/hooks.json             # Hook wiring (copied from skill)
    .codex/agents/relay-worker.toml
    ```
    
  • SKILL.md 6.8 KB
    ---
    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)
    ```
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.