Agent teams in Claude Code what they are and when they help

An agent team in Claude Code is a group of agents that coordinate on shared work, not just parallel sessions or nested subagents. Teams need shared state to surface who is doing what, what assumptions they made, and which files they touched, so duplicated or conflicting changes do not slip into the codebase.

Three patterns people call agent teams

When people talk about agent teams in Claude Code, they often blur three distinct patterns: subagents inside a single task, multiple parallel Claude sessions, and a team of agents coordinating across work. Each pattern solves a different coordination problem and requires different kinds of shared state.

Where each pattern helps

Use subagents for narrow, nested work inside one task, where context is already loaded and the risk of overlap is low. Use parallel sessions for independent tasks where isolation avoids accidental interference. Use a team of agents for shared work where overlapping changes are likely and you need to surface assumptions early.

When subagents fit

Subagents are a good fit when the subtask is small and the context is already loaded, such as writing tests for a function or adding documentation for a class you just edited. The parent agent can spawn a subagent, pass the relevant files, and the subagent does not need to re-read the entire codebase.

Because subagents share the parent’s context, they avoid rework for the subtask itself, but they do not expose their work to other parent tasks. If two parent tasks spawn subagents that edit the same file, the edits will conflict when you try to merge them later.

When parallel sessions fit

Parallel sessions are useful when tasks are independent and you want to keep work isolated, such as setting up a new service while fixing a bug in another. Each session keeps its own context, so changes in one session do not affect the other. This prevents accidental overlap, but it also means you cannot coordinate on shared files or decisions.

When a team of agents fits

A team of agents is the right choice when multiple agents work on related features, refactor overlapping code, or hand off work between them. Each agent registers its presence, claims a task, and exposes its assumptions and decisions so others can see them. This surfaces overlaps early and lets you name the practice before conflicts embed in the codebase.

What breaks when agents cannot see each other

When agents cannot see each other’s current work, duplicated effort and conflicting changes become the default. You only discover the overlap when you try to merge or review, and by then the mistakes are already in the codebase, making fixes more expensive.

Duplicated work

Two agents may both decide to refactor the same utility class because they cannot see that the other already started. Each agent writes its own version of the refactor, and the later change overwrites the earlier one. The result is lost work and a broken build until you redo the refactor by hand.

Conflicting edits

Agents editing different parts of the same file can generate clashing edits if they do not coordinate. One agent adds a new parameter to a function while another removes the same parameter because they worked from stale context. These conflicts appear as merge conflicts, but the root cause is the lack of shared state during editing.

Missed assumptions

An agent assumes a certain behavior for a module because it read outdated documentation, while another agent changed that behavior days ago. The first agent’s changes break the new behavior, and neither agent knows why until a test fails or a reviewer flags the issue. Shared state would have surfaced the change when it happened.

Review surprises

When agents keep their assumptions private until the pull request, reviewers see a wall of changes with no explanation for why they were made. The review turns into a debugging session to reconstruct the decisions, and you spend time asking agents for context instead of reviewing the code.

Shared state turns review into a confirmation step rather than a detective story. Decisions and findings are recorded as work progresses, so reviewers can see the rationale without rederiving it from the diff.

How shared state surfaces overlaps before they break

To coordinate across sessions and machines, agents need shared state that is visible to every agent in the team. This includes presence, claimed tasks, file scope, decisions, and findings. Tools like start_work, inspect_work, update_work, and transfer_work expose this state so overlaps surface early and conflicts are avoided.

Overlap warnings arrive when an agent claims work, which the five tools each contribute to in a different way. If an agent starts editing a file that another agent already scoped, the system can flag the overlap before the edit is saved. This prevents duplicated effort and clashing changes from ever being written.

Shared state also surfaces decisions and findings as they happen. When an agent records a decision or a finding, every other agent can see it in their inbox or outbox. That way, if one agent changes a module’s behavior, others can see the change and adjust their plans before they start editing.

Presence and task ownership

Agents register their presence and claim or accept tasks so others know who is working on what. If two agents try to claim the same task, the system can flag the conflict before either agent starts editing. This replaces the surprise that happens when parallel sessions step on each other’s work.

Decisions and findings

Agents record decisions and findings as they work so others can see the rationale behind changes. If one agent changes a module’s behavior, it records the decision and the reasoning. Other agents see this in their inbox and can adjust their plans before they start editing the same file.

File scope and edit history

Agents scope the files they plan to edit when they claim a task. If another agent scopes the same file, the system flags the overlap so both agents can coordinate. Shared state also records which changes each agent made, so reviewers can see the history of decisions instead of reconstructing it from the diff.

This history becomes review evidence. When you mark a task review-ready, the system records the changes, tests, and decisions so reviewers can see the full picture without digging through commit messages.

What to use when you need a team

If you need a true agent team that coordinates across sessions and machines, you need shared state that agents can read and write while they work. Subagents and parallel sessions do not provide this. You need tools that expose presence, task ownership, decisions, and findings in real time.

The Model Context Protocol defines a standard way for agents to call external tools, and a local MCP server can provide the shared workspace these tools need. Tools like start_work, inspect_work, update_work, transfer_work, and finish_work let agents register presence, claim tasks, record decisions, and hand off work without losing context.

These tools do not replace your coding agent. They sit beside it, called by the agent as it works, and expose the shared state the agent needs to coordinate with others. The result is fewer duplicated changes, fewer clashing edits, and review evidence that arrives with the code instead of after it.

Agents record their decisions and findings as they work, so reviewers can see the rationale without rederiving it from the diff.

If your team already uses MCP-capable agents like Claude Code, Cursor, or Codex, you can start coordinating them today. The only thing you need is a local MCP server that provides the shared workspace these agents call while they work.

For teams that coordinate across repositories and machines, a cloud workspace is coming soon. Until then, the local workspace is enough to start avoiding the coordination gaps that break agent teams today.