How we plan to run many Claude Code agents without collisions

Parallelism is where agents can outpace a manual migration, and also where things can go wrong quickly. One agent migrating one module is a manageable unit of work. Ten agents working on the same repository at the same time can overwrite each other’s files, break each other’s builds and produce a review queue nobody can keep up with. Our design gives each agent its own git worktree, a plan scoped to a single module and a strict list of allowed tools.

One worktree per agent

A git worktree is a separate working directory attached to the same repository, checked out on its own branch. Each agent works in its own worktree, so its edits, build outputs and test runs never touch another agent’s files. When it finishes, its branch becomes a pull request.

git worktree add -b migrate/loan-interest ../wt/loan-interest
git worktree add -b migrate/fee-calc ../wt/fee-calc

Worktrees are cheap to create and remove, and they share the repository’s object store, so they do not multiply disk usage the way full clones do.

One module per plan

Isolation on disk is not enough if two agents change the same logical code. The Atlas assigns each agent a single module, chosen so that concurrent modules do not share files. Shared code, such as common copybooks or utility classes, is migrated first and on its own, before parallel work starts on the modules that depend on it.

Boundaries enforced by hooks

Claude Code supports hooks that run before a tool is used. We use them to reject edits outside the module’s directory, new dependencies that are not on an approved list and anything that looks like a secret. The agent sees the rejection and adjusts, so routine mistakes do not need a human, while real decisions still do.

Headless runs

Each agent runs Claude Code in headless mode, started by our orchestrator with the task, the allowed tools and a structured output format:

claude -p "Migrate the fee-calc module to Java 21. Keep every golden-master test green." \
  --allowedTools "Read,Edit,Bash(mvn -q test:*)" \
  --output-format json

The JSON output gives the orchestrator a machine-readable result to record and act on.

Shared resources

Builds and tests can collide even in separate directories. Two test suites that bind the same port or write to the same database schema will fail in confusing ways. Each worktree gets its own ports, temporary directories and test database schema, derived from its name, so runs are reproducible and do not interfere.

Throttling the review queue

The real bottleneck in a parallel migration is people. If agents open pull requests faster than engineers can review them, quality drops. The orchestrator will limit the number of open agent pull requests per team and pause new work until reviews catch up. Agents waiting for review cost nothing; rushed reviews cost a lot.

Merge order

Pull requests are merged in dependency order from the Atlas. After each merge, the remaining branches are rebased and their golden-master suites are run again before they return to review. A conflict means the module boundaries were wrong, and that is something we want to learn from rather than paper over.

This is the third phase of our roadmap. We expect to refine it substantially with design partners before it runs on real codebases.