Managing 5+ Parallel Claude Code Agents Without Losing Track

Running one Claude Code agent is straightforward. Running five simultaneously on the same codebase is where things get chaotic. After months of doing this daily, here is what actually works - and what the growing ecosystem of parallel agent tooling confirms.

Anthropic shipped built-in git worktree support for Claude Code in early 2026, validating what practitioners had figured out independently: isolation is the foundation of parallel agent management. Without it, agents step on each other's work constantly.

Git Worktrees: The Non-Negotiable Foundation

The single most important practice for parallel agent work is giving each agent its own git worktree. Without this, two agents editing the same file simultaneously produce merge conflicts and corrupted state that neither agent can cleanly resolve.

# Set up worktrees for three parallel agents
git worktree add ../project-auth-refactor feature/auth-refactor
git worktree add ../project-test-coverage feature/add-test-coverage
git worktree add ../project-docs-update feature/update-docs

# Each agent works in its own directory
# cd ../project-auth-refactor && claude  (agent 1)
# cd ../project-test-coverage && claude  (agent 2)
# cd ../project-docs-update && claude    (agent 3)

Each worktree shares git history with the main repository but has its own working directory, its own staged changes, and its own HEAD. Agents commit independently. You merge when each feature is complete.

Anthropic's implementation in Claude Code automates this - when you ask an agent to "use worktrees," it creates and cleans up the worktree automatically. The manual approach above is useful when you want explicit control over the feature branch names or when running multiple Claude Code processes from the command line.

Shared CLAUDE.md as the Coordination Layer

Your project's CLAUDE.md file is the one place all parallel agents read from. It becomes the coordination layer for work that cannot be fully isolated.

Structure it to answer the questions agents need answered before taking action:

# Project Coordination

## Active Agents (update when you start/finish)
- auth-refactor: working on src/auth/, DO NOT TOUCH these files
- test-coverage: working on tests/, adding coverage for auth module
- docs-update: working on docs/ and README only

## Shared Conventions
- Commit format: feat/fix/chore(scope): description
- Tests must pass before committing
- Use TypeScript strict mode

## Files Off-Limits (being modified by another agent)
- src/auth/session.ts - auth-refactor agent
- src/auth/permissions.ts - auth-refactor agent

## Merge Order
1. auth-refactor merges first (other work depends on it)
2. test-coverage merges second
3. docs-update merges last (no code dependencies)

Updating CLAUDE.md when you spin up a new agent takes 30 seconds. Debugging a merge conflict caused by two agents touching the same file takes much longer.

Session Naming That Survives 10 Open Terminals

The naming problem is simple: "agent-1" through "agent-5" tells you nothing when you have five terminal windows open and need to know which one is doing what.

Name sessions after the task, not the agent number:

# tmux session naming
tmux new-session -s auth-refactor
tmux new-session -s test-coverage
tmux new-session -s docs-update
tmux new-session -s dependency-audit

# Then switch by task name
tmux attach -t auth-refactor

If you use iTerm2 or Warp, set the tab title explicitly when you start each agent session. The cognitive overhead of remembering "agent-3 is doing the thing with the auth" disappears when the tab is labeled "auth-refactor."

Dependency Mapping Before You Start

The hardest part of parallel agent work is not technical - it is the upfront thinking about which tasks can actually run in parallel and which have dependencies that require sequential execution.

A quick dependency check before spinning up agents:

Task: auth-refactor
Files touched: src/auth/*
Depends on: nothing (greenfield refactor)
Blocks: test-coverage (tests need updated auth interface)

Task: test-coverage
Files touched: tests/auth/*
Depends on: auth-refactor (must complete first)
Blocks: nothing

Task: docs-update
Files touched: docs/*, README.md
Depends on: nothing (documentation is independent)
Blocks: nothing

Parallelizable now: auth-refactor + docs-update
Sequential: test-coverage runs after auth-refactor merges

Tasks that touch the same files cannot run in parallel, even with worktrees. A conflict at merge time is still a conflict. Tasks in independent parts of the codebase can run simultaneously without coordination overhead.

The Practical Limit: 5 Agents

Five is approximately the practical upper limit for parallel agents before coordination overhead begins exceeding the productivity gain. The Citadel and ccswarm projects that emerged in 2025 to automate parallel agent management both found this number independently. Beyond five agents, the cost of reviewing and merging independent work streams grows faster than the work itself.

The reasons:

• Each additional agent requires checking its status, reviewing its output, and making a merge decision
• Dependency conflicts multiply with agent count (each new agent can conflict with all prior agents)
• Context for what each agent is doing grows beyond what fits in short-term memory

Start with two agents on a real project and add a third only after you have a reliable merge workflow. Most teams find that three well-coordinated agents deliver more output than five poorly-coordinated ones.

Handling the Merge Wave

When multiple agents complete work around the same time, you face a merge wave: several feature branches ready simultaneously, each potentially conflicting with the others.

Strategies that reduce merge wave friction:

Establish merge order upfront - Before starting agents, decide the merge sequence. The agent working on the most foundational change merges first. Others rebase onto the freshly merged main before their PR is reviewed.

Use a lead agent for merging - One agent takes the role of reviewing and merging other agents' work, rebasing conflicts, and keeping main clean. This works well for teams already using Claude Code for code review.

Merge incrementally - Do not wait for all agents to finish. Merge the first agent's work as soon as it is ready. The second agent rebases. This keeps the merge window small and conflicts manageable.

# After auth-refactor agent completes
git checkout main
git merge feature/auth-refactor
git push

# Signal to test-coverage agent (update CLAUDE.md)
echo "auth-refactor merged - test-coverage can now rebase onto main" >> CLAUDE.md

# test-coverage agent rebases
cd ../project-test-coverage
git rebase main

When More Agents Is the Wrong Answer

Spinning up more agents does not always mean more output. Signs that you need better coordination, not more agents:

• You are spending more than 20% of your time managing agents rather than reviewing their output
• Merge conflicts are appearing regularly (agents are not isolated correctly)
• You cannot summarize what each agent accomplished today without checking logs
• Agents are asking redundant questions because CLAUDE.md is not up to date

Fix the coordination infrastructure before adding agents. A single well-directed agent with clear instructions and proper isolation outperforms three poorly-coordinated agents on any task with real complexity.

The goal is not to run the maximum number of agents. It is to run enough agents that work is progressing at a rate you can keep up with - so that the bottleneck is your review and decision speed, not agent execution speed.

This post was inspired by a discussion on r/macapps by u/ParthJadhav.

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