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:
- The shape. The size of each change. An attempt five times larger than the others either found something the others missed or wandered off.
- 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.
- 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.
- 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.
- 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.
- 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. - See the worktrees. Click the worktree selector. Each entrant has its own
worktree on a branch named
race/<id>-a,race/<id>-band 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. - Watch progress. Ask "What's the race status?" The agent calls
race_status(no approval needed), which lists each entrant's state (preparing,running,finishedorfailed), 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. - 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_diffin each entrant's folder and compare what each branch did with what its summary claims. Once the race has finished,race_statuspoints you atjudge_panelfor the comparison. - 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 withworktree_removeonce you've looked. Picking while entrants are still running stops the race. - 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_statusshowed 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
- Fleet reference — the
race_*tools, entrant limits and budget rules - One worktree per agent — why each entrant gets its own checkout
- Judges and second opinions — score the attempts before you read them all
- Review the diff — read the winner the way you'd read anyone's
- Fleet — where the race budget is set