All pages

Many agents at once · Lesson 1.2 · 10 min

Race and pick

Give one task to several agents and keep the best result.

After this lesson you know when it pays to give one task to several agents at once, how to write a prompt that makes their attempts comparable, and how to read the results and keep one.

Time: 10 minutes · Works on: macOS app. Any MCP client connected to TRMNLY on a Mac can call the race_* tools.

Why run the same task more than once

An agent's first attempt is one sample. For a task with one obvious answer, one sample is enough. For a task with several defensible answers, the first attempt is mostly a coin toss, and you only learn what the alternatives looked like by asking again.

A race asks several agents at once, each in its own worktree. Instead of arguing about which approach to try first, you read three finished attempts and keep the best. Reading is faster than retrying one at a time, and seeing the alternatives side by side often shows you what you actually wanted.

When a race is worth it

Race when the answer is uncertain and reading is cheap:

  • Design choices. "Add caching to the search endpoint." In-memory, on disk, or HTTP headers? Three entrants will likely pick differently.
  • A bug with an unclear cause. Each entrant may chase a different hypothesis. The one with a failing test that now passes wins.
  • A refactor where taste matters. You'll know the cleanest version when you see it, and not before.

Don't race when the task is well specified. "Rename userId to accountId across the API" has one right answer, and a race only pays for it three times. Don't race large tasks either. Every entrant's diff has to be read, and three 2,000-line diffs aren't a comparison you'll do well.

Write a prompt that makes attempts comparable

Every entrant gets the same prompt and nothing else. No conversation history, nobody to ask. So the prompt has to be a complete brief (see Write a task brief), plus two things that matter more in a race:

  • One way to judge. Name the test, the command or the behavior that decides which attempt is better. "The fastest correct answer to npm test -- search" is something you can check. "The nicest" isn't.
  • Room to differ, inside fences. Say what is fixed (the public API, the files out of bounds) and leave the approach open. If you specify the approach, you've written one answer three times.

A worked prompt:

The /search endpoint takes 900 ms on the fixture in tests/fixtures/big.json.
Make it faster without changing its response shape.
Done when: npm test -- search passes and the timing test in
tests/search.perf.test.ts reports under 200 ms.
Don't touch src/api/routes.ts or add a dependency.
Commit your work with a message that names your approach.

Read the attempts, then pick

When the entrants finish, you have a summary from each and a branch from each. They aren't the same thing. The summary is what the agent says it did; the branch is what it did. Read in this order:

  1. The shape. The size of each change. An attempt five times larger than the others either found something the others missed or wandered off.
  2. The check. Run the test that decides the race in each entrant's checkout. An attempt that doesn't pass it is out, however good its summary sounds.
  3. The diff. Read the survivors. Pick the one you'd rather maintain.

You can hand step 3 to a panel of models first (see Judges and second opinions), but the pick is yours.

Picking keeps a branch. It doesn't merge it. The winner still goes through review like any other branch.

Do it in TRMNLY

There's no race button. You start a race by asking an agent: the sidebar agent, or Claude Code connected to TRMNLY over MCP. The agent calls race_start, race_status and race_pick.

  1. Check the budget first. A race's ceiling defaults to the Budget in the Fleet strip under the Tasks tab's header (open Tasks from More ▾ and click the strip to expand it). The ceiling is also clamped to what that amount has left after today's agent spending. If today's spending has used it up, the race is refused before it starts. Entrants use the token source picked in the same strip, such as CLI harness (subscription) or Project default.
  2. Start the race. Select the project, open the Agent tab and ask: "Race 3 agents on this prompt:" followed by your prompt. An approval card for Race agents on a prompt appears, because a race is several agents running at once, each approving its own file writes. Approve it. You can pass 2 to 5 entrants, and a different base branch. Without one, entrants branch from the repository's default branch.
  3. Read the reply. It states the race's ceiling and each entrant's share, and the race stops itself when spending reaches the ceiling. Entrants are labelled a, b, c. Letters, so they're never confused with card numbers like #3.
  4. See the worktrees. Click the worktree selector. Each entrant has its own worktree on a branch named race/<id>-a, race/<id>-b and so on. Your sidebar stays on the worktree you were in. TRMNLY doesn't switch you into an entrant's checkout as it creates them.
  5. Watch progress. Ask "What's the race status?" The agent calls race_status (no approval needed), which lists each entrant's state (preparing, running, finished or failed), its branch, its change size as +added/-removed, how long it ran, its summary once finished, and what the race has spent against its ceiling. An entrant still running after 30 minutes is given up on and marked failed.
  6. Check each attempt. Switch to an entrant's worktree with the selector, open a tab and run the deciding test there. Or ask the agent to run git_diff in each entrant's folder and compare what each branch did with what its summary claims. Once the race has finished, race_status points you at judge_panel for the comparison.
  7. Keep one. Ask "Keep entrant b." The agent calls race_pick, with an approval card titled Keep one race entrant, because it removes the other worktrees. A worktree with uncommitted changes is never removed. The reply names any it left in place, and you can remove those with worktree_remove once you've looked. Picking while entrants are still running stops the race.
  8. Land the winner. Switch to the kept worktree, click the selector and choose Open PR…. Nothing was merged and no Tasks card was touched by the race. What happens to the winner is your decision.

One race runs per project at a time. A second race_start is refused until the first has finished or been picked.

Check yourself

  • You can name one task in your current project worth racing and one that isn't, and say why.
  • Your race prompt names the check that decides the winner.
  • race_status showed each entrant's branch and change size.
  • You ran the deciding test in at least two entrants' worktrees before picking.
  • After race_pick, only the winner's worktree was left, and it was not merged.

Go further