Parallel Feature Dev: 3 Claude Code Agents, 3 Worktrees, 1 Termdock

What You Get: 3 Features Built in 40 Minutes

Picture a factory floor. Three assembly lines running side by side, each building a different product. No line waits for the others. No worker crosses into the wrong lane. At the end, three finished goods roll off simultaneously.

That is what happened here. Three features for a Next.js e-commerce app. Built in parallel. Merged cleanly. All tests passing.

Total wall-clock time: 40 minutes. The same work done sequentially: roughly 2 hours. The savings come from overlap. While Agent 1 builds search, Agent 2 builds the cart, Agent 3 builds email. Three assembly lines. One terminal window with three side-by-side panels.

This article walks through every step of that session. What to type. What to watch for. How to merge. If you want the theory behind git worktrees and multi-agent isolation, the Git Worktree Multi-Agent Setup Guide covers that. This article is purely practical.

Prerequisites

Four things must be installed before you begin:

• Git 2.20+ -- worktree support stabilized at this version
• Claude Code -- the --worktree (-w) flag shipped in v2.1.50
• Termdock -- for multi-panel terminal layout
• A clean main branch -- no uncommitted changes, no stale worktrees

Verify:

git --version        # git version 2.44+ recommended
claude --version     # v2.1.50 or later
git worktree list    # should show only your main working tree
git status           # clean working tree

The Scenario: An E-Commerce Sprint

Three features. Three different corners of the codebase.

1. Product search -- a search bar with category filters, price range, and full-text search against a product database
2. Shopping cart -- add/remove items, persist state across sessions with localStorage, display cart total
3. Order confirmation emails -- after checkout, send a confirmation email with order details using Resend

Why these three work in parallel: they barely overlap. Search lives in app/search/ and lib/search/. Cart lives in app/cart/ and lib/cart/. Email lives in lib/email/ and app/api/orders/. They share one file -- the Product type in types/product.ts -- and a handful of utility functions. That is it.

The less overlap, the fewer merge conflicts. The fewer merge conflicts, the more time parallelism actually saves.

Step 1: Define Shared Types First

Before spawning a single agent, commit the shared interfaces to main. This is the most effective conflict-prevention technique that exists.

Think of it as laying the foundation before the carpenters arrive. Everyone builds on the same slab.

# Create the shared Product type that all three features need
cat > types/product.ts << 'EOF'
export interface Product {
  id: string;
  name: string;
  description: string;
  price: number;
  category: string;
  imageUrl: string;
  inStock: boolean;
}

export interface CartItem {
  product: Product;
  quantity: number;
}

export interface Order {
  id: string;
  items: CartItem[];
  total: number;
  customerEmail: string;
  createdAt: Date;
}
EOF

git add types/product.ts
git commit -m "add shared types for product, cart, and order"

Now every agent branches from the same base with the same types.

Step 2: Open Termdock and Set Up 3 Panels

Open Termdock. Create a layout with three vertical panels. Each panel will run one Claude Code agent in its own worktree.

Three equal columns works best. When one agent needs attention -- it asked a question, or it finished and needs review -- drag the panel border to give it more space. Termdock's resize is instant. Drag and release.

You can also use a two-top-one-bottom layout if your screen is wider than tall. The principle is the same: all three agents must remain visible at once. If you have to tab-switch to see an agent, you will miss its questions. It will sit idle. Your parallel advantage evaporates.

Step 3: Launch 3 Agents in 3 Worktrees

In each Termdock panel, start a Claude Code session with the --worktree flag:

Panel 1 -- Product Search Agent:

claude -w feature/product-search

Once the session starts, give it the task:

Build a product search page at app/search/page.tsx. Requirements:
- Full-text search input that queries products by name and description
- Category filter dropdown (use categories from the existing seed data)
- Price range filter with min/max inputs
- Search results displayed as a grid of ProductCard components
- Server-side search using a new searchProducts function in lib/search/index.ts
- Use the Product type from types/product.ts
- Add loading states and empty state handling

