Integrate parallel sessions without losing ownership

Learning objective

Parallelize work with subagents and multiple sessions while managing context.

Core idea

Parallel work earns its cost when independent assignments can finish without repeatedly renegotiating shared decisions. Subagents isolate task context inside a session; separate Claude Code sessions can isolate editing work in Git worktrees. Neither removes the need for an integration owner who decides what joins the release.

The architect adds a team workflow around those mechanisms: assign a base revision, divide ownership, supply bounded context, verify returned changes, and control cleanup. Optimize accepted throughput rather than the count of agents running at once. Several fast generators can overwhelm one reviewer or produce individually correct changes that disagree on an interface.

How it works

Choose the coordination boundary

Use a subagent for a bounded investigation or review whose result feeds the main session. Use separate sessions when work needs independent steering, a distinct editing lifecycle, or an experiment that should remain separate until compared. Subagents work within one session; worktree sessions have separate conversations and editing lifecycles.

Choose coordination according to who operates those sessions. Cross-session messaging lets hand-run sessions exchange findings; the desktop app provides visual local-session management; cloud sessions use Anthropic-managed infrastructure by default. Agent view (claude agents) is in research preview and provides background-session dispatch and monitoring. Agent teams are experimental and disabled by default, adding a team lead, shared tasks, and messaging for automated coordination. Prefer hand-run worktrees for a few independently steered tasks; consider these surfaces when visual oversight, hosted execution, or automated coordination justifies their setup and status constraints.

Parallelize independent assignments; wait for an accepted producer interface before implementing its dependent consumer.

Record a small assignment sheet: owner, goal, base revision, editable paths, dependencies, verification commands, expected return, and integration owner. These team-owned fields expose outstanding work when a session returns incomplete results.

Isolate editing with worktrees

Git’s git worktree add associates another working tree with the same repository, allowing different branches to be checked out simultaneously. Linked worktrees have separate working files and per-worktree metadata such as HEAD and the index, while repository data is shared. This supplies checkout isolation, not a separate infrastructure environment.

Claude Code exposes claude --worktree NAME, also spelled -w. Its default creates .claude/worktrees/NAME/ and branch worktree-NAME. The worktree.baseRef setting defaults to "fresh", branching from the repository’s default remote branch; "head" uses the launching worktree’s local HEAD. Use the latter when workers require committed in-progress interface changes. Uncommitted edits are not a substitute for a shared base revision.

For subagents that edit independently, set isolation: worktree in the custom subagent’s frontmatter, or ask Claude to use worktrees for its agents. Context separation alone does not create a separate checkout: without worktree isolation, a subagent starts in the main conversation’s working directory. Verify the actual editing location before launching overlapping changes.

Claude Code adds checks that block direct file-tool edits and certain command or Git redirects into the main checkout. Those checks do not track every file a shell command writes. A shell copy or redirect can still target the main checkout subject to permissions and sandboxing. Use the access policy in 7.1.3 for that boundary. Choosing Yes, and don’t ask again for a Bash command normally saves the approval in the main checkout’s .claude/settings.local.json, applying it to the main checkout and every other worktree even after the originating worktree is removed. On Windows and in other cases where Claude Code does not use the repository root, the rule stays with that worktree. Review a persistent approval as a change to every parallel session in that clone, not to one worker; a rule the whole team needs belongs in the committed .claude/settings.json (7.1.1, 7.1.3).

Reproduce the environment deliberately

A worktree is a fresh checkout, so initialize its dependencies and test configuration. .worktreeinclude copies matching gitignored files when Claude creates worktrees with Git; it uses .gitignore syntax and does not duplicate tracked files. Select patterns deliberately because copying an ignored environment file can also copy credentials or shared-service endpoints.

Give parallel test sessions separate test resources when their commands would otherwise mutate the same service. Different source directories do not assign different databases, network ports, or deployment targets. The assignment sheet should name the permitted test environment and credentials; the worktree setup should implement that choice. If isolation cannot be provided, serialize the conflicting operation while preserving parallel source work.

