Fleet of Claudes: Parallel Build Agents

Tier 3 · Everything Built 7 min read

Running one build agent is straightforward. Running six at the same time — each working on a different feature, each needing to commit to git — turns out to require solving problems that only appear at scale. Fleet of Claudes is the first system that got this right.

What It Is

Fleet of Claudes was a project (slug: fleet-of-claudes, completed 2026-04-30) to build a parallel-spawn engine for build agents. The completion criteria: 6 PRs merged, 48/48 fleet tests passing.

The name comes from the observation that running 6 concurrent Claude Code instances doesn’t require 6 human operators. One orchestrator, 6 workers, each in their own git worktree. The orchestrator spawns them, monitors them, and integrates their output.

The Trampling Problem

Before worktree isolation, concurrent build agents shared a working tree. Agent A runs git checkout feat/feature-a, starts editing page.tsx. Agent B, working on feat/feature-b, runs git checkout feat/feature-b. Agent A’s edits are now on Agent B’s branch. Agent A doesn’t know this yet.

This happened in practice. CHANGELOG 2026-05-22: “a parallel chat-resume sub-agent switched to chat-resume-fix branch, my page.tsx edits landed there instead of org-chart-v2, and recovery via cherry-pick + reflog cost ~15 minutes.” The same incident class recurred on 2026-06-08.

The fix, for agent-system work, is isolation: "worktree" in the Agent tool call. Each parallel agent gets its own directory (via git worktree add) and its own working tree. When it commits, the commit goes to the right branch in the right directory. The parent session’s working tree is untouched.

The fleet.py Module

At the code level, agents/shared/fleet.py (now part of the parallel-spawn-refactor project) handles the mechanics:

Spawn — calls the Agent tool with isolation: "worktree" and a specific objective prompt.
Monitor — tracks running agents by run ID.
Reap — reads the stream-json output from finished tmux sessions, marks tasks done or failed, and cleans up the worktree.
Report — surfaces results to the orchestrator (or directly to Telegram) when the batch completes.

The fleet doesn’t manage merges. That’s a deliberate design choice: agents land work on named branches; merge strategy is the orchestrator’s (or JD’s) decision. The fleet’s job is to get work onto branches, not to decide what’s production-ready.

The 6-PR Run (2026-04-30)

The completion run shipped 6 PRs in parallel:

Each agent had a distinct objective and a distinct target branch.
All ran with worktree isolation.
All 48 fleet tests passed on completion.

This was a proof-of-concept for the pattern that the work queue (and later the Infinity Fleet drainer) would industrialize. The 6-PR run proved that concurrent Claude Code agents can work on the same repository without trampling each other, given the isolation contract.

What the Isolation Contract Requires

For agents running parallel against the same repo, the rules (derived from the documented incidents) are:

Every background Agent call that touches git uses isolation: "worktree". No exceptions.
The worktree is the agent’s only workspace. It does not cd to the parent checkout.
Commits happen in the worktree. The parent session integrates via git fetch && git merge --ff-only <branch> if it needs the work inline, or leaves the branch for PR review.
Each agent is told it’s in a worktree. The prompt says: “You are in a worktree. Confirm with pwd. Don’t touch other branches in the parent checkout.”

For NC5 (the Nerve Center v5 repo, a nested separate git repo inside agent-system), the isolation goes one level deeper — a safe-nc5-edit.sh script creates a per-agent worktree under projects/nerve-center-v5/.claude/worktrees/safe-<branch>/, and a pre-commit hook refuses commits from the shared checkout path entirely. See Worktree Isolation: The Hard Lesson for the full story.

What Fleet of Claudes Enabled

Before the fleet: a complex multi-feature build meant doing features sequentially in one session. An 8-feature sprint took as long as the slowest feature times 8.

After: those 8 features can run in parallel. The orchestrator writes 8 objective prompts, spawns 8 worktree-isolated agents, and waits for the results. Wall time collapses to the length of the slowest feature (or the session’s context window, whichever binds first).

The capability existed in Claude Code’s Agent tool before Fleet of Claudes. What Fleet of Claudes added was the isolation discipline, the monitoring, and the 48-test suite that proved it was actually reliable.

Next: Infinity Fleet: The Queue Drainer — the queue-based, worktree-isolated drainer that scales build work across machines.