Parallel Claude sessions need git worktrees — here's the isolation pattern that prevents chaos

Running multiple coding agents in parallel sounds like a productivity dream. Two Claude sessions, one handling the API refactor while another builds the dashboard. What could go wrong?

Everything. They'll overwrite each other's changes, conflict on file locks, and leave your repo in a state that makes git blame look like abstract art.

The problem isn't the agents — it's that you're running them in the same working directory. They're stepping on each other's files, competing for the same resources, and creating merge conflicts that would make a senior engineer weep.

Here's the pattern that fixes it: git worktrees. Each agent gets its own isolated copy of your repo, works independently, then merges back when done.

Key insight: Git worktrees let you check out the same repo to multiple directories simultaneously. Each worktree has its own working directory but shares the same .git database.

Here's how to set it up:

# Create worktrees for each agent
git worktree add ../agent-1-api-refactor feature/api-refactor
git worktree add ../agent-2-dashboard feature/dashboard

# Each agent works in its own directory
# Agent 1: /project/agent-1-api-refactor
# Agent 2: /project/agent-2-dashboard

Now your agents can work simultaneously without conflicts. Agent 1 refactors the API in its worktree while Agent 2 builds the dashboard in another. No file locks, no overwrites, no chaos.

But here's the critical part: each agent needs to know its boundaries. Don't just throw them into separate worktrees and hope for the best. Give them explicit instructions:

You are working in worktree: agent-1-api-refactor
Your branch: feature/api-refactor
Your scope: API endpoints in /src/api only
Do not modify: frontend files, database migrations
When complete: commit your changes and notify for merge

The merge strategy matters too. Don't let agents merge their own work — that's how you get broken main branches. Instead, use a coordinator pattern:

• Agents work in their worktrees
• They commit to their feature branches
• A coordinator agent (or you) handles the merge review
• Clean up worktrees after successful merge

I've been running this pattern with two Claude sessions for weeks. One handles backend work, another manages frontend updates. The isolation is perfect — no more "wait, which agent changed this file?" detective work.

Warning: Don't forget to clean up. Stale worktrees eat disk space and create confusion. Run git worktree prune regularly.

The cleanup is simple:

# After successful merge
git worktree remove ../agent-1-api-refactor
git branch -d feature/api-refactor

This pattern scales beautifully. Need three agents? Create three worktrees. Working on a complex feature with multiple components? Give each agent its own worktree and scope.

The key is isolation with coordination. Each agent gets its own sandbox, but they're still working toward the same goal with clear handoff protocols.