Running many coding agents at once: worktrees, handoffs, one check per phase

The two parts of a many-agents setup that break quietly: the worktree each session works in, and the handoff file a session leaves for the next one. Setup, traps, cleanup and a template.

I run many Claude Code sessions at the same time, each on one task. The whole system is in How I run thousands of Claude Code sessions: briefs, cards, checks, hooks and costs. This note goes deeper on the two parts that break quietly: the worktree each session works in, and the handoff file a session leaves when it runs out of room.

One worktree per session

Two agents in one folder will overwrite each other's files, switch branches under each other and commit each other's half-done work. A git worktree is a second working folder of the same repository, on its own branch, sharing one .git. It costs no clone and no second download of the history.

Claude Code can make one for you: claude -w fix-login starts the session in a new worktree under .claude/worktrees/fix-login, on a branch named after it. My task opener uses exactly that. Without it, the plain git version is two lines:

git worktree add .worktrees/fix-login -b fix-login origin/main
cd .worktrees/fix-login

That is the easy part. A fresh worktree has the code, but not what makes the code run.

Dependencies are not in the worktree

node_modules is not in git, so a new worktree has none. Running pnpm install in every worktree is slow and fills the disk, and with a symlinked node_modules it can do worse. If the worktree's node_modules is a link to the main checkout's, an install inside the worktree writes through that link, and the main checkout's packages end up pointing into a folder that will be deleted next week. I have a small script that scans the main checkout for exactly that, and a standing rule: sessions never install in a worktree.

So dependencies are linked, not installed. Claude Code has a setting for the top level (worktree.symlinkDirectories with node_modules in it). In a monorepo that is not enough: every package has its own node_modules. On 12.11. sessions in one of my apps started without the app package's folder and had to link it by hand. Now a bootstrap step links the top folder and every packages/*/node_modules the main checkout has.

One trap stays. Those links point into the main checkout, and so do the links pnpm made between your own workspace packages. If a session edits a shared package inside its worktree, the app still imports the main checkout's copy, and the session tests code it did not write. For the repo where that matters, a script gives each package its own node_modules pointing at the worktree's own packages and rebuilds the shared ones when their build is older than the sources. That takes about 25 seconds.

The bootstrap took a median 14.5 seconds and up to 42 seconds at the 90th percentile when I measured it on 07.11. For the two busiest repos, two worktrees now wait ready and bootstrapped, so a new session takes one and starts at once.

The stash is shared

Worktrees share one .git, and the stash lives there. A git stash in one worktree puts the entry on the same list every other worktree sees, and a git stash pop in another session takes the newest entry, which may be yours.

The rule my sessions get: no bare git stash. To set work aside, make a temporary commit. If a stash is unavoidable, push it with a unique message, note its hash, apply it by hash, and drop it by finding that message again.

Cleaning up

Worktrees pile up. On 27.10. one cleanup removed 267 working copies, about 109 GB, and kept 238 that were not provably safe to delete.

"Safe" has a strict meaning here: nothing uncommitted, and the branch's last commit is on the remote. The removal is a plain git worktree remove, never --force, so git itself refuses while anything is unsaved. Two things can still stop it:

  • A worktree that holds a submodule cannot be removed until the submodule is deinitialised.
  • node_modules/ with a trailing slash in .gitignore matches only directories. A linked node_modules is a symlink, so git counts it as an untracked file and refuses. Write node_modules without the slash.

My close script also retries, because another git process can hold .git/config for a moment. Nine close logs show that error.

Here is a small version of the helper, tested on a scratch repo before it went in this note:

