Race three agents on one task

Give one hard task to three workers at once, each in its own worktree, compare what they did and keep the best one.

Goal. A bug or a design question without one obvious answer goes to three agents at the same time. You compare their changes side by side and merge the one you like; the other two go away.

You need

A git repository, or from st 0.3.107 any folder (st snapshots one without git; see Tasks). Each worker gets a worktree and a branch of its own, from the commit your checkout is on.
st 0.3.84 or later, with st hooks install and st plugin install done.
Claude Code (and Codex, to mix them) in a pane of a session st shares.

1. Write the task

One file every worker can work from alone. Say what is wrong, what may change, and how to tell it is fixed.

# Fix the flaky login test
 
`go test ./internal/auth -run TestLogin -count 20` fails about one run in five.
Find why and fix the cause, not the test. Change only internal/auth.
Done when the command above passes 20 times out of 20. Commit on your branch.

The first line names the workers (fix-the-flaky-login-1, -2, -3), unless --name gives a shorter base.

2. Ask the coordinator

/sophonz:orchestrate Race three workers on fix.md, Claude and Codex mixed.
When all three are done, show me what each changed. Don't pick yet.

It runs:

st worker start --fan 3 --agent claude,codex --task fix.md
st worker wait --timeout 30m
st worker fan

--fan takes 2 to 8 workers. A list in --agent is used in turn, so three workers are Claude, Codex, Claude.

Three new windows open in the coordinator's session, one per worker. They show in the desktop app's agent graph and sidebar under the coordinator, and in the phone app's window list, like any other agent: open one to see it work or to type into it.

4. Compare

st worker fan lists the fan's workers side by side:

  fix-the-flaky-login
    %15   claude   done    2 files changed, 14 insertions(+), 3 deletions(-)
          Guarded the token cache with a mutex; 20/20 passes
    %16   codex    done    1 file changed, 6 insertions(+), 2 deletions(-)
          Fixed the clock in the test fixture; 20/20 passes
    %17   claude   working no changes

(+ not committed) after a line means that worker left changes it did not commit.

To read the diffs on screen:

Desktop app (0.1.30 or later). Pick a worker's card in the agent graph and click Changes · fan …. Its diff and the fan's other workers show side by side.
Web terminal (st 0.3.84 or later). Click the Δ on the worker's window row in the sidebar.

5. Pick one

Click Use this one in that view, or tell the coordinator "pick %16", which runs:

st worker pick %16

st merges that worker's branch into your checkout, closes the other workers' windows and removes their worktrees and branches.

Changes not committed are refused. Ask the worker to commit, or pick with --commit.
A conflict merges nothing and removes nothing. Send the worker something like "merge main into your branch, resolve the conflicts, commit", then pick again.
--keep merges and leaves the other workers as they are.

6. Finish

The worker you picked keeps its window and its worktree. Once you are happy with the merge:

st worker stop %16 --yes   # close its window
st worker clean %16        # remove its worktree and branch

More on fans and worktrees: Workers and Tasks, ownership and worktrees.