--- title: "Claude Code subagents vs parallel sessions: when to use which · Cork" description: "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." canonical: "https://corkcli.com/blog/claude-code-subagents-vs-parallel-sessions" last_updated: "2026-11-14" published: "2026-10-03" author: "Kevin Vera" --- # Claude Code subagents vs parallel sessions: when to use which 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. By Kevin Vera · October 3, 2026 · [Guides](https://corkcli.com/blog/c/guides) · 6 min read Use subagents when one conversation should hand off a self-contained side task and only needs the result back, such as a codebase search, a log dig or a test run. Use parallel sessions when you have several independent pieces of work that you want to steer yourself, each with its own conversation and usually its own git worktree. Subagents keep your main context clean; parallel sessions give you more throughput and more control, at the price of coordinating them yourself. ## The core difference A subagent lives inside your session. Claude Code's docs define subagents as "specialized AI assistants that handle specific types of tasks," each running "in its own context window with a custom system prompt, specific tool access, and independent permissions." It works, then returns a summary to the conversation that spawned it. A parallel session is a separate `claude` process, typically started in another terminal with `claude --worktree `. It has its own full conversation with you, and it does not report back to any other session unless it messages one. | | Subagents | Parallel sessions | |---|---|---| | Who steers | Claude delegates; you talk to the main session | You, in each session | | Context | Fresh window; returns a summary to the caller | Full, independent conversation | | What it sees at start | Its own prompt, the task message, CLAUDE.md, git status | Everything a normal session loads | | File isolation | Optional: `isolation: worktree` | Optional: `claude --worktree` | | Talking to others | Reports to its caller | Cross-session messaging, if Claude chooses or you ask | | Best for | Noisy side tasks, specialist roles | Independent features, bugs, experiments | All details are as documented by Anthropic as of October 2026. ## When subagents are the right call The docs list three signals: - "The task produces verbose output you don't need in your main context." - "You want to enforce specific tool restrictions or permissions." - "The work is self-contained and can return a summary." Typical examples: "find every caller of `parseConfig` and list them," "run the integration tests and summarize failures," or a read-only reviewer that cannot edit files. A subagent definition is a Markdown file in `.claude/agents/` (project) or `~/.claude/agents/` (personal): ```markdown --- name: test-runner description: Runs the test suite and reports failures with file and line tools: Read, Grep, Glob, Bash model: sonnet --- Run the tests, then report each failure with its file, line and a one-line cause. Do not edit files. ``` Add `isolation: worktree` when a subagent should edit files in parallel with others, so each gets a temporary worktree. Subagents can run in the background while you keep working, and by default can spawn their own subagents up to three levels below the main conversation. Keep the main conversation, not a subagent, when "the task needs frequent back-and-forth," when "multiple phases share significant context," for "a quick, targeted change," or when latency matters, since a subagent starts fresh and has to gather context. ## When parallel sessions are the right call Use separate sessions when the pieces of work are independent and each deserves your attention: a feature, a bug fix and a dependency upgrade at the same time. Setup: ```bash claude --worktree feature-search # terminal 1 claude --worktree fix-login-timeout # terminal 2 ``` Each gets its own worktree under `.claude/worktrees/` on a `worktree-` branch, so edits never touch the other session's files. Name sessions so they are easy to address and resume. If you would rather dispatch tasks and check back later than sit in each terminal, agent view (`claude agents`, a research preview) shows background sessions on one screen and moves each into its own worktree before it edits files. Sessions can pass findings to each other with cross-session messaging: ```text Tell @fix-login-timeout that I changed the session cookie name to sid_v2 ``` ## What about agent teams? Agent teams sit between the two: a lead session spawns teammates that each have their own context, share a task list, and message each other directly. They are experimental and disabled by default (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`), they "use significantly more tokens than a single session," and they do not isolate teammates in worktrees, so the docs advise that each teammate own a different set of files. Reach for them when workers need to discuss and challenge each other, such as a parallel review or competing debugging hypotheses. ## A quick decision checklist 1. Will you need to talk to this worker more than once? Use a **parallel session**. 2. Do you only want the result, and would the process flood your context? Use a **subagent**. 3. Should the worker be restricted to certain tools? Use a **subagent** with a `tools` list. 4. Do several workers need to debate or divide a plan among themselves? Consider an **agent team**. 5. Will workers edit overlapping files? Whatever you pick, use **worktrees** and assign file ownership. On cost: a subagent "sends its own requests, which count toward the same usage limits as your main conversation," and every parallel session does the same. More workers means more tokens, so add them only when the work is truly parallel. ## How Cork helps Both patterns isolate context, and that is also their weakness: a subagent in its own worktree and a session in another terminal each work from what they read at the start. If one renames a function the other calls, they find out at merge time, or when Claude happens to send a message. 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. Whichever pattern you choose: - **Briefing:** each agent starts with the exact signatures, callers and recent changes of the code it is about to touch, so a fresh context window costs less searching. - **Live awareness:** a rename or signature change by any agent reaches the others that depend on it on their next step. - **[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, useful for agent teams that share one checkout. - **Landing:** `git push` becomes one step that rebases onto teammates' commits, reruns the tests and pushes. Hooks run this with no extra model calls. Cork Free covers one machine with no account; the paid plan adds teammates' machines. Install: ```bash curl -fsSL https://corkcli.com/install.sh | sh ``` ## Frequently asked questions ### Are Claude Code subagents parallel? They can be. Background subagents run concurrently while you keep working; foreground subagents block until they finish. ### Do subagents share context with the main session? No. A subagent starts with a fresh context window and does not see your conversation history. The exception is a forked subagent, which inherits the whole conversation. ### Is it cheaper to use subagents than multiple sessions? Each subagent and each session sends its own requests. Subagents can save main-context tokens by returning only a summary, but more workers always means more total usage. ### Can subagents edit the same files at the same time? Not safely in one checkout. Give them `isolation: worktree`, or split the work so each owns different files. ## Sources - - - - - ## Related reading - [Claude Code agent teams vs separate sessions on one repo](https://corkcli.com/blog/claude-code-agent-teams-vs-separate-sessions): 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). - [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. - [Cork vs Claude Code agent teams: one session's crew, or every agent on the repo](https://corkcli.com/blog/cork-vs-claude-code-agent-teams): Cork vs Claude Code subagents, agent teams and cross-session messaging: what each coordinates, where agents collide, and when to use both together. - [Running AI coding agents in a monorepo: what to watch for](https://corkcli.com/blog/ai-coding-agents-monorepo): What breaks when AI coding agents work in a monorepo: instruction files, context size, shared packages, affected tests and parallel agents, with fixes for each. [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-subagents-vs-parallel-sessions