How to delegate tasks in parallel with sub agents and worktree in Claude Code

Issue #1028

Running one Claude session at a time is fine for small tasks. For larger work — building a feature while fixing a bug, writing tests while refactoring — you need parallelism. Claude Code provides two tools for this: sub-agents and git worktrees.

When you ask Claude to do two things at once in a single session, it does them sequentially. More importantly, every file read and every edit fills up the context window. A long session gets slower and less focused as it grows.

Sub-agents solve the context problem. Worktrees solve the file conflict problem.

What Sub-Agents Do

A sub-agent is a separate Claude instance that handles a specific task in its own context window. It runs independently, returns results to the parent session, and then terminates. The parent conversation stays clean.

Claude Code ships with three built-in sub-agents: Explore (fast, read-only codebase search), Plan (research during plan mode), and general-purpose (complex multi-step work). You can also create custom ones.

Claude delegates to sub-agents automatically when it recognizes a task matches their description. You can also invoke them explicitly:

use the code-reviewer subagent to check the auth module

To see what’s available in the current session:

/agents

Creating a Custom Sub-Agent

Sub-agents are Markdown files with YAML frontmatter. Save them to .claude/agents/ for project-level scope, or ~/.claude/agents/ to use them across all projects.

---
name: test-writer
description: Writes unit tests for Swift functions. Use when asked to add test coverage.
model: claude-haiku-4-5-20251001
tools:
  - Read
  - Write
  - Bash
---

You write focused Swift unit tests. Use XCTest conventions.
Check existing test files first to match the project's style.

The description field is how Claude decides when to delegate. Make it specific.

What Worktrees Do

A git worktree creates a separate working directory from the same repository. Each worktree has its own files, its own branch, and its own independent checkout — but they all share the same git history and remote connections.

Without worktrees, two Claude sessions in the same repo will overwrite each other’s changes. With worktrees, each session works in its own isolated directory.

Starting Claude in a Worktree

Use the --worktree flag to create an isolated worktree and start Claude inside it:

claude --worktree feature-auth

This creates .claude/worktrees/feature-auth/ with a new branch worktree-feature-auth, then starts a Claude session there. To run two sessions in parallel, open two terminals:

# Terminal 1
claude --worktree feature-payments

# Terminal 2
claude --worktree bugfix-timeout

Both sessions work on the same codebase without any conflicts. When you exit a worktree session with no changes, Claude removes it automatically. If there are changes, Claude asks whether to keep or discard the worktree.

Sub-Agents with Worktree Isolation

Sub-agents can also run in isolated worktrees. Add isolation: worktree to a custom sub-agent’s frontmatter:

---
name: feature-builder
description: Implements new features. Use when adding functionality to the codebase.
isolation: worktree
tools:
  - Read
  - Write
  - Edit
  - Bash
---

You implement features in isolation. Write clean, focused code.
Run tests before finishing.

When Claude delegates to this agent, it gets its own worktree automatically. No parent session configuration needed. Finished worktrees with no changes are cleaned up at startup.

You can also ask Claude during a session:

use worktrees for your agents

A Practical Parallel Workflow

Here’s how to run three independent tasks simultaneously.

First, set up .worktreeinclude in the project root to copy environment files into each worktree:

.env
.env.local

Then open three terminals and start each session:

# Terminal 1: new feature
claude --worktree feature-dashboard

# Terminal 2: bug fix
claude --worktree fix-login-race

# Terminal 3: tests
claude --worktree tests-api-coverage

Each Claude session works independently. When they finish, check the branches:

git worktree list

/path/to/project                    abc1234 [main]
/path/to/project/.claude/worktrees/feature-dashboard    def5678 [worktree-feature-dashboard]
/path/to/project/.claude/worktrees/fix-login-race       ghi9012 [worktree-fix-login-race]
/path/to/project/.claude/worktrees/tests-api-coverage   jkl3456 [worktree-tests-api-coverage]

Review the changes in each branch, then merge what you want:

git merge worktree-fix-login-race
git merge worktree-feature-dashboard

Clean up when done:

git worktree remove .claude/worktrees/feature-dashboard
git worktree prune

Keeping Worktrees Out of Git Status

Worktree directories will show up as untracked files in git status unless you exclude them. Add this to .gitignore:

.claude/worktrees/

Conclusion

Use --worktree when you want two or more interactive Claude sessions running in parallel from separate terminals. Use isolation: worktree in a sub-agent definition when you want Claude to spawn isolated workers automatically from within a single session — useful for building, testing, and reviewing in parallel without managing terminals yourself.

The two approaches compose naturally. You can be in a worktree session and have that session spawn sub-agents with their own worktrees. Each level of work stays isolated from the others.