Check instruction provenance too. A worktree-isolated subagent takes its startup instruction files from the main conversation, not from its own worktree. Under the default .claude/worktrees/ location, it also does not load the worktree root’s CLAUDE.md or .claude/rules/ while reading there. Do not assume switching branches gives that subagent the instructions on the switched branch. Include branch-specific requirements explicitly in the assignment.

Join artifacts instead of transcripts

Require each worker to return the revision or patch, changed paths, commands and results, unresolved questions, and the decision needed from the coordinator. Preserve detailed output in an artifact when useful; return the concise result needed for integration. Raw exploration logs from several workers can fill the coordinator’s context despite separate worker windows.

Use /clear between unrelated assignments and /compact with focus instructions when continuing one long task. Keep the accepted interface, modified files, remaining dependencies, and verification status in the handoff. Compaction is a context-management operation; it does not recheck a source claim or merge a branch.

The integration owner compares returned changes with the agreed interface, resolves conflicts, and runs combined verification. A worker’s passing local test proves only what ran against its own revision and environment. The final integrated revision needs the completion policy in 7.2.3, particularly where changes interact without creating a textual conflict.

Worktree sessions start from the committed interface changes, and the integration owner runs combined verification on the changes they return.

Retire checkouts without losing work

For interactive worktrees Claude created with Git, a clean unnamed session is removed automatically on exit; a named clean session prompts first. Worktrees with work, or with unverifiable state, also prompt. Non-interactive -p worktrees have no exit prompt and are not cleaned up on exit. Assign their cleanup explicitly.

For isolated subagents, an unchanged temporary worktree is removed when the subagent finishes; changed worktrees can remain for the documented retention sweep. Preserve the required patch and verification result before removal. Use git worktree remove for deliberate cleanup, inspecting retained work first. A finished conversation is not proof that its unmerged changes are disposable.

Key distinctions and trade-offs

Context isolation versus checkout isolation: A summary reduces the main session’s reading load. A worktree separates editable source. Some assignments need both.

Checkout isolation versus resource isolation: Worktrees do not allocate independent external test or production services.

Parallel generation versus integrated completion: Fast workers still depend on review capacity, shared interfaces, and combined checks.

Parallelism adds setup, duplicated context, simultaneous usage, and integration work. Subagents make their own requests against the session’s usage limits. Prefer a small number of independently useful assignments over a wide fan-out whose outputs one person cannot evaluate.

Architecture / decision scenario

An education platform has three days to update grading exports and student-notification templates, with one integration reviewer. The tempting approach launches six sessions against the same checkout, each editing whichever files seem necessary. The architect instead creates two independently owned editing assignments and one bounded subagent investigation of compatibility tests.

The interface change is accepted and committed first. The two editing sessions use separate --worktree checkouts with worktree.baseRef: "head", so both start from that interface revision. Each uses its own test configuration rather than a copied production environment file. The investigation returns relevant test paths and gaps, not a full search transcript.

One session finishes in an hour; the other needs four. The reviewer does not integrate the first as a complete release. After both return their changes and results, the integration owner checks the shared export identifier and runs the combined suite. A mismatch can fail integration even when both branches pass locally. The owner preserves accepted commits and reports before removing retained worktrees, keeping the review workload within the single-reviewer constraint.

Common exam traps

• Assuming a separate subagent context automatically provides separate files.
• Launching a dependent consumer before its interface exists.
• Assuming a worktree starts from uncommitted main-session changes.
• Copying environment files without considering their credentials and shared resources.
• Treating local worker passes as verification of the integrated revision.
• Assuming every worktree is automatically deleted when its session ends.

What to remember

Choose the context and editing boundaries independently. Give each worker a known base, owned scope, reproducible environment, and compact return. Keep integration and cleanup under explicit ownership; concurrency succeeds only when the combined revision is accepted.

Knowledge check

References

• Anthropic, Run parallel sessions with worktrees
• Anthropic, Create custom subagents
• Anthropic, Best practices for Claude Code
• Anthropic, Agent view
• Anthropic, Agent teams
• Git, git-worktree