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.
- Subagents run in their own context and return a summary
- Parallel sessions each get their own git worktree
- Claude Code's own parallel features run only Claude
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: sonnetThose 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_SUBAGENTSchanges 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: worktreein 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.
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?
Which one should you use?
Start with the lightest option that fits, and move up only when the task needs it.
- A quick change or a task with lots of back-and-forth: stay in one main conversation.
- A side task that would flood your context (searching a large codebase, reading logs, running tests): use a subagent and keep only its summary.
- Several independent Claude tasks that edit files at once: subagents with
isolation: worktree, or background sessions from agent view, which each get a worktree. - Work you want to steer task by task, or a reviewer from another provider: run separate sessions, each in its own worktree.
- 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
maocommand. 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
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.
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.
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.
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.
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: 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: 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:
claude --worktree, the.claude/worktrees/location and branch name, and worktrees for subagents. - Manage multiple agents with agent view:
claude agents, research preview status, and the worktree each dispatched session moves into. - Orchestrate teams of Claude Code sessions: agent teams, how to enable them, the comparison with subagents, file conflicts and token usage.
- Message your other Claude Code sessions: cross-session messaging, its version requirement, and what a message carries.
- Manage costs effectively: subagent requests drawing on your usage, smaller models for subagents, and agent team token costs.
- How to run multiple Claude Code agents in parallel and Multi-agent orchestration for coding agents: MAO's layers, wires,
maocommand and attention. - Run a shell or agent, Create a worktree layer, Connect agents, notes, and portals, Work with connected notes from the CLI and Add and choose provider accounts: MAO's agent nodes, layers, connections, notes and accounts.
Checked on 2026-10-28.
Questions? Ask in the Discord or write to hello@miguer.com.