Run several agents at once
Give each coding agent its own branch and worktree, and check each branch as one change before it merges into main.
Where the check fits
You run several coding agents side by side, each in its own Git worktree on its own branch. But a new worktree is a fresh checkout with no installed dependencies, and two copies of your app fight over one port. Starting the app in every worktree is slow, so it often gets skipped, and broken branches reach main.
RunStory builds each branch in a sandbox of its own. No worktree has to run the app, and the check needs no push and no pull request.
Three agents, each on its own branch in its own worktree. Each branch is checked as one change, measured from where it left main. Two pass and merge. The third goes back to its agent.
Set it up
-
Set up the repository once, on
main. Then commit whatrunstory initleaves for Git:.runstory/runstory.yml, the section it adds toAGENTS.md, and one line inCLAUDE.mdif you have that file. Every worktree then has them.runstory init runstory setup -
Give each agent a worktree and a branch. Claude Code's hook works in every worktree. For Codex or Cursor, run
runstory init --automatic offin each new worktree, so the agent there has its hook.git worktree add ../store-gift-cards -b agent/gift-cards -
When an agent finishes, check its branch from inside its worktree.
main..means every commit on this branch thatmaindoesn't have.cd ../store-gift-cards runstory run main.. -
Merge the branches whose check found nothing.
Start each check inside the branch's own worktree. The result lands there, so the agent working there gets the findings at the end of its turn.
A worktree starts without the files Git ignores. If your checks use secret values, copy .runstory/env into each new worktree.
Let each agent ask for its own check
Your coding agents start a check only when you ask. So ask in the task you give each one.
Ask each agent
Add gift cards to checkout on this branch. When you're done, run one RunStory check (runstory run main..), then fix what it finds.
Gate the merge in a script
A lead agent or a script can hold the merge until the check passes. With --wait, the command exits 0 when the check finds no confirmed problems, and 1 when it confirms a new one.
cd ../store-gift-cards
if runstory run main.. --wait --timeout 75m; then
git -C ../store merge agent/gift-cards
fi
Check the branches together
Two branches can each pass and still break each other. After the merges, run one more check over all of them.
before=$(git rev-parse main) # note this before the first merge
# ...merge each branch that passed...
runstory run "$before..main"
Example: three agents, one afternoon
A developer at Acme, an online furniture store, gives three tasks to three coding agents, each in its own worktree.
| Branch | The check | What happens next |
|---|---|---|
agent/gift-cards | No confirmed problems | It merges into main |
agent/address-edit | 1 problem found | Its agent fixes it, and the retest passes |
agent/search | No confirmed problems | It merges into main |
A dry run in the first worktree shows what its check covers:
$ runstory run main.. --dry-run
Checking main.., 2 commits from main (3844d4b) to agent/gift-cards (9fc8ca8), with 4 files changed
On agent/address-edit, the cart empties when the delivery address changes. The agent in that worktree gets the finding at the end of its turn, fixes the code, and runs the retest. It passes 3 times, so that branch merges too. One last check of main covers the three merges together.
What it costs
A default check uses 2 frontier models and costs 6 credits.
| To | Do this |
|---|---|
| Check a branch with 1 model, for 3 credits | runstory run main.. --providers anthropic |
| See what a check would cover first | runstory run main.. --dry-run |
| Cap the project's checks at 30 credits a day | runstory settings --daily-limit 30 |
Checks from every worktree count against one daily limit. Your plan sets how many run at once, and a check over that number waits for a free slot. If two worktrees start the same check of the same commit, they share one check.