Agent Relay

Multi-agent race

When you don't know which agent is going to solve a task best — or when you want a second opinion before committing — run two or more agents in parallel against the same prompt and merge the result you trust most. Agent Relay handles the messy parts: isolated worktrees, conflict detection, and conflict-aware routing back to your branch.

This is a narrative walkthrough. For the underlying command, see agent-relay run.

What you'll end up with

your-repo/                       # untouched until you accept a result
  .agent-relay/
    sessions/
      01J9X3M7K5...              # claude-code's attempt (worktree A)
      01J9X9N7Q2...              # codex's attempt    (worktree B)
    worktrees/
      claude-code-01J9X3M7K5/    # isolated working tree, claude-code's changes
      codex-01J9X9N7Q2/          # isolated working tree, codex's changes
    race/
      01J9XAEYR3.../             # race manifest + conflict report

Two agents, two sessions, two worktrees — your main checkout never moves until you pick a winner.

Setup

  1. Be on a clean branch

    Race expects no uncommitted changes in the working tree. Commit, stash, or stage everything first.

    terminal
    git status

  2. Make sure both agents are discoverable

    terminal
    agent-relay discover

    You need at least two ready adapters. If only one shows up, install the other before continuing.

  3. Start the race

    terminal
    agent-relay race c x "Add a feature flag for the new auth flow"

    Agent Relay creates one git worktree per agent, kicks off both sessions, and writes a race manifest under .agent-relay/race/<race-id>/. Both runs are completely isolated — they can't see each other's working trees, and your main checkout is never modified.

  4. Watch both in real time (optional)

    Open two more shells. From the first:

    terminal
    agent-relay watch --session <claude-session-id>

    From the second:

    terminal
    agent-relay watch --session <codex-session-id>

    Both watchers stream the live event log from disk.

  5. Pick the winner

    When at least one session finishes, Agent Relay generates a conflict report — which files each agent touched, where their changes overlap, and whether the overlapping regions agree byte-for-byte.

    terminal
    agent-relay race accept <agent-alias>

    The accepted worktree's changes get merged into your main checkout. Anything outside the agent's stated touched-file list is left alone even if the worktree drifted (defense against runaway tool use).

Conflict-aware routing

Race doesn't just diff the two trees and call it a day. Each session's resume.json lists the files the agent believed it was touching, and Agent Relay only routes work that:

  1. Appears in the accepted agent's touched_files list. Drifted changes outside the stated scope stay in the worktree.
  2. Doesn't conflict with the loser's accepted work (in chained races, where you accept some files from one agent and some from another).

The result is a merge that reflects what each agent said it was doing, not whatever they actually wrote to disk in a moment of confusion.

Cleanup

Race state is held in .agent-relay/race/<id>/ and .agent-relay/worktrees/<agent-id>/. To remove finished races:

terminal
agent-relay race prune

By default prune removes only races where every session is in completed or abandoned state — active and checkpointed races are preserved.

Next

Resuming a session

Pick up an old session manually, even after a crash or a long gap.

Handoffs

The packet format that makes conflict-aware routing possible.