Panel 2 -- Shopping Cart Agent:

claude -w feature/cart

Build a shopping cart at app/cart/page.tsx. Requirements:
- CartProvider context in lib/cart/context.tsx that wraps the app
- Add-to-cart button component for product cards
- Cart page showing all items with quantity adjustment and removal
- Persist cart to localStorage, restore on page load
- Display cart total with item count in the navbar
- Use CartItem type from types/product.ts
- Handle edge cases: item out of stock, quantity exceeding stock

Panel 3 -- Order Email Agent:

claude -w feature/order-email

Build an order confirmation email flow. Requirements:
- POST /api/orders endpoint in app/api/orders/route.ts
- Accepts cart items and customer email, creates an Order record
- Sends confirmation email using Resend (already in package.json)
- Email template in lib/email/templates/order-confirmation.tsx using React Email
- Use Order type from types/product.ts
- Include order summary, item list, and total in the email
- Add error handling for failed email sends

Three agents. Running independently. Each has its own branch, its own working directory under .claude/worktrees/, its own copy of the codebase. They cannot see each other. They cannot interfere with each other.

Step 4: Monitor from Termdock

This is where parallel development shifts from "running agents" to "managing agents." Your job is no longer to write code. Your job is to watch, answer, and intervene.

Watch for agent questions. Claude Code sometimes asks for clarification. "Should the search results use server components or client components?" Answer fast. With all three panels visible, you spot questions the moment they appear.

Watch for error spirals. If an agent hits a compilation error and starts going in circles, step in. Type a correction directly: "Stop. The Resend import is import { Resend } from 'resend', not from '@resend/node'."

Watch for completion. Agents finish at different times. The order email agent typically finishes first -- less UI work. When it commits and reports done, start reviewing its output while the other two keep running.

Termdock's workspace-level git sync helps here. You see at a glance which worktree has new commits, which has uncommitted changes, which is still being written to. No manual git status in each panel.

Step 5: Review Each Agent's Work

All three finished. Review before merging.

# In the product search worktree
cd .claude/worktrees/feature/product-search
git log --oneline main..HEAD
# a1b2c3d add search page with filters
# d4e5f6g add searchProducts function
# h7i8j9k add ProductCard component

git diff main --stat
# app/search/page.tsx         | 87 +++
# components/ProductCard.tsx  | 42 +++
# lib/search/index.ts         | 56 +++
# ... 12 files changed

# In the cart worktree
cd .claude/worktrees/feature/cart
git log --oneline main..HEAD
git diff main --stat
# app/cart/page.tsx            | 95 +++
# lib/cart/context.tsx         | 68 +++
# components/AddToCartButton.tsx | 34 +++
# ... 9 files changed

# In the order email worktree
cd .claude/worktrees/feature/order-email
git log --oneline main..HEAD
git diff main --stat
# app/api/orders/route.ts     | 45 +++
# lib/email/templates/order-confirmation.tsx | 72 +++
# ... 7 files changed

Check for obvious problems. Does each agent's code compile? Did it use the shared types correctly? Did two agents modify the same file?

Step 6: Merge in Dependency Order

Order matters. Merge the feature that others depend on first.

Here, search and cart are standalone. The order email flow references cart items. So: merge search and cart first, then order email.

# Return to your main working tree
cd ~/project

# Merge product search (standalone)
git merge feature/product-search
# Auto-merging...
# Merge made by the 'ort' strategy.

# Merge shopping cart (standalone)
git merge feature/cart
# Auto-merging...
# Merge made by the 'ort' strategy.

# Merge order email (references CartItem type, already on main)
git merge feature/order-email
# Auto-merging...
# Merge made by the 'ort' strategy.

If there are conflicts, they will almost certainly be in shared files like app/layout.tsx (multiple agents adding imports or providers) or package.json (different agents adding dependencies). These are mechanical conflicts. Seconds to resolve.

