<!-- Claude Code agent teams: landing the pull requests · https://merget.ai/guides/claude-code-agent-teams-pull-requests -->

# Claude Code agent teams: landing the pull requests

Agent teams coordinate the work between Claude Code sessions, not the merge. Set a team up, avoid overwrites, and land what it produces.

Merget team · Nov 13, 2026 · 4 min read

Claude Code agent teams let one lead session coordinate several teammates through a shared task list and messages. Give each teammate its own files, end each stream of work in its own pull request, and let a merge queue reconcile the pull requests when several teams and developers land on the same main.

## What an agent team is

An agent team is several Claude Code sessions working together. One session is the team lead: it creates tasks, assigns them and synthesizes results. Teammates work independently, each in its own context window, and message each other directly. See the [agent teams docs](https://code.claude.com/docs/en/agent-teams).

Agent teams are experimental and off by default. Turn them on with an environment variable in `settings.json`:

```
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

Then describe the task and the teammates you want in plain language. The docs suggest starting with 3 to 5 teammates, and note that a team uses significantly more tokens than a single session.

## Teams, subagents or worktree sessions

| Option | How it works | Use it for |
| --- | --- | --- |
| Subagents | Helpers inside one session that report back to it. | Focused tasks where only the result matters. |
| Agent teams | Separate sessions with a shared task list and direct messaging. | Work that needs discussion and coordination between agents. |
| Worktree sessions | Independent sessions you start yourself, each on its own branch. | Parallel implementation that ends in separate pull requests. |

The docs list a few limits worth knowing before you rely on a team: a session has one team, teammates cannot spawn their own teammates, and resuming a session does not restore in-process teammates.

## Inside the team: give each teammate its own files

The docs are direct about the main hazard: “Two teammates editing the same file leads to overwrites.” Break the work so each teammate owns a different set of files, and keep tasks self-contained: a module, a test file, a review.

- Split by layer or module, so frontend, backend and tests each go to one teammate.
- For larger pieces of implementation, run separate sessions in [git worktrees](https://merget.ai/guides/claude-code-worktrees-merge) so each has its own checkout and branch.
- Ask the lead to wait for teammates to finish before it starts integrating.

### A prompt that sets file ownership

```
Create an agent team for the billing refactor. Spawn three teammates:
- api: owns src/api/ only
- ui: owns src/ui/ only
- tests: owns tests/ only
No teammate edits files outside its area. Wait for all three
before you integrate, then run the full test suite.
```

Naming each teammate and its files in the prompt gives the lead clear tasks to assign and gives you names to refer to later. If two areas must change together, give both to one teammate.

## Between teams: the pull requests still meet at main

A team coordinates the sessions inside it. It knows nothing about the other pull requests open against the repository: the ones from your colleagues, their agent teams, and yesterday’s sessions. Once everyone runs coding agents, pull requests arrive faster than they merge, and each one that lands moves main for the rest.

Two things go wrong. Pull requests that touch the same lines conflict in text and wait for a rebase. Pull requests that touch related code, such as a renamed function and a new call to its old name, merge cleanly and break the build. Both send someone, usually another agent session, back to repair work that was already finished.

## Landing the pull requests

1. Keep each pull request to one task. A team’s output can be several pull requests.
2. Run your required checks on the combined result, not only on each branch.
3. Put a merge queue in front of main so pull requests are ordered and tested together.
4. Choose a queue that works on conflicts instead of sending pull requests back.

[Merget](https://merget.ai/how-it-works) is a semantic merge queue for GitHub. It finds the pull requests that collide, including the ones Git merges cleanly, resolves the conflicts in queue order, and lands the result through your required checks and reviews.

Merget starts in Advisory mode, where it reports the conflicts and changes no source code. To give your agent the queue’s findings and order, paste this into it:

```
Fetch and execute the instructions to set me up for Merget from https://sema.merget.ai/agent-setup/prompt.md
```

## What a team costs, and where merge conflicts add to it

Each teammate is a separate Claude Code instance with its own context window, so token use grows with the size of the team. That is worth it when teammates work independently. It is wasted when a finished pull request has to be reopened because another one landed first: the repair is one more session on top of the team that already ran. See [what merge conflicts cost](https://merget.ai/guides/cost-of-merge-conflicts-ai-coding-agents).

In our benchmarks, Merget planned a queue of 40 merges in under 30 seconds and resolved [223 of 223 conflicted files](https://merget.ai/benchmarks/conflict-resolution) from real merges with one model call each. Agent sessions are kept for the conflicts that need them.

## Questions

### How do I enable agent teams in Claude Code?

Set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` to `1` in your environment or in the `env` block of `settings.json`. The feature is experimental and disabled by default.

### Do agent teams prevent merge conflicts?

Inside a team, file ownership prevents overwrites. Between pull requests from different teams, sessions and developers, conflicts still happen at merge time.

### What is the difference between agent teams and subagents?

Subagents work inside one session and report back to it. Teammates are separate sessions that share a task list and message each other.

### How many teammates should a team have?

The Claude Code docs suggest starting with 3 to 5 teammates for most workflows.

[See how Merget resolves conflicts in queue order](https://merget.ai/how-it-works), or [sign up free](https://sema.merget.ai/login) and connect one repository.

### Merging git worktrees from parallel Claude Code agents

Claude Code’s --worktree flag gives each session its own checkout and branch. Set them up, land the branches, and stop them colliding at merge time.

Merget team · Nov 13, 2026 · 4 min read

[Open](https://merget.ai/guides/claude-code-worktrees-merge)

### Codex worktrees: merging parallel agent branches

Codex runs each chat in its own git worktree so parallel tasks do not interfere. Turn the worktrees into pull requests and land them together.

Merget team · Nov 13, 2026 · 4 min read

[Open](https://merget.ai/guides/codex-worktrees-merge)

### Cursor worktrees and cloud agents: landing the pull requests

Cursor runs agents in git worktrees on your machine and in cloud VMs that push branches. See how both work and how to keep the pull requests landing.

Merget team · Nov 13, 2026 · 4 min read

[Open](https://merget.ai/guides/cursor-worktrees-cloud-agents)

[All guides](https://merget.ai/guides)
