Two coding agents editing the same files is $200/month in merge conflict hell

Two agents editing the same codebase is a nightmare waiting to happen. We learned this the expensive way when our coding agents started overwriting each other's changes, creating merge conflicts that took hours to untangle, and generally turning our repository into a battlefield.

The problem isn't coordination—it's that agents don't understand ownership. They see a file, they edit it. They don't check if another agent is working on the same module, they don't understand the concept of "claiming" a piece of work, and they definitely don't know how to back off when there's a conflict.

Here's what we built to fix it: git worktrees with agent-specific branches.

#!/bin/bash
# Agent isolation script
AGENT_ID=$1
TASK_ID=$2

# Create isolated worktree for this agent
git worktree add "../agent-${AGENT_ID}-${TASK_ID}" -b "agent/${AGENT_ID}/${TASK_ID}"
cd "../agent-${AGENT_ID}-${TASK_ID}"

# Agent works here in complete isolation
echo "Agent ${AGENT_ID} workspace ready at $(pwd)"
echo "Branch: agent/${AGENT_ID}/${TASK_ID}"

Each agent gets its own complete copy of the repository. No shared files, no race conditions, no mysterious conflicts. When the agent finishes, it creates a PR from its branch. The merge happens through GitHub's normal review process, not through agents stepping on each other.

But isolation alone isn't enough. Agents also need to understand scope boundaries. We give each agent a manifest file that defines exactly what it's allowed to touch:

# agent-manifest.json
{
  "agent_id": "backend-dev-001",
  "task_id": "auth-refactor-2024-01",
  "allowed_paths": [
    "src/auth/**",
    "tests/auth/**",
    "docs/auth.md"
  ],
  "forbidden_paths": [
    "src/payment/**",
    "src/user-data/**",
    ".github/**"
  ],
  "max_files_changed": 15
}

The agent checks this manifest before every file operation. Try to edit something outside your scope? The operation fails with a clear error message. This prevents the "helpful" agent that decides to refactor your entire database layer while fixing a typo.

Critical: Never let agents merge their own PRs. That's where the real disasters happen. Agents celebrate success while CI burns red, approve changes that break production, and merge code they don't actually understand.

The cleanup process is automatic:

# After PR is merged or closed
git worktree remove "../agent-${AGENT_ID}-${TASK_ID}"
git branch -D "agent/${AGENT_ID}/${TASK_ID}"

This pattern scales to as many agents as you want without the coordination nightmare. Agent A can refactor the authentication system while Agent B builds the payment integration. They never see each other's work until the PR review stage.

The key insight: treat agents like remote developers, not like threads in a program. Remote developers get their own environment, work on their own branches, and submit their work for review. Agents should work the same way.

Cost impact: we went from spending $200/month on agents fixing each other's merge conflicts to $30/month on actual productive work. The worktree overhead is negligible—a few extra gigabytes of disk space per active agent.