Skip to content
#

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.

Each agent's branch is checked before it merges into main main agent/gift-cards its own worktree check 31 no problems agent/address-edit its own worktree check 32 1 problem found back to its agent, not into main agent/search its own worktree check 33 no problems runstory run main.. merge merge

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

  1. Set up the repository once, on main. Then commit what runstory init leaves for Git: .runstory/runstory.yml, the section it adds to AGENTS.md, and one line in CLAUDE.md if you have that file. Every worktree then has them.

    runstory init
    runstory setup
    
  2. Give each agent a worktree and a branch. Claude Code's hook works in every worktree. For Codex or Cursor, run runstory init --automatic off in each new worktree, so the agent there has its hook.

    git worktree add ../store-gift-cards -b agent/gift-cards
    
  3. When an agent finishes, check its branch from inside its worktree. main.. means every commit on this branch that main doesn't have.

    cd ../store-gift-cards
    runstory run main..
    
  4. 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.

BranchThe checkWhat happens next
agent/gift-cardsNo confirmed problemsIt merges into main
agent/address-edit1 problem foundIts agent fixes it, and the retest passes
agent/searchNo confirmed problemsIt 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.

ToDo this
Check a branch with 1 model, for 3 creditsrunstory run main.. --providers anthropic
See what a check would cover firstrunstory run main.. --dry-run
Cap the project's checks at 30 credits a dayrunstory 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.