Parallel coding agents need file state isolation — here's the git worktree pattern that prevents chaos

You want to run multiple coding agents in parallel. Agent A working on the frontend refactor while Agent B handles the API changes. Makes perfect sense until they start stepping on each other's files.

The naive approach is separate git branches. But agents don't context-switch like humans — they leave half-finished work everywhere. Agent A checks out feature/refactor, starts moving files around, then Agent B switches to feature/api and suddenly the frontend is in a broken state.

Don't do this: Multiple agents sharing one working directory with branch switching. You'll get file conflicts, lost work, and agents that can't complete tasks because their environment keeps changing under them.

The solution is git worktrees — separate working directories that share the same git history. Each agent gets its own isolated file system state.

#!/bin/bash
# Setup script for parallel agents

# Create worktrees for each agent
git worktree add ../project-agent-a feature/frontend-refactor
git worktree add ../project-agent-b feature/api-changes
git worktree add ../project-agent-c main  # read-only reference agent

# Each agent gets its own directory:
# /project-agent-a/  (Agent A's isolated workspace)
# /project-agent-b/  (Agent B's isolated workspace) 
# /project-agent-c/  (Agent C for research/reference)

Now each agent operates in complete isolation. Agent A can move files, refactor directory structures, even break the build — and Agent B never sees it. They're working on the same git repository but completely separate file states.

The key insight: Agents don't need to share a working directory — they need to share git history. Worktrees give you both isolation and coordination.

Here's the agent coordination pattern that makes this work:

# Agent A working in /project-agent-a/
$ git add .
$ git commit -m "feat: refactor component structure"
$ git push origin feature/frontend-refactor

# Agent B can pull those changes when ready
$ cd /project-agent-b/
$ git fetch origin
$ git merge origin/feature/frontend-refactor  # only when needed

Each agent commits to its own branch, pushes regularly, and can selectively pull changes from other agents when it makes sense for their task. No more "Agent B broke my environment" scenarios.

Pro tip: Give one agent a worktree on main as a "reference environment." When agents need to check current production behavior or research existing code, they query the reference agent instead of disrupting active work.

The cleanup is simple too:

# When agents finish their tasks
git worktree remove ../project-agent-a
git worktree remove ../project-agent-b
git branch -d feature/frontend-refactor  # if merged

This pattern scales beyond two agents. I've run four agents simultaneously — each with isolated worktrees, each making progress without stepping on the others. The key is treating your codebase like infrastructure that needs proper resource isolation.

Most people think parallel agents need complex orchestration. Really they just need separate sandboxes and a coordination protocol. Git worktrees give you both.