wt() {
  local name=${1:?name} base=${2:-main} root dir rel nm
  root=$(git rev-parse --path-format=absolute --git-common-dir) || return
  root=${root%/.git}
  dir="$root/.worktrees/$name"
  git -C "$root" fetch -q origin "$base" || return
  git -C "$root" worktree add -q -b "$name" "$dir" "origin/$base" || return
  git -C "$dir" submodule update -q --init --recursive
  for nm in "$root"/node_modules "$root"/packages/*/node_modules; do
    [ -d "$nm" ] || continue
    rel=${nm#"$root"/}
    [ -e "$dir/$rel" ] || ln -s "$nm" "$dir/$rel"
  done
  cd "$dir" || return
}

wt_done() {
  local dir root
  dir=$(git rev-parse --show-toplevel) || return
  root=$(git rev-parse --path-format=absolute --git-common-dir)
  root=${root%/.git}
  [ "$dir" != "$root" ] || { echo "this is the main checkout"; return 1; }
  [ -n "$(git branch -r --contains HEAD)" ] || { echo "not pushed yet"; return 1; }
  cd "$root" && git worktree remove "$dir"
}

wt fix-login makes the worktree, fills submodules, links dependencies and moves you in. wt_done refuses until the work is pushed, then removes the folder and keeps the branch. Add .worktrees to .gitignore.

The handoff file

Every step of a session re-reads the whole conversation, so a long session gets slow and expensive. My sessions stop at around 150,000 tokens and leave a handoff file for a fresh one. There are 517 of those files on my machine now, a median of 723 words each.

When to write it

My context hook warns at 200,000 tokens. A warning is not a stop: in eight sessions I measured, they ended between 219,000 and 283,000. A session that writes its handoff at that point is in the middle of a step, in a hurry, and forgets the half it has not written down.

So the rule says 150,000: do not start a new step after that, finish the one you are in, push, then write the handoff. A clean handoff at 150,000 is worth more than a cut-off at 200,000.

What goes in it

The crew note lists the three parts: done, learned, next. After a few hundred of these, the ones that work have a little more:

  • Done, with what was pushed.
  • Not verified: what the session could not test and the next check must. Without this line, "done" reads as "works".
  • Facts with file and line, so the next session does not search for them again.
  • Next steps, in order, each small enough to finish.
  • Traps: what cost this session time and will cost the next one the same.
  • Failed checks: how many times which test has failed. That count belongs to the test, not the session. Once an integration check failed 14 times in a row across four sessions, because each one started counting from zero. Now after three failures on the same test, a session stops re-running the check and asks for a reproduction on a test server first.
# Handoff: <task> (<date, time>)

## Done
- <what changed>, pushed on <branch>

## Not verified
- <what the next check must prove>

## Facts
- <fact> (<file>:<line>)

## Next, in order
1. <step>
2. <step>

## Traps
- <what wasted time, and how to avoid it>

## Failed checks
- <test>: failed <n> times, last because <reason>

Why the newest replaces the rest

Each handoff is rewritten from scratch, never appended to. The next session reads only the newest one and trusts its facts. It opens a file again only to edit it.

That rule came from measuring. Before it, eleven follow-up sessions spent 50 to 87 % of their file reading on files the session before them had already read, about 255,000 tokens in all. A session already reads 27,000 to 66,000 tokens of files before it writes anything. A chain of handoffs adds to that, and when two of them disagree, the session has to find out which one is still true.

Now the brief of a follow-up session is the newest handoff plus what changed since, and it ends with the files the last session read and edited, at most 40, so the new one can open the right lines without searching.

One check per phase

Worktrees are what make the batching possible. Each session pushes its own branch and runs only the tests it touched. The branches meet on one integration branch, and one full check runs there for the whole phase. The numbers and what went wrong before that rule are in the crew note.

If you start with two sessions

One worktree each, dependencies linked, never installed. No bare git stash. A handoff file at 150,000 tokens with what is not verified and the traps in it. The rest of the system is built on those.

More posts

All posts →
  1. 21 Nov 2026

    Same agent, rebuilt workspace, a quarter of the bill: what EnvOpt showsA new arXiv paper leaves the model and the harness alone and lets another AI rebuild the workspace the agent works in. On 200 test tasks, the same Claude Haiku 4.5 agent cost $42.36 before and $11.55 after, and passed more tasks.

    AI · 7 min
  2. 21 Nov 2026

    CLAUDE.md vs AGENTS.md: which one Claude Code reads, and why I keep only oneWhen a repository has both files, Claude Code reads CLAUDE.md and leaves AGENTS.md alone unless you import it. I found five of my repositories set up the wrong way round: the real instructions in AGENTS.md, and a CLAUDE.md that only pointed at it.

    How I build · 5 min
  3. 20 Nov 2026

    Running several Claude Code agents at once: worktrees, handoffs and one check per phaseWhat broke when I put many Claude Code agents on the same repositories, and the four rules that stayed: one worktree per agent, small file-disjoint jobs, a rewritten handoff, and one full check per phase.

    How I build · 5 min