# Claude Code subagents or parallel sessions: which should you use?

Use subagents when Claude should hand a self-contained side task to a helper and only needs the summary back. Use separate sessions, each in its own git worktree, when you want to steer each task yourself, keep its full context, or run another provider beside Claude. MAO fits when those sessions also need to talk.

Use Claude Code subagents when one session should hand a self-contained side task (a search, a test run, a review) to a helper and only needs the summary back. Run several sessions in parallel, each in its own git worktree, when each task is big enough to steer yourself, needs its own full context, or should run on another provider such as Codex. MAO is for the second case: each session is a real terminal on a canvas, on its own branch, and wired sessions can send each other tasks.

## What are Claude Code subagents?

Subagents are helpers that Claude starts from inside your session. Each one runs in its own context window with its own system prompt, tool access and permissions, does its work there, and returns a summary to the main conversation.

Claude Code ships with built-in subagents, among them **Explore** (a fast, read-only agent for searching a codebase), **Plan** (read-only research during plan mode) and a general-purpose agent that can both explore and act. A subagent that is not a fork does not see your conversation history; a forked subagent inherits it.

You define your own subagent as a Markdown file with YAML front matter, in `.claude/agents/` for the current project or `~/.claude/agents/` for all your projects. Only `name` and `description` are required. The front matter of the docs' example reviewer:

```
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
```

Those four fields go between two `---` lines at the top of `.claude/agents/code-reviewer.md`, and the instructions below them ("You are a code reviewer...") become the system prompt. Claude reads each subagent's `description` to decide when to delegate. You can also ask for one by name ("use the code-reviewer subagent on the auth changes"), @-mention it, or run a whole session as that agent with `claude --agent code-reviewer`.

How subagents run, according to Claude Code's documentation:

- **Foreground or background.** A foreground subagent blocks the main conversation until it finishes; a background one runs while you keep working. With nothing configured, a subagent Claude spawns from the main conversation starts in the background.
- **Several at once.** By default up to 20 subagents can run in a session at the same time (`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` changes the limit), and a subagent can spawn its own, up to three layers below the main conversation.
- **Same checkout unless isolated.** A subagent starts in the main conversation's working directory. `isolation: worktree` in its front matter gives it a temporary git worktree instead, removed automatically if it makes no changes.
- **Same usage limits.** A subagent's requests count toward the same usage limits as your main conversation, and the docs warn that many subagents each returning detailed results can consume significant context.

## What parallel features does Claude Code document?

Besides subagents, Claude Code's docs describe several ways to run work in parallel, all of them made of Claude sessions. In the docs' words, to involve a different tool you expose it to Claude as an MCP server.

| Feature | What it is | Status in the docs |
| --- | --- | --- |
| Subagents | Workers inside one session that return a summary | Available |
| `claude --worktree <name>` | Starts a session in its own worktree under `.claude/worktrees/<name>/`, on a new branch `worktree-<name>` | Available |
| Agent view (`claude agents`) | One screen to dispatch and monitor background sessions; each moves into its own worktree before it edits files | Research preview |
| Agent teams | A lead session spawns teammates that share a task list and message each other directly | Experimental, off by default |
| Cross-session messaging | Claude can list and message your other Claude Code sessions; a message is text, never history or files | Available from v2.1.224 (v2.1.234 on native Windows) |

The docs also list dynamic workflows (a script that runs many subagents) and projects (parallel threads started from claude.ai/code or the desktop app). Agent teams are turned on with `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`, and the docs note that teammates are not isolated in worktrees, so each teammate should own a different set of files.

## What do separate parallel sessions give you instead?

A separate session is a full conversation per task that you can steer directly, in its own checkout, running whichever agent you choose. The price is that coordinating them is up to you or your tools.

- **Separate context.** Each session keeps its whole conversation, not a summary handed back to someone else, and you can talk to it at any point. That suits long tasks with many turns of back-and-forth, which the subagent docs say belong in a main conversation.
- **Separate worktrees.** Give every session that edits code its own worktree, so no session's half-finished change lands under another. Claude Code can create one for you, or you can use plain git:

```
claude --worktree feature-auth      # terminal 1
claude --worktree fix-session-bug   # terminal 2

# or with git directly
git worktree add ../myapp-api -b agent/api
cd ../myapp-api && claude
```

- **Mixing providers.** A terminal of its own can run Codex, Gemini CLI or another CLI agent next to Claude Code, which none of Claude Code's built-in features do.

Running several sessions or subagents at once multiplies token usage, so the docs point to their costs page for usage and rate limits. Agent teams in particular use significantly more tokens than a single session, because each teammate is a separate Claude instance.

## Subagents or parallel sessions: how do they compare?

|  | Subagents | Parallel sessions (one worktree each) |
| --- | --- | --- |
| Task size | A self-contained side task that ends in a summary | A task you steer over many turns |
| Who coordinates | Claude, from the main conversation | You, or agent view, cross-session messaging or an orchestration app |
| Context | Own window; only the summary returns | Each session keeps its full conversation |
| File isolation | Shares the checkout unless `isolation: worktree` is set | One worktree per session |
| Talking to each other | Report to the caller; subagents Claude named can message each other | Cross-session messaging between Claude Code sessions |
| Providers | Claude only | Any CLI agent, each in its own terminal |
| Usage | Counts toward the same limits; can run on a smaller model such as Haiku | Each session uses its own tokens; several at once multiply usage |

