What Actually Happens When 12 Agents Work on the Same Branch
What Actually Happens When 12 Agents Work on the Same Branch
The theory sounds great - spin up a dozen agents, each working on a different feature, all committing to the same branch. Ship a week of work in an afternoon. Here is what actually happens.
The Build Collision Problem
Agent 3 modifies a shared utility file. Agent 7 is mid-build. The build fails because the file changed under it. Agent 7 sees the error, tries to "fix" it by reverting Agent 3's changes. Agent 3 notices its changes disappeared and rewrites them. This loop can continue for hours.
Never Let Agents Build Simultaneously
The single most important rule we learned - never let two agents run builds at the same time. A terminal manager that queues build commands prevents the collision loop entirely. Each agent can edit files freely, but when it is time to compile or test, they wait in line.
File Lock Conventions
Without explicit file locking, agents will edit the same file simultaneously. We use a simple convention in CLAUDE.md - each agent declares which files it owns. If Agent A is working on auth.swift, no other agent touches that file until Agent A commits.
What Works at Scale
After months of running 8-12 parallel agents daily:
- Git worktrees eliminate most conflicts by giving each agent its own working directory
- A shared terminal manager prevents build collisions
- CLAUDE.md serves as the coordination layer - agents read it before starting work
- Agents should never try to fix errors in files they did not create
- Merging happens manually, not automatically
The Real Limit
The bottleneck is not compute or API costs. It is coordination overhead. Past 6-8 agents, the time you spend managing conflicts exceeds the time you save from parallelism. The sweet spot for most projects is 3-5 agents with clear boundaries.
Fazm is an open source macOS AI agent. Open source on GitHub.