Stop Running Multiple Agents in the Same Repo - Use Directory Ownership

Five AI agents running in the same repo sounds productive until they all edit the same file at the same time. Merge conflicts, overwritten changes, broken builds - the chaos scales faster than the productivity gains. Directory ownership is the fix.

The Problem in Detail

When multiple agents work on the same codebase without coordination, file conflicts are the obvious problem but not the only one.

Race conditions on shared files. Agent A reads package.json, Agent B adds a dependency and writes the file, Agent A writes its version back - and Agent B's changes disappear. This happens constantly on package.json, tsconfig.json, tailwind.config.ts, and any file that multiple features touch. The agents have no visibility into each other's operations.

Logical conflicts that don't show as merge conflicts. Agent A refactors a function signature. Agent B adds three call sites using the old signature. Both agents commit cleanly with no conflict markers. The build breaks when someone tries to combine the work.

Shared context pollution. If two agents are both running Claude Code in the same directory, they share CLAUDE.md and potentially interfere with each other's session context. Instructions written by one agent's session bleed into another's.

Test suite fights. Two agents running tests simultaneously on the same codebase can interfere with shared database state, port bindings, or temp files. One agent's test setup tears down what another agent's test created.

Git Worktrees as the Foundation

Before directory ownership, establish isolation at the filesystem level with git worktrees. A worktree is a second checkout of the same repo at a different path, on a different branch:

# Create a worktree for each agent
git worktree add ../project-agent-ui feature/ui-updates
git worktree add ../project-agent-api feature/api-refactor
git worktree add ../project-agent-tests feature/test-coverage

# Each agent works in its own directory
# Changes don't interfere with each other at the OS level

Each worktree has its own working directory, its own .git state pointer, and its own branch. Agents cannot accidentally overwrite each other's uncommitted changes because they are not sharing a filesystem path.

Worktrees solve the filesystem problem. Directory ownership solves the logical problem.

Directory Ownership Pattern

Assign each agent a clear, non-overlapping scope:

Agent 1 - /src/components/     UI work only
Agent 2 - /src/api/            Backend endpoints and services
Agent 3 - /src/lib/            Shared utilities and helpers
Agent 4 - /tests/              Test coverage across all modules
Agent 5 - /docs/ and /scripts/ Documentation and tooling

The rule is simple: each agent only modifies files in its assigned directories. Shared files get a designated owner, and other agents must request changes rather than making them.

This works because most feature work is naturally scoped. A UI component change touches /src/components/ and nothing else. An API endpoint change touches /src/api/. The overlap is rarer than you would expect.

Encoding Ownership in CLAUDE.md

Put ownership rules in each agent's CLAUDE.md so every session starts with clear boundaries:

# Agent Scope: UI Components

## Your Directory
You own /src/components/. Only modify files in this directory.

## Out of Scope
Do NOT modify:
- /src/api/ (owned by API agent)
- /src/lib/ (owned by utilities agent)
- package.json, tsconfig.json, or any root config files
- /tests/ (owned by test agent)

## Requesting Cross-Agent Changes
If you need a change in /src/lib/:
1. Stop and document what you need
2. Create a GitHub issue describing the required change
3. Leave a TODO comment in your code: // TODO: needs lib update - see issue #N
4. Continue with your work using a stub or type assertion

Do not implement the change yourself. Do not modify files outside your scope.

This is the most important part. The agent needs explicit instructions about what to do when it hits a dependency on another agent's directory - stop, document, and continue rather than reaching across the boundary.

Handling Shared Files

Some files genuinely need to be modified by multiple agents. package.json is the classic example - both the UI agent adding a React component library and the API agent adding a database driver need to edit it.

Two approaches:

Designated owner. Assign package.json to one agent (typically a "coordinator" role). Other agents create requests: add a comment in their own code, open an issue, or write to a shared request file that the coordinator picks up.

Merge-friendly format. For files like package.json, use a separate manifest approach: each agent writes its dependencies to a separate file (deps-ui.json, deps-api.json) and a separate merge script combines them. This eliminates the conflict entirely.

# Each agent writes its dependencies here
# deps-ui.json: {"react-query": "^5.0", "framer-motion": "^11.0"}
# deps-api.json: {"drizzle-orm": "^0.30", "pg": "^8.11"}

# Merge script (runs in CI or on demand)
node scripts/merge-deps.js

Practical Enforcement

Without enforcement, agents eventually violate boundaries when they think crossing them is faster. Three mechanisms help:

Pre-commit hook. Reject commits that touch files outside the declared scope:

#!/bin/bash
# .git/hooks/pre-commit
AGENT_SCOPE=$(cat .agent-scope 2>/dev/null || echo "none")

if [ "$AGENT_SCOPE" = "none" ]; then
  exit 0  # no scope defined, allow anything
fi

CHANGED_FILES=$(git diff --cached --name-only)
VIOLATIONS=""

while IFS= read -r file; do
  if [[ "$file" != "$AGENT_SCOPE"* ]] && [[ "$file" != ".agent-scope" ]]; then
    VIOLATIONS="$VIOLATIONS\n  $file"
  fi
done <<< "$CHANGED_FILES"

if [ -n "$VIOLATIONS" ]; then
  echo "Scope violation: files outside $AGENT_SCOPE:$VIOLATIONS"
  exit 1
fi

Each worktree has a .agent-scope file containing its root path (e.g., src/components/).

Pull request review. PRs that touch files outside the agent's declared scope get flagged automatically in CI. A simple GitHub Actions check:

- name: Check agent scope
  run: |
    SCOPE=$(cat .agent-scope)
    git diff --name-only origin/main | grep -v "^$SCOPE" | grep -v "^.agent-scope" > violations.txt
    if [ -s violations.txt ]; then
      echo "Files outside scope $SCOPE:"
      cat violations.txt
      exit 1
    fi

Session context. Including the ownership rules at the top of CLAUDE.md means every new session starts with the boundaries in context. Agents are less likely to violate rules they were just reminded of.

When Boundaries Need to Move

Directory ownership is not permanent. As features evolve, scopes need to adjust. The process:

1. One agent finishes its current work and is ready for a new assignment
2. Review whether the boundary served its purpose
3. Update CLAUDE.md for all agents if the boundary changes
4. Communicate the change before starting new sessions

Avoid adjusting boundaries mid-session. A running agent that has planned work around its scope will produce confused output if the scope changes while it is working.

How Well This Scales

Five agents with clear boundaries produce more than five agents fighting over shared files - even accounting for the overhead of cross-agent requests and the occasional delay waiting for another agent's directory to become available.

The productivity gain is not just from parallelism. It is from focus. An agent that knows it owns /src/components/ makes cleaner, more coherent changes than an agent that might touch anything. The constraint is a feature.

Fazm supports multi-agent workflows on macOS with session isolation, making directory ownership patterns easy to enforce.

This post was inspired by a discussion on r/ClaudeAI (219 upvotes, 62 comments) by u/nelson-v.

Fazm is an open source macOS AI agent. Open source on GitHub.

More on This Topic

• Git Worktree Isolation for Multi-Agent Work
• Managing Parallel Claude Agents
• 668K Line Codebase with Multi-Agent Orchestration