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.

Inside the interactive relay shell, run /race to start this flow. This page is a narrative walkthrough of the same workflow using the scriptable agent-relay race command, so it also fits scripts and CI.

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. 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. 2

   Make sure both agents are discoverable

   In the relay shell, list the adapters Relay can find:

   text

   /discover

   You need at least two ready adapters. If only one shows up, install the other before continuing. From a script, agent-relay discover does the same.

3. 3

   Start the race

   In the interactive relay shell:

   text

   /race c x "Add a feature flag for the new auth flow"

   Or, from a script or CI, the scriptable equivalent:

   >_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. 4

   Watch both in real time (optional)

   From the relay shell, tail either side with /watch <session-id>. From separate shells, the scriptable form does the same. The first:

   >_terminal

   agent-relay watch <claude-session-id>

   The second:

   >_terminal

   agent-relay watch <codex-session-id>

   Both watchers stream the live event log from disk.

5. 5

   Inspect or resolve conflicts

   When the race finishes cleanly, Relay can merge non-conflicting in-scope work back to your main checkout. If it ends in manual_resolution_required, inspect the saved conflict artifacts first from the relay shell:

   text

   /inspect-conflicts <session-id>

   Then continue the resolution workflow:

   text

   /resolve <session-id>

   Both have scriptable equivalents — agent-relay inspect-conflicts and agent-relay resolve — for CI and automation.

Conflict-aware routing

Race doesn't just diff the two trees and call it a day. Each session's saved turn state lists the files the agent believed it was touching. Relay uses that state when reviewing and merging race results:

1. Drifted changes outside an agent's stated scope are treated conservatively.
2. Overlapping edits are saved as conflict artifacts instead of being silently guessed.
3. Human judgment stays in the loop when automatic resolution is not safe.

The result is a workflow that reflects what each agent said it was doing, not only whatever files it happened to write.

Continuing a race

If a race ends because it hit max_time, was interrupted, stayed incomplete, or one agent errored, continue the broader task from the relay shell:

/race --continue <session-id> c x "Continue the task"

On macOS, Relay can open terminal windows or tabs for the tmux-backed race:

/race --open-terminals c x "Build the auth module"

Use --no-open-terminals to suppress that behavior explicitly. The scriptable agent-relay race form takes the same flags for CI and automation.

Next