---
title: "Claude Code agent teams vs separate sessions on one repo · Cork"
description: "Claude Code agent teams vs separate sessions on one repo: how each works, token cost, same-file conflicts, worktrees, and when to pick which (October 2026)."
canonical: "https://corkcli.com/blog/claude-code-agent-teams-vs-separate-sessions"
last_updated: "2026-10-03"
published: "2026-10-03"
author: "Kevin Vera"
---

# Claude Code agent teams vs separate sessions on one repo

Claude Code agent teams vs separate sessions on one repo: how each works, token cost, same-file conflicts, worktrees, and when to pick which (October 2026).

By Kevin Vera · October 3, 2026 · [Guides](https://corkcli.com/blog/c/guides) · 7 min read

Use a Claude Code agent team when one task benefits from several Claude instances that discuss, split and check each other's work under one lead session. Use separate sessions (usually one per git worktree) when you have independent tasks that you want to steer yourself, possibly over hours or days. As of October 2026, agent teams are experimental, use significantly more tokens, and share one checkout, so the docs warn that two teammates editing the same file leads to overwrites. Separate sessions isolate files with worktrees but only meet again at merge time.

## How agent teams work

Agent teams coordinate "multiple Claude Code instances working together." One session is the team lead; teammates "work independently, each in its own context window, and communicate directly with each other." The pieces, from the Claude Code docs:

- **Team lead:** the main session that spawns teammates and coordinates.
- **Teammates:** separate Claude Code instances, each working on assigned tasks.
- **Task list:** shared work items with dependencies. "Task claiming uses file locking to prevent race conditions when multiple teammates try to claim the same task simultaneously."
- **Mailbox:** direct messaging between agents.

Agent teams are "experimental and disabled by default." Turn them on in `settings.json`:

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

Then ask for a team in plain language, for example "Spawn three teammates to review PR #142: one on security, one on performance, one on test coverage." Teammates run in your terminal by default (in-process mode), or in split panes with tmux or iTerm2. Hooks such as `TaskCompleted` and `TeammateIdle` let you enforce quality gates: exit with code 2 to keep a teammate working or block a task from completing.

Limitations worth knowing before you rely on them: `/resume` and `/rewind` do not restore in-process teammates, a session has exactly one team, teammates cannot spawn their own teammates, and the lead is fixed for the session's lifetime.

## How separate sessions work

The other approach is to open several Claude Code sessions yourself, each in its own terminal, and give each one a task. To keep their file edits apart, start each in its own git worktree:

```bash
claude --worktree feature-auth
claude --worktree bugfix-123
```

Each command creates a worktree under `.claude/worktrees/<name>/` on a new branch named `worktree-<name>`. A worktree is a fresh checkout, so list gitignored files such as `.env` in a `.worktreeinclude` file to have them copied in. You can also manage worktrees with git directly (`git worktree add ../project-feature-a -b feature-a`).

Separate sessions can still talk. With cross-session messaging (Claude Code v2.1.224 or later on macOS and Linux), Claude can "list and message your other Claude Code sessions on this machine." The docs give the motivating case: "When a change in one session breaks what another is building on, Claude can warn that session before you notice." Messages are plain text, and Claude decides when to send one unless you ask it to. Your sessions on other machines and in the cloud are reachable through Remote Control.

## Side by side

| | Agent team | Separate sessions |
|---|---|---|
| Who coordinates | The lead session | You, plus optional cross-session messages |
| Setup | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`, then ask for teammates | Open terminals; `claude --worktree <name>` for isolation |
| Shared state | Task list with dependencies, mailbox | Git history; plain-text messages |
| File isolation | One checkout; docs advise giving each teammate different files | One worktree per session |
| Lifetime | One session; teammates not restored on `/resume` | Each session resumes on its own |
| Token cost | "Significantly more tokens than a single session" | Each session pays for its own context; no lead overhead |
| Status | Experimental | Generally available |

## When to pick an agent team

The docs list the strongest uses as research and review, new modules where each teammate owns a separate piece, debugging with competing hypotheses, and cross-layer changes split by layer. They also say what teams are bad at: "For sequential tasks, same-file edits, or work with many dependencies, a single session or subagents are more effective."

Practical rules from the same docs: start with 3 to 5 teammates, aim for 5 to 6 tasks per teammate, and if you are new to teams, start with work that does not write code, such as a PR review.

## When to pick separate sessions

Separate sessions fit when tasks are independent and long-running, when you want to review each stream yourself, or when different people own different streams. They also survive restarts better, since each session resumes on its own and worktrees persist until you remove them.

The tradeoff is merge time. Worktrees prevent two sessions from writing the same file while they work, but if both changed the same function, you find out when you merge. Cross-session messaging helps if Claude notices and chooses to send a warning, but nothing enforces it.

## The problem neither fully solves

Both approaches coordinate Claude sessions run by one person. In the docs' words, "in every approach the workers are Claude sessions." Real repos often have more: a Codex agent in another terminal, a Cursor agent in the editor, and teammates running their own agents on the same codebase. An agent team cannot see those agents, and cross-session messaging reaches only your own sessions. On a shared checkout the guidance is partitioning: "Break the work so each teammate owns a different set of files." That works when the work splits cleanly, and fails quietly when it does not.

## How Cork helps

Cork is the [coordination layer](https://corkcli.com/blog/coordination-layer-ai-coding-agents) for multiplayer coding agents: it keeps Claude Code, Codex and Cursor agents, on one machine or across a team's machines, from overwriting each other on one codebase, and hands each agent what the others already learned.

It sits under either setup rather than replacing it. Cork's hooks run inside each Claude Code session, so every teammate and every separate session gets the same protocol:

- **[Write gate](https://corkcli.com/blog/write-gate):** an edit against code another agent is changing right now is held until your agent has their version. This covers the same-file case the agent teams docs warn about.
- **Live awareness:** when another agent renames or re-signatures code yours depends on, your agent hears it on its next step, without relying on Claude choosing to send a message.
- **Briefing:** each agent gets the exact signatures, callers and recent changes of the code it is about to touch.
- **Landing:** for worktree sessions, `git push` becomes one step that rebases onto teammates' commits, reruns the tests and pushes.

Cork does not plan or assign work, so keep agent teams for orchestration. It covers Codex and Cursor agents too, and with Team, teammates' machines. Install it with:

```bash
curl -fsSL https://corkcli.com/install.sh | sh
```

## Frequently asked questions

### Are Claude Code agent teams better than multiple sessions?

For one task that benefits from discussion and parallel exploration, yes. For several independent tasks you want to steer yourself, separate sessions in worktrees are simpler, cheaper and not experimental.

### Do agent teams use git worktrees?

Not by default. Teammates share the lead's checkout, which is why the docs recommend giving each teammate a different set of files. Subagents, by contrast, can run in their own worktree with `isolation: worktree`.

### Can two Claude Code sessions edit the same file?

They can, and the later write wins. Run them in separate worktrees to isolate edits until merge, or use a coordination layer that holds an edit while another agent is changing the same code.

### How much more do agent teams cost?

The docs say they "use significantly more tokens than a single session," since each teammate is a separate Claude instance with its own context window and usage scales with active teammates.

## Sources

- <https://code.claude.com/docs/en/agent-teams>
- <https://code.claude.com/docs/en/worktrees>
- <https://code.claude.com/docs/en/cross-session-messaging>
- <https://code.claude.com/docs/en/agents>
- <https://code.claude.com/docs/en/sub-agents>
- <https://git-scm.com/docs/git-worktree>

## Related reading

- [Claude Code subagents vs parallel sessions: when to use which](https://corkcli.com/blog/claude-code-subagents-vs-parallel-sessions): Subagents or parallel Claude Code sessions? Compare context, control, file isolation and cost, with a decision checklist and setup for each, as of October 2026.
- [Agent-to-agent messaging between coding agents: how it works](https://corkcli.com/blog/agent-to-agent-messaging-coding-agents): How coding agents message each other as of October 2026: Claude Code SendMessage, team mailboxes, cross-session sockets, A2A, and what a useful message holds.
- [How to run multiple Claude Code agents on one repo without conflicts](https://corkcli.com/blog/run-multiple-claude-code-agents-one-repo): Run several Claude Code agents on one repository safely: worktrees, subagents, agent teams, cross-session messaging, and a clean landing routine, step by step.
- [How to share context between Codex and Claude Code](https://corkcli.com/blog/share-context-codex-claude-code): Make Codex and Claude Code work from the same context: one AGENTS.md, shared MCP servers, handoff files, and live awareness when both edit the same repo.

[All articles](https://corkcli.com/blog.md) · [Cork in Markdown](https://corkcli.com/index.md) · [llms.txt](https://corkcli.com/llms.txt)

This page in HTML: https://corkcli.com/blog/claude-code-agent-teams-vs-separate-sessions