Subagents and Parallel Work With Coding Agents

Parallel agents fail in one boring way: two of them edit the same file, and one overwrites the other.

Everything else about running several coding agents at once, including the tools, 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) and what Codex and Cursor offer. Then it shows how to split a task into lanes, one agent per lane, so they don't collide, and what whoever is coordinating 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 and costs a lot more usage.

Subagents: isolate the context

A subagent is a helper with its own context window (its own working memory for the conversation), its own instructions, and its own set of tools. It does the job and hands a summary back to the session that started 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 subagent reads all the files, and only its findings come back to your main conversation.

Custom subagents are Markdown files in .claude/agents/ (for one project) or ~/.claude/agents/ (for all your projects). The block at the top of the file, 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 (a separate copy of the code, explained below), 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, though. 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 copy of the same repository, in its own folder, 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 will save you 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's a fresh copy. node_modules isn't there.
• Copy ignored config files with .worktreeinclude. That's 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

An agent team is several full Claude Code sessions working together. A lead hands out tasks from a shared list, and the teammates message each other. They are experimental and off unless you set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (agent teams docs).

The docs are upfront about the cost. Teams "use significantly more tokens than a single session", usage grows with every teammate you add, 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, each in its own virtual machine, 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 which files each lane owns, 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.

Here's 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 heads off 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 the 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 to shared files. 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 spells out 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. Run git diff --stat against the base. Any file outside the lane's list is a finding, even if the change looks fine.
• Checks. Rerun the lane's stated checks yourself. A report that says "tests pass" is a claim until you see the output.
• Shared files. 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 what the test checks has changed what the code is supposed to do. 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.