Running Parallel AI Agents on One Codebase

The idea sounds simple: run multiple AI coding agents at the same time to ship features faster. In practice, it is a coordination problem.

We have been running 3-5 parallel Claude Code agents on the Fazm codebase. Here is what works and what does not.

The One Rule: No File Overlap

If two agents edit the same file, you get merge conflicts, lost changes, and wasted context window re-reading the file to figure out what the other agent changed. It is not worth it.

The rule is simple: each agent owns a set of files. No sharing. If Agent A needs to change a file that Agent B is working on, one of them waits.

This works naturally when your architecture has clean module boundaries. The UI agent works on SwiftUI views. The pipeline agent works on the async capture chain. The API agent works on LLM integration. Their file sets rarely overlap. Having detailed CLAUDE.md files helps each agent understand module boundaries - we cover this in the HANDOFF.md pattern.

tmux for Session Management

Each agent runs in a named tmux session: fazm-refactor, fazm-pipeline, fazm-tests. tmux ls gives a quick overview of everything running. You can attach and detach without losing context.

The alternative - five terminal tabs - becomes unmanageable fast. You lose track of which agent is doing what, and accidentally closing a tab kills the session.

Git Branch Isolation

Each agent works on its own git branch. This prevents the most common disaster: Agent A commits a half-done change, Agent B pulls it, Agent B's build breaks, Agent B spends 10 minutes debugging someone else's work-in-progress.

When an agent finishes, you review its branch and merge. Clean, predictable, reversible.

What Does Not Work

• Shared state files. If two agents both need to update a configuration file or a shared types file, you need to serialize that access manually.
• "Just figure it out" coordination. Agents do not communicate with each other. You are the coordinator. If you do not explicitly assign scopes, they will collide. We learned this the hard way while building Fazm with Claude.
• Too many agents. Past 5 concurrent agents, the coordination overhead exceeds the parallelism benefit. 3 is the sweet spot for most projects. The Swift ScreenCaptureKit pipeline was a perfect example - we split the work between UI, capture, and accessibility agents.

---

Based on our experience building Fazm. Discussed in r/AI_Agents.