Claude Code Subagents in Parallel - Safety Lessons from Real Codebases
When Parallel AI Agents Collide
The stat that "1 in 4 AI outputs has something wrong" sounds abstract until you experience it with five agents running simultaneously on your macOS app. Two of them editing the same Swift file, producing conflicting changes that both look correct individually but break everything when merged.
The Real Problem
Parallel AI agents don't coordinate. Each agent operates in its own context window with no awareness of what other agents are doing. Agent A refactors a function signature while Agent B adds a new call to the old signature. Both produce valid code. The merge produces a build failure.
This isn't a theoretical concern - it happens constantly when you scale past two or three agents on any non-trivial codebase.
Isolation Is Non-Negotiable
Git worktrees are the minimum viable solution. Each agent gets its own working directory with git worktree add. They share git history but can't step on each other's files. The merge conflicts still happen, but they happen at merge time where you can resolve them intentionally, not silently in the middle of an agent's work.
File-Level Locking
Beyond worktrees, you need conventions about which agent owns which files. Document this in your project's coordination file. If Agent A is working on the networking layer, Agent B should not touch those files. This sounds obvious but agents don't read social cues - you need explicit boundaries.
The Quality Tax
More agents doesn't always mean more productivity. Beyond three or four parallel agents, the coordination overhead - reviewing outputs, resolving conflicts, verifying nothing broke - can eat up all the time you saved. Start with two agents and scale up only when your isolation strategy is solid.
Fazm is an open source macOS AI agent. Open source on GitHub.