Running multiple Claude Code agents on the same repo

You want to run more than one Claude Code agent on the same repository without duplicating work or losing track of decisions. Parallel execution alone isn’t enough. Agents need a shared place to register what they intend to do, record decisions, and surface overlaps before they start editing.

What parallel execution gives you and what it doesn’t

Running multiple Claude Code sessions in separate terminals gives you parallel execution. Each agent can work on different files at the same time, which speeds up independent tasks. However, each session keeps its context private, so changes and decisions made by one agent aren’t visible to the others.

Parallel execution doesn’t prevent duplication. If two agents are asked to implement the same feature in different ways, you’ll discover the overlap only when you review the pull request. At that point, undoing one implementation is more expensive than avoiding the duplication in the first place.

Parallel execution also doesn’t surface scope overlaps. An agent editing a utility function in one terminal doesn’t know that another agent is about to refactor the same function in a different way. The file-level isolation of worktrees doesn’t help here, because the conflict is in the design, not the file system.

Why worktrees aren’t the answer for coordination

Git worktrees isolate files so you can check out different branches in separate directories. This prevents direct file collisions when agents work on different branches. However, worktrees don’t share context about what each agent is doing, why they made certain choices, or what assumptions they’re operating under.

Agents can still step on each other indirectly. For example, one agent might refactor a shared data structure while another agent is building a feature that depends on the old structure. Worktrees let both agents run in parallel, but they don’t prevent the resulting merge conflict or the need to rework the feature after the refactor.

Worktrees also don’t prevent logical overlaps. Two agents might independently decide to change the same function’s behavior in conflicting ways, even though they’re editing different files. Coordination requires sharing intent and decisions, not just file paths.

What state must be shared between agents

When agents depend on each other’s decisions, you need to share three kinds of state: what each agent is working on, the assumptions they’re operating under, and the decisions they’ve made. This shared state must be visible before any agent starts editing, so others can see overlaps and adjust their plans.

First, agents need to register their presence and claim a task or a scope of work. This lets other agents know that someone is already active in that area. Second, agents need to record their intent, assumptions, and findings as they work. This prevents others from making conflicting changes based on outdated assumptions.

Without this shared state, agents operate in silos. Each one makes decisions in private, and those decisions only surface at pull request time. By then, the cost of fixing mistakes or resolving conflicts is higher than if the overlap had been caught earlier.

A workflow that coordinates multiple agents

Start by splitting the work into independent tasks where possible. When tasks depend on each other, define clear handoff points and share the state at each step. Use a shared workspace to track ownership, decisions, and scope overlaps before any agent starts editing.

1. Register presence and claim work

Each agent begins by registering its presence and claiming a task or a scope of work. This step surfaces any overlaps with other agents who are already active in the same area. If two agents try to claim overlapping scopes, the second one receives an overlap warning and must either reassign the task or split the work before proceeding.

Overlap warnings arrive when an agent claims work, which the five tools each contribute to in a different way. This lets you avoid wasted effort and merge conflicts before any code is written.

2. Record intent, assumptions, and findings

As agents work, they record their intent, assumptions, and findings in the shared workspace. This includes why they chose a particular approach, what trade-offs they considered, and what risks they identified. Other agents can read this state and adjust their own plans accordingly, avoiding duplication and conflicting changes.

Recording this state live means that when an agent needs to make a decision that affects others, the context is already available. For example, if one agent decides to change a shared interface, other agents can see the reasoning and adapt their work before they start editing.

3. Transfer or finish work at handoff points

When one agent finishes a subtask, it transfers the work to the next agent or marks the task as review-ready. Transferring work includes the decisions made, the tests run, and the risks identified. This gives the next agent a clear starting point and reduces the chance of rework.

If the work is ready for review, the agent records the changes, tests, risks, and decisions, then marks the task as review-ready. This signals to reviewers that the work is complete and the context is available for them to evaluate.

When to use this workflow

This workflow is useful when you have multiple independent tasks that can run in parallel, or when you have a large task that can be split into subtasks handled by different agents. It’s also useful when agents need to coordinate around shared state, such as a data structure or an API contract.

It’s less useful for tasks that require tight, real-time collaboration between agents, or when the work is so small that the overhead of coordination outweighs the benefits. In those cases, a single agent or a pair of agents working in the same session is more effective.

If you’re already using agents that support the MCP standard, you can implement this workflow with a local MCP server that provides the shared workspace. The server exposes tools for registering presence, recording intent, transferring work, and marking tasks as review-ready.

Agents like Claude Code, Cursor, and Codex can call these tools while they work, keeping their private sessions focused on the task at hand while the shared workspace handles coordination.

What success looks like

With this workflow, you avoid duplication and merge conflicts that arise from parallel execution without coordination. Each agent’s decisions and assumptions are visible to others before they start editing, so overlaps are caught early.

You also reduce the risk of agents making conflicting changes based on outdated assumptions. Shared state about intent, decisions, and tests gives reviewers a clear trail of why each change was made and what was tested, making the review process faster and more reliable.

Agents work in private sessions, but their context and assumptions live in shared workspaces where others can see them.

Next steps

If you’re running multiple agents today and seeing duplication or merge conflicts, try splitting work into independent tasks and sharing intent and decisions in a shared workspace. Start small: pick one task, register it, record your assumptions, and let another agent pick up the handoff.

For a deeper look at how the five tools sequence around a task, see how the five tools sequence around a task. If you’re already coordinating agents and want to reduce the overhead, consider a local MCP server that provides the shared workspace you need. You can also read about how other teams standardise their AI tools without locking in one agent.