Running several Claude Code agents at once: worktrees, handoffs and one check per phase

What 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.

For a while I ran one Claude Code session at a time. Now several run at once, each on its own job, across a handful of repositories. Parallel agents are not hard to start. The hard part is that they share things nobody thought of as shared: a working folder, a stash list, a test cluster, and your usage limit. Every rule below exists because one of those shared things bit me.

If you are looking for how the crew is set up in general, that is in my AI agent crew write-up. This post is only about running them side by side.

One agent, one worktree

A git worktree is a second working folder of the same repository, on its own branch. Two sessions in two worktrees cannot overwrite each other's files, and they still share one history.

The rule in my global CLAUDE.md is that an agent never edits the main checkout. Before its first edit it moves into its own worktree. Telling it once was not enough, so two hooks back the sentence:

  • A hook on session start restates the rule and names the current branch.
  • A hook that runs before every command blocks a push to the main branch. The agent can only push a feature branch and open a pull request.

The sentence says what I want. The hook makes the wrong way fail.

The shared things I did not expect

The stash list is shared. All worktrees of one repository see the same stash stack. A bare git stash pop in one session can pop the entry another session pushed a minute earlier. The rule now says: never a bare stash. Set work aside with a temporary commit, or tag the stash entry and apply it by its hash.

A new worktree is not a full copy. On 18 October I found that git worktree add leaves submodule folders empty. A test run uploaded that tree as it was and died on the missing files. The fix was a short snapshot recipe (add the worktree, then update the submodules) and a check that refuses to start a run from a tree with empty submodule folders.

Installing packages in a worktree. Mine are told never to run pnpm install inside a worktree; a bootstrap script links the existing node_modules instead, and an install problem goes to the coordinating agent rather than being fixed locally.

Removing a worktree. A closed agent's worktree should disappear, but only if nothing is lost. From 4 November a cleanup script removes it with a plain git worktree remove, never with --force, and only when the working tree is clean and the branch is on the remote. Git itself then refuses when something is unsaved. Worktrees with submodules need an extra step before git agrees to remove them.

Jobs that do not touch the same files

On 5 October I wrote down the rule I still use: several agents on one repository are fine when each has its own worktree and branch and they touch different files. If two jobs need the same files, the second waits for the first. Everything merges in one batch, so a conflict shows up once, in one place, rather than as a surprise in the middle of a job.

Handoffs: rewrite, never append

A long job does not fit in one session. Past roughly 150,000 tokens of context, each step costs more because the whole conversation is read again. My agents do not start a new step there. They finish the one they are in, push, and write a handoff for the next session.

The first handoffs were notes that grew with each session. When I measured eleven successor sessions, they had spent 50 to 87 percent of their file reading on files the previous session had already read, around 255,000 tokens in all. Now:

  • A handoff replaces all earlier ones. It is written to stand alone: decisions, facts with file and line number, the next steps in order.
  • The next session reads the newest handoff only, trusts the facts in it, and opens a file again only to edit it.

The context of the previous session is the most expensive thing you can throw away, so the handoff has to carry it.

One full check per phase

All my projects share two small test clusters. In September I set a rule: one full check per phase, not one per task. It was tightened on 23 October and again on 7 November:

  • While working, an agent runs only the test files it added or changed, on my own machine.
  • The full check runs once, on the branch that collects the work of several agents.
  • After a failed check, the agent reads the whole log and fixes every failure before sending it again. Never resubmit an unchanged tree.

On 11 November the reason became clear. One browser test had failed 14 times across four agents, and each run showed only the next broken step. The fix was a loop stop: after three failed checks on the same test, the agents stop sending the full check and hand the failing scenario to a tester agent that reproduces it on a server that stays up. The full check is sent once at the end.

A waiting agent also costs something. An agent that polls a build in its window burns context for nothing, so mine are told to park: when one has sent a check, it records what it waits on and its session ends. It is woken with the result. I wrote about what a long session costs in What Claude Code really costs.

What I would do in your place

  1. Make isolation a hook, not a sentence. Block pushes to the main branch and remind each session of its worktree on start.
  2. Say which things are shared. List them in CLAUDE.md: the stash, the test cluster, the usage limit. Each agent only sees its own session.
  3. Rewrite the handoff. One file, replaced each time, with facts and file lines.
  4. Cap the expensive checks. Run the changed tests locally, the full suite once per phase, and stop retrying a test after three failures.
  5. Date every rule. A date and a reason next to each rule tells you later which ones failed and need a hook. More in My CLAUDE.md, and the failure behind each rule.

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

    Your agent finished the task. Did every step work? What prefix executability showsA new arXiv paper replays every tool call an agent made and marks the first one that could not run. On 200 function-calling tasks, one agent finished 94 % of them, yet only 47 % of its runs ran clean from start to end.

    AI · 5 min