Step 7: Verify and Clean Up

Run the full test suite on main:

npm run build        # verify compilation
npm run test         # run all tests
npm run lint         # check for lint errors

Then clean up:

git worktree list
# /Users/you/project                                abc1234 [main]
# /Users/you/project/.claude/worktrees/feature/product-search  def5678 [feature/product-search]
# /Users/you/project/.claude/worktrees/feature/cart            ghi9012 [feature/cart]
# /Users/you/project/.claude/worktrees/feature/order-email     jkl3456 [feature/order-email]

# Remove worktrees
git worktree remove .claude/worktrees/feature/product-search
git worktree remove .claude/worktrees/feature/cart
git worktree remove .claude/worktrees/feature/order-email

# Delete merged branches
git branch -d feature/product-search feature/cart feature/order-email

# Prune stale references
git worktree prune

Timing Comparison

The numbers, side by side:

Parallel is not 3x faster. Each agent runs at the same speed regardless. The savings come purely from overlap. You pay a 15-minute merge-and-review tax. The net saving: 47 minutes.

This scales with feature count. Four parallel features saves more. Two saves less. Three is the sweet spot -- good throughput without overwhelming your ability to monitor.

When This Workflow Fits (and When It Doesn't)

Use parallel agents when:

• You have 2-4 features touching different parts of the codebase
• Features share types or interfaces but not implementation files
• Each feature takes 20+ minutes for a single agent (below that, merge overhead is not worth it)
• You have a terminal setup that shows all agents simultaneously

Use a single agent when:

• The task is a single-file bug fix or small refactor
• Features are deeply entangled (same files, same functions)
• You are not sure what you want yet and need interactive iteration

The 2026 AI CLI Tools Complete Guide covers how this parallel workflow fits into broader AI-assisted development patterns, including when to use different tools for different agent slots.

Troubleshooting

Agent asks about files another agent created. Agents cannot see other worktrees. Tell it explicitly: "The CartProvider is being built in a parallel worktree. Mock the cart context for now. We will integrate after merging."

Worktree creation fails with "already checked out." Each branch can only be checked out in one worktree. A previous worktree was not cleaned up. Run git worktree list to find it, then git worktree remove <path>.

Agent modifies shared config files. If two agents both update tailwind.config.ts or next.config.js, you get merge conflicts. Prevention: add shared configuration entries to main before starting agents. If conflicts happen anyway, they resolve in seconds.

Agent runs out of context mid-task. Long-running agents in complex codebases can hit context limits. Start a new session in the same worktree: cd .claude/worktrees/feature/cart && claude. The worktree preserves all progress.

Disk space concerns with large repos. Each worktree copies working files but shares the git object database. A 1 GB project with three worktrees uses roughly 3 GB of additional disk space. If tight, use sparse checkout to limit each worktree to the directories its agent needs. Claude Code's --worktree flag supports this via the worktree.sparsePaths setting.

Quick Reference: The Full Command Sequence

# 1. Commit shared types
git add types/ && git commit -m "add shared types"

# 2. Open Termdock with 3-panel layout

# 3. Launch agents (one per panel)
claude -w feature/product-search    # Panel 1
claude -w feature/cart              # Panel 2
claude -w feature/order-email       # Panel 3

# 4. Give each agent its task prompt

# 5. Monitor, answer questions, review output

# 6. Merge in order
git merge feature/product-search
git merge feature/cart
git merge feature/order-email

# 7. Verify
npm run build && npm run test

# 8. Clean up
git worktree remove .claude/worktrees/feature/product-search
git worktree remove .claude/worktrees/feature/cart
git worktree remove .claude/worktrees/feature/order-email
git branch -d feature/product-search feature/cart feature/order-email
git worktree prune

Three agents. Three worktrees. One terminal window. Setup takes two minutes. Merging takes fifteen. Everything in between runs in parallel.