How to Run Five Claude Code Agents on One Repo Without Merge Conflicts

Running one Claude Code agent is easy. Running five on the same repository is where teams get burned. The usual outcome is two agents that finish their tasks, two branches that merge cleanly, and a main branch that no longer builds, because Git merged text and nobody checked meaning. This post is the setup that avoids that, using Nool 7.0 on top of an ordinary Git repository. Every command below is real; run nool <command> --help for the full flags.

The three collisions you are actually avoiding

Working-tree collisions: two agents editing the same checkout overwrite each other, and the loser finds out when its build breaks. Git worktrees fix this one.

Scope collisions: two agents in separate worktrees both change the same function, or both reach into the same module from different callers. Worktrees do not fix this; the branches merge and the result is wrong.

Semantic collisions: two agents make changes that are each fine alone and incompatible together, such as one renaming a field and the other adding a caller that uses the old name. Text merge cannot see this at all.

You need isolation for the first, leases for the second, and a semantic check for the third.

Step 1: Onboard the repository

curl -fsSL https://www.nool.dev/nool-install.sh | bash
cd your-repo
nool init --from-git main
nool discover features
nool status --compact

nool init builds the ledger alongside your Git history without changing it. nool discover features maps the architecture into the entity graph the rest of the commands read. Git stays the storage layer.

Step 2: Give each agent its own room and its own lock

Each Claude Code agent gets a try branch with an isolated worktree and an atomic lease on the paths it will touch:

nool try new api-rate-limit  --worktree --nodes src/api/     --intent "Add rate limiting to the public API"
nool try new billing-retries --worktree --nodes src/billing/ --intent "Bounded retries for webhook delivery"
nool try new search-index    --worktree --nodes src/search/  --intent "Rebuild the search index incrementally"
nool try new docs-refresh    --worktree --nodes docs/        --intent "Refresh the install and quickstart docs"
nool try new ci-selection    --worktree --nodes .github/     --intent "Use impact-scoped test selection in CI"

Each branch is checked out under .nool/try/<name>/. If another agent already holds a lease over the paths you asked for, the command exits with code 3 before it writes anything; that is the second collision, prevented at the door rather than discovered at merge. Leases carry a fencing number assigned when they are granted and checked again when the work is sealed, so an expired or superseded lease cannot land work even if it looked valid when the agent started.

Start each Claude Code session inside its worktree. If you use the Nool MCP server, Claude Code can announce, propose and read context itself; from a plain terminal the commands are the same.

flowchart LR
  A[nool try new --worktree --nodes] --> B[Claude Code works in .nool/try/name]
  B --> C[nool propose --intent]
  C --> D{Envelope and gates}
  D -- pass --> E[nool try promote: 3-way merge]
  D -- fail --> F[Narrow the change or justify it]
  E --> G[main]

Step 3: Let each agent propose under its intent

Inside its worktree, an agent lands work the same way a single agent would:

nool propose --all --intent "Add rate limiting to the public API" --fast
nool solidify --fast --compact

The proposal is checked against the intent the branch declared. If the agent reached outside its envelope, into files or symbols the intent did not cover, the proposal is refused unless it carries a --justification, and the justification is recorded on the knot. For changes that cross an architectural boundary, use --full: it validates against the AST, and in the coordination benchmark it blocked both real contract breaks in the workload with zero false alarms.

Step 4: Check for semantic conflicts before anyone merges

nool announce status
nool discover conflicts src/api/ src/billing/ src/search/

announce status shows who holds what, with fencing numbers. discover conflicts reports overlapping intent between branches before either lands. This is the third collision, caught while both changes are still cheap to adjust.

Step 5: Promote one branch at a time

nool try promote api-rate-limit
nool try promote billing-retries

try promote computes what main changed since the branch's recorded base and three-way merges it path by path. If two agents genuinely changed the same symbol, promote stops with diff3 conflict markers in the worktree and a non-zero exit code instead of guessing. Same-symbol concurrency serializes by design; everything else converges.

If a branch has fallen behind, nool try rebase <name> merges main's drift into the worktree first without sealing anything.

Step 6: Or let Nool plan the waves

Five hand-typed try new commands are fine for five agents. For a task list, plan instead:

nool fleet advise --task api=src/api/ --task billing=src/billing/ --task search=src/search/ --task docs=docs/ --task ci=.github/
nool fleet plan --task api=src/api/ --task billing=src/billing/ --task search=src/search/ --task docs=docs/ --task ci=.github/ --width 5
nool fleet plan --task api=src/api/ --task billing=src/billing/ --width 5 --run <builder-spec> --isolation worktree

fleet advise recommends single, parallel or quorum from measurable signals before you spend anything. fleet plan partitions the tasks into waves whose node sets are disjoint, so agents in the same wave cannot collide by construction, and with --run executes each task under its own branch, agent id and lease.

What it costs

The independent coordination benchmark ran nine coordination arms over an identical 38-task workload for ten seeds. On its bare path Nool landed 709.4 valid tasks per hour against 624.4 for git worktrees, with 77 child processes spawned instead of 441 and average stall halved. With full semantic governance on, throughput was 632.2, a statistical tie with git worktrees at p = 0.35. The benchmark's own caveats apply: synthetic agents, timings that vary with machine load, and a lease protocol that at the time of the run predated 7.0's fenced leases. Read the full page, including what it does not establish, at /research/coordination-benchmark.

Across machines

Agents on different machines get the same fenced leases through a nool-hub-server, which grants atomic, expiring leases over an authenticated API with OIDC principals and org and repo access control. Teams that do not want a server get leases replicated as commit-backed refs that only accept compare-and-swap writes.

The short version

Give every agent a worktree and a lease with nool try new --worktree --nodes. Propose under the declared intent, with --full on anything that crosses a boundary. Run discover conflicts before promoting. Promote one branch at a time and let diff3 markers tell you when two agents really did touch the same symbol. For more than a handful of agents, fleet plan does the partitioning for you. The multi-agent coding page goes deeper on each step, and the Claude Code guide covers the session setup.