Efficient Claude Code: Context Parallelism & Sub-Agents

• 3 min read • Systems Engineering

Practical guide to parallelizing work using git worktree and Claude. Clean checkouts, clean AI contexts

TL;DR

  • Problem: Branch juggling and a shared Claude Code context slow you down when handling multiple tasks at once.
  • Solution: Create one isolated worktree per task, run a separate Claude session in each, and use sub-agents for efficient context management and better specialization.

Why this setup works

  • Isolated code states. git worktree creates additional working directories that share history but keep their own files, HEAD, and index. No stashing. No heavy clones. Git docs
  • Isolated AI contexts. Claude Code sub-agents run in their own context window so one task’s history does not pollute another. Sub-agents

Think of it like multiple separate benches in a workshop. Each bench has its own parts and its own notebook.

Parallelizing work with git worktree

git worktree lets you create multiple working directories from a single repository, each with its own checked-out branch and index while sharing the same .git object database. Practically, it means you can develop feature A, feature B, and a hotfix in parallel-no stashing, no branch juggling, and no heavyweight extra clones. Each worktree is a normal folder you can build/test independently and merge or open PRs from as usual.

Create one folder per task from the main repo:

# from your main repo directory
git worktree add ../app-feature-a -b feature/a   # new branch + worktree
git worktree add ../app-feature-b -b feature/b   # another branch + worktree
git worktree add ../app-hotfix hotfix/123        # existing branch into a worktree

Now you have three sibling folders, each a full checkout sharing the same .git object database. You can build/run/tests independently in each.

Check what is active and clean up when done:

git worktree list
git worktree remove ../app-feature-b          # tree must be clean

Notes:

  • If a branch is checked out in another worktree, Git will refuse to reuse it. Create a new branch or detach.
  • You can enable per-worktree Git config with git config extensions.worktreeConfig true

One Claude session per folder

Run a separate Claude Code session inside each worktree:

# Terminal 1
cd ../app-feature-a && claude

# Terminal 2
cd ../app-feature-b && claude

# Terminal 3
cd ../app-hotfix && claude

You can build, test, and commit independently in each folder. Anthropic’s docs recommend this pattern for running parallel Claude Code sessions with worktrees.

Sub-agents: specialist help with clean contexts

Sub-agents are specialized AI assistants (e.g., code-reviewer, debugger, data-scientist) with their own system prompt, tool permissions, and separate context window. Claude Code can auto-delegate to them or you can invoke explicitly. This preserves your main thread while letting specialists go deep.

Manage agents

/agents   # open the interactive sub-agents UI

Pick project-level or user-level, describe when it should be used, and select allowed tools. Claude will auto-use it when the description matches, or you can call it explicitly

Use the code-reviewer subagent to check my recent changes.

Where the files live

  • Project sub-agents → .claude/agents/ (checked into VCS)
  • User sub-agents → ~/.claude/agents/ (global to you)

Simple example (project file .claude/agents/code-reviewer.md)

---
name: code-reviewer
description: Expert code review; use proactively after code changes
model: sonnet
---

You are a senior code reviewer. Run `git diff` for recent changes,
focus on modified files, and report:

- Critical issues, Warnings, Suggestions (with examples/fixes)

Drop-in library of sub-agents

To get started you can use wshobson/agents repo. It’s a large collection you can place under ~/.claude/agents/ (or manually copy selected agents into your project). It includes patterns for automatic delegation and multi-agent workflows.

Common pitfalls and guardrails

  • Branch locking. One branch cannot be checked out in two worktrees. Create new branches for parallel tasks.
  • Per-tree setup. Each worktree may need its own npm install or virtualenv. Treat them like separate repos.
  • Context creep. Keep sub-agent descriptions tight and only grant required tools. Accuracy improves. Risk drops.

Mini-checklist

  • Create a worktree per task: feature A, feature B, hotfix.
  • Start one Claude session inside each folder.
  • Add sub-agents for review, testing, and debugging.
  • Keep agent scopes narrow and tool access minimal.
  • Merge or open PRs from each branch when green.
View All Notes