Subagents and Parallel Work With Coding Agents

Parallel agents fail in one boring way: two of them edit the same file. Everything else about running several coding agents at once, including the tooling, the models, and how many you run, matters less than deciding up front who owns which files.

This guide covers the three ways Claude Code runs work in parallel (subagents, worktree sessions, and agent teams), what Codex and Cursor offer, how to divide a task so lanes don't collide, and what the person or agent coordinating the lanes should check before anything merges. Product behavior is from the vendor docs as of September 26, 2026.

Three mechanisms, three jobs

Claude Code has three separate features that people lump together as "parallel agents". They solve different problems.

Sources: subagents, worktrees, agent teams.

The short version: a subagent keeps your main conversation clean, a worktree keeps your files clean, and a team adds coordination on top at a higher token cost.

Subagents: isolate the context

A subagent runs in its own context window with its own system prompt and tool access, then returns a summary to the session that spawned it. The docs say subagents don't see your conversation history or the files you've already read. They do load CLAUDE.md and a git status snapshot unless you turn that off.

Claude Code ships three built-in subagents: Explore and Plan, which are read-only, and a general-purpose agent with all tools. You can ask for one in plain language:

use a subagent to investigate how our auth system handles token refresh

That example is from the common workflows page. The file reads happen in the subagent's context, and only the findings come back.

Custom subagents are Markdown files in .claude/agents/ (project) or ~/.claude/agents/ (you). The frontmatter controls what the helper can do. This reviewer can read but not edit:

---
name: diff-reviewer
description: Reviews a finished change for bugs, missing tests, and edits outside the stated scope. Use after a lane reports done.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You review one change. Run git diff against the base branch. Report, in order:
files changed outside the scope you were given, bugs, missing or weakened tests,
and anything you could not verify. Do not edit files.

Two frontmatter fields matter for parallel work. isolation: worktree gives each run of the subagent its own temporary git worktree, removed automatically if it made no changes. background: true lets it run while you keep working. Subagents can nest up to three levels by default, and up to 20 can run at once, per the docs.

Cost is the catch. The subagents page says each subagent's requests count toward the same usage limits as your main conversation. A subagent saves context, not money.

Worktrees: isolate the files

A git worktree is a second checkout of the same repository on its own branch. Claude Code creates one for you:

claude --worktree feature-auth

Per the worktrees page, that creates .claude/worktrees/feature-auth/ on a new branch named worktree-feature-auth. Run the same command with a different name in another terminal and you have two sessions that can't touch each other's files. While a session is isolated, Claude Code blocks edits and commands that target the main checkout.

Three setup details from the docs save a confused first hour:

• Add .claude/worktrees/ to .gitignore so worktree contents don't show up as untracked files in your main checkout.
• Install dependencies in each worktree. It is a fresh checkout. node_modules isn't there.
• Copy gitignored config with .worktreeinclude. A file at the repo root, in .gitignore syntax, listing things like .env.local. Claude Code copies matching gitignored files into each new worktree.

On exit, a clean worktree from an unnamed session is removed automatically. A worktree with changes prompts you to keep or remove it. Non-interactive claude -p runs don't clean up, so remove those yourself with git worktree remove.

You can also create worktrees with plain git (git worktree add ../project-feature-a -b feature-a) and start claude inside. That works with any agent, including Codex and Cursor's CLI.

Agent teams: coordination at a price

Agent teams run several full Claude Code sessions with a lead that assigns tasks from a shared list and teammates that message each other. They are experimental and off unless you set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (agent teams docs).

The docs are candid about the trade. Teams "use significantly more tokens than a single session", token use scales with the number of teammates, and for sequential tasks or same-file edits a single session or subagents work better. They suggest starting with three to five teammates and, for a first try, a task that doesn't write code, such as a parallel review of one pull request from security, performance, and test-coverage angles.

Their file-conflict advice is one line and it's the rule for everything on this page: "Two teammates editing the same file leads to overwrites. Break the work so each teammate owns a different set of files."

Codex and Cursor

Codex has subagents too. Per the Codex subagents docs, it spawns them when you ask directly or when an AGENTS.md or skill tells it to. Custom agents are TOML files in .codex/agents/ or ~/.codex/agents/ with a name, description, and developer_instructions. Subagents inherit your sandbox policy and approval mode, and the docs warn they "consume more tokens than comparable single-agent runs". Codex cloud tasks are the other parallel route: each runs in its own cloud environment and comes back as a diff or pull request (Codex cloud docs).

Cursor runs cloud agents in isolated VMs, each on its own branch, launched from the editor, the web, Slack, or an @cursor comment on GitHub (Cursor cloud agents docs). They bill at API pricing for the selected model.

The mechanism differs. The rule doesn't: one lane, one set of files, one branch.

How to divide the work

Split by file ownership, not by feature name. "Frontend" and "backend" sound separate until both lanes edit the shared types file. Before you start any lane, list every file each lane may create or edit, then look for overlap.

A method that holds up:

1. Map the change to files first. Ask a read-only subagent (Explore or Plan) to list which files a task will touch. That costs one research pass and prevents the collision.
2. Give every shared file exactly one owner. Route files, config, lockfiles, a shared JSON registry, the series index: one lane edits it, the others don't. If two lanes genuinely need it, sequence them.
3. Leave glue for last. The edit that wires lanes together, such as an index export, a nav entry, or a manifest, belongs to the coordinator after lanes finish.
4. Ban the commands that write shared state. In a shared checkout, two lanes running a full build or a code generator at once can corrupt the output. Name the allowed checks per lane.
5. Keep lanes small enough to review. A diff you can read in one sitting beats a lane that "does the whole backend".

A lane brief that encodes those rules is short:

Lane: API validation for the signup form
You own: src/app/api/signup/route.ts, src/lib/validation/signup.ts,
         src/lib/validation/signup.test.ts
Do not edit: anything else. If you think a shared file must change,
             stop and say which file and why.
Allowed checks: npx vitest run src/lib/validation/signup.test.ts,
                npx eslint <your files>
Do not run: the full build, code generators, git commit.
Report: files changed, checks run with results, anything unverified.

What the orchestrator reviews

Whoever coordinates the lanes, you or a lead agent, reviews each lane before it merges. The docs note that the lead in an agent team sometimes declares the work finished early, so this step stays with a person or a dedicated reviewer.

• Scope. git diff --stat against the base. Any file outside the lane's list is a finding, even if the change looks fine.
• Checks, rerun. Rerun the lane's stated checks yourself. A report that says "tests pass" is a claim until you see the output.
• Shared files, once. Apply the glue edits after all lanes land, then run the full build once.
• Unverified items. Every lane report should list what it could not check. Those items are your to-do list, not footnotes.
• Tests that got easier. A lane that makes a failing test pass by loosening the assertion has changed the spec. Read the test diff, not just the result.

The diff review guide in this series goes deeper on reading agent changes. For multi-agent design outside coding tools, see how to build a multi-agent AI system.

Previous in the series: Hooks for coding agents. Next: MCP servers for coding agents.