Skip to content

Agentic Software Development

Workflows & Fleets

Parallel Agents Without Merge Hell: Git Worktrees and Specialized Subagents

From Agentic Software Development · 10 articles · latest

Topology diagram of isolated git worktrees running parallel researcher, builder, and verifier subagents merging into main
Each parallel builder gets its own git worktree and branch while read-only researchers and isolated verifiers stay cleanly decoupled.

Once you see an agent knock out a 40-minute module refactor in four minutes, your next instinct is obvious: "What if I spin up three terminal tabs and run three tasks at once?" If all three agents point at the exact same working tree on disk, you don't get 3x velocity—you get instantaneous filesystem chaos. Agent A runs git status and sees Agent B's half-edited file, assumes it broke something, and git checkouts Agent B's work into oblivion while Agent C's test server locks the SQLite database.

To run parallel agents reliably—Stage 5 in our agentic engineering roadmap—you need two forms of isolation working together: filesystem/state isolation via Git worktrees, and role isolation via specialized subagents.

Why git worktree Solves Concurrent Checkouts

Most developers know git branch, yet surprisingly few regularly use git worktree. Unlike cloning a multi-gigabyte repository three times (and duplicating .git object history), git worktree shares one .git object store while giving each branch its own completely separate directory, staging index, and HEAD—a foundation covered in depth in Parallel Agents and Worktrees.

Before launching two independent tasks simultaneously, spin up clean sibling directories:

# From your primary repo checkout on main
git fetch origin
git worktree add ../repo-feat-retry -b feat/client-retry origin/main
git worktree add ../repo-feat-audit -b feat/seo-audit origin/main

# Inspect active checkouts
git worktree list

Now Agent 1 operates solely inside ../repo-feat-retry and Agent 2 operates solely inside ../repo-feat-audit. They never stomp on each other's uncommitted changes, git diff output, or IDE language server caches. Just remember two operational habits: first, keep .venv or node_modules either rebuilt cleanly inside the worktree (uv sync or pnpm install --offline) or symlinked read-only so dependency setup takes seconds instead of minutes. Second, once a branch merges via pull request or fast-forward, tear down the worktree promptly before stale checkouts pile up:

git worktree remove ../repo-feat-retry && git branch -d feat/client-retry
git worktree prune

If Agent 1 merges first while Agent 2 is still running, do not panic about branch drift—rebase Agent 2's worktree onto updated origin/main before running final tests so you catch interface mismatches inside the isolated worktree rather than on main.

The Trap Nobody Mentions: Shared Ports and State

Filesystem isolation alone isn't enough if both worktrees spin up integration tests that bind to localhost:5432 or write to /tmp/test.db. That is how parallel builds pass individually and flake unpredictably together.

Keep parallel worktrees genuinely independent with three small conventions:

  1. Random or hash-derived ports: Parameterize test servers via PORT or pytest --basetemp / per-worktree Docker project names (COMPOSE_PROJECT_NAME=wt-retry).
  2. Ephemeral test databases: Give each worktree its own schema or SQLite temp file rather than a shared local DB.
  3. Disjoint file ownership in specs: Even with separate worktrees, launching two agents that both heavily refactor core/client.py guarantees painful manual merges later. Use your 30-line task specs to assign disjoint modules per parallel branch—or enforce automated integration serialization via a pull request merge queue.

Warning

Shared API state still collides: If two parallel agents edit live external state (like the same staging CMS entry), worktrees won't protect you. That is why stateful servers need optimistic concurrency hashes—like Pressroom's expectedContentHash conflict detection in Safe Agent Editing at Scale.

Specialize Your Subagents Instead of Cloning Generalists

The second half of clean parallelization is resisting the urge to spawn five identical "do-everything" clones. A single generalist agent exploring 25 files across a codebase quickly fills 70% of its context window with irrelevant search hits before writing line one of your fix—exactly the kind of real-world MCP and context-window failure mode we debugged in The Operational Reality of Agents in Production.

Instead, structure subagent orchestration patterns around three specialized roles with strict tool permissions:

Subagent RoleWorkspace & Write AccessContext DietDeliverable Returned to Parent
ResearcherRead-only (no file writes)Search hits, call sites, schema docsConcise 1-page synthesis of files, invariants, & exact line ranges
Scoped BuilderDedicated git worktree branchResearcher summary + 30-line specClean commits passing Red-phase tests & static checks
Adversarial VerifierRead-only (or test runner only)Git diff + spec (NOT builder chat!)Pass/fail review flagging missing edge cases or test gaming

Look closely at why the Adversarial Verifier must never inherit the Builder's chat history. If the Builder convinced itself midway through debugging that ignoring a 409 Conflict edge case was fine, an independent Verifier reading only the original spec and git diff spots the missing requirement in five seconds.

Knowing When Sequential Beats Parallel

Parallel fleets feel futuristic, yet orchestrating worktrees adds real coordination overhead. Do not parallelize tightly coupled database schema changes, sweeping cross-cutting renames, or exploratory architecture spikes where every step informs the next. Save worktree fleets—or background issue-to-PR delegation pipelines—for well-bounded, disjoint backlog work: three independent bug fixes, parallel test coverage backfills, or decoupled frontend/backend endpoints behind a frozen OpenAPI contract.

Put all six building blocks together—disciplined stage progression, a crisp AGENTS.md, short EARS specs, clean Skills vs. MCP boundaries, independent verification gates, and worktree isolation—and AI coding stops feeling like herding unpredictable interns. It starts feeling like real software engineering again.

Keep reading

Comments