## Which one should you use?

Start with the lightest option that fits, and move up only when the task needs it.

1. **A quick change or a task with lots of back-and-forth:** stay in one main conversation.
2. **A side task that would flood your context** (searching a large codebase, reading logs, running tests): use a subagent and keep only its summary.
3. **Several independent Claude tasks that edit files at once:** subagents with `isolation: worktree`, or background sessions from agent view, which each get a worktree.
4. **Work you want to steer task by task, or a reviewer from another provider:** run separate sessions, each in its own worktree.
5. **Sessions that must hand work to each other:** add a way for them to talk, such as cross-session messaging between Claude Code sessions, an agent team, or MAO when the sessions include other providers.

## Where does MAO fit?

MAO is for the parallel-sessions side. Each session is a real terminal on a canvas, and MAO adds the branches, connections and notifications that plain terminals lack.

- **Every node is the agent's own CLI.** A node runs Claude Code, Codex, Gemini CLI, Grok, OpenCode, Antigravity or a shell, on that agent's own login and model. Because a Claude Code node is the real CLI, it can still delegate to its own subagents.
- **Layers are git worktrees.** Put an agent on a layer and it works on its own branch in its own working tree. You review the diff on the canvas and land the layer into Ground when it is ready.
- **Wires let sessions talk.** Connect two agents and they can send each other tasks and get results back with the `mao` command. A wire grants access only to the node at its other end.
- **Shared context lives in notes.** An agent wired to a note can read it and append to it, so a specification is written once.
- **Attention comes to you.** When an agent finishes, fails or waits for an approval, its node says so and you get a desktop notification.
- **Accounts per node.** Each agent node can use its own provider account, so two Claude Code sessions can run on two accounts side by side.

A worker asks its connected reviewer and logs progress from its own terminal:

```
mao peers
mao ask reviewer "Review the session refresh changes on this branch"
mao note append progress "Refresh path done; reviewer is on it"
```

## Frequently asked questions

### Do Claude Code subagents share context with the main conversation?

No. Each subagent runs in its own context window, does not see your conversation history and returns a summary. A forked subagent is the exception: it inherits the conversation.

### Can Claude Code subagents edit files in parallel without conflicts?

Yes, if each gets its own worktree. Add `isolation: worktree` to a subagent's front matter, or ask Claude to use worktrees for its agents; otherwise subagents work in the main conversation's checkout.

### Are subagents cheaper than running several sessions?

Subagents keep your main context smaller because only their summary comes back, but their requests count toward the same usage limits, and you can run them on a smaller model such as Haiku. Running several sessions or subagents at once multiplies token usage either way.

### Can a Claude Code subagent run Codex or Gemini?

No. In every Claude Code approach the workers are Claude sessions, and another tool can only be reached as an MCP server. To run Codex or Gemini CLI as an agent of its own, start it in its own terminal, or as a node in MAO wired to your Claude Code session.

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

Subagents report their results back to the main conversation, which manages all the work. In an agent team, a lead spawns teammates that share a task list and message each other directly; the feature is experimental, off by default and uses more tokens.

## Sources

- [Create custom subagents](https://code.claude.com/docs/en/sub-agents): what subagents are, their own context window, built-in subagents, file locations and front matter, invocation, foreground and background, concurrency and nesting limits, `isolation: worktree`, usage limits, and when to use the main conversation instead.
- [Run agents in parallel](https://code.claude.com/docs/en/agents): the list of Claude Code's parallel approaches, that the workers are always Claude sessions, MCP for other tools, and that several sessions or subagents multiply token usage.
- [Run parallel sessions with worktrees](https://code.claude.com/docs/en/worktrees): `claude --worktree`, the `.claude/worktrees/` location and branch name, and worktrees for subagents.
- [Manage multiple agents with agent view](https://code.claude.com/docs/en/agent-view): `claude agents`, research preview status, and the worktree each dispatched session moves into.
- [Orchestrate teams of Claude Code sessions](https://code.claude.com/docs/en/agent-teams): agent teams, how to enable them, the comparison with subagents, file conflicts and token usage.
- [Message your other Claude Code sessions](https://code.claude.com/docs/en/cross-session-messaging): cross-session messaging, its version requirement, and what a message carries.
- [Manage costs effectively](https://code.claude.com/docs/en/costs): subagent requests drawing on your usage, smaller models for subagents, and agent team token costs.
- [How to run multiple Claude Code agents in parallel](https://trymao.dev/run-multiple-claude-code-agents) and [Multi-agent orchestration for coding agents](https://trymao.dev/multi-agent-orchestration): MAO's layers, wires, `mao` command and attention.
- [Run a shell or agent](https://trymao.dev/docs/terminals-agents/terminal-and-agent-nodes), [Create a worktree layer](https://trymao.dev/docs/layers-git-worktrees/create-layer), [Connect agents, notes, and portals](https://trymao.dev/docs/connections-orchestration-mao-cli/node-connections), [Work with connected notes from the CLI](https://trymao.dev/docs/notes-binders/note-cli) and [Add and choose provider accounts](https://trymao.dev/docs/agent-presets-accounts-roles/agent-accounts): MAO's agent nodes, layers, connections, notes and accounts.

Checked on 2026-10-28.

Source: https://trymao.dev/claude-code-subagents-vs-parallel-sessions