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

What You Get: 3 Features Built in 40 Minutes

Here is the end state. Three features for a Next.js e-commerce app, built in parallel, merged cleanly, all tests passing:

Total wall-clock time: 40 minutes. Sequential time for the same work: roughly 2 hours. The time savings come from running all three agents simultaneously, each in its own isolated worktree, monitored from a single Termdock window with three side-by-side panels.

This article walks through exactly how to set up that session, what to type in each terminal, and how to merge the results. If you want the theory behind git worktrees and multi-agent isolation, that is covered in the Git Worktree Multi-Agent Setup Guide. This article is purely practical.

Prerequisites

You need four things installed before starting:

• Git 2.20+ — worktree support is stable from this version onward
• Claude Code — with the --worktree (-w) flag, available since v2.1.50
• Termdock — for multi-panel terminal layout
• A clean main branch — no uncommitted changes, no stale worktrees

Verify your setup:

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

You are building three features for a Next.js e-commerce application. The features are:

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 cart state across sessions using localStorage, display cart total
3. Order confirmation emails — after checkout, send a confirmation email with order details using Resend

These three features are ideal for parallel development because they touch different parts of the codebase. Product search lives in app/search/ and lib/search/. The cart lives in app/cart/ and lib/cart/. Email lives in lib/email/ and app/api/orders/. The overlap is minimal: they share the Product type from types/product.ts and a few utility functions.

Step 1: Define Shared Types First

Before spawning agents, commit any shared interfaces to main. This is the single most effective way to prevent merge conflicts later.

# 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 available.

Step 2: Open Termdock and Set Up 3 Panels

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

The layout that works best for three agents: split the window into three equal columns. When one agent needs more attention (it asked a question, or it finished and needs review), drag the panel border to give it more space. Termdock's drag-and-drop resize makes this instant.

You can also use a 2-top-1-bottom layout if your screen is wider than it is tall. The key is that all three agents remain visible simultaneously. If you have to tab-switch to see an agent, you will miss its questions and it will sit idle.

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

All three agents are now running independently. Each has its own branch, its own working directory under .claude/worktrees/, and its own copy of the codebase files. They cannot see or interfere with each other's changes.

Step 4: Monitor from Termdock

This is where Termdock earns its place in the workflow. With three agents running, your job shifts from writing code to monitoring progress and answering questions.

What to watch for across the three panels:

Agent questions. Claude Code will sometimes ask for clarification. "Should I use server components or client components for the search results?" Answer quickly so the agent does not block. With all three panels visible, you spot questions immediately.

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

Completion status. Agents finish at different times. The order email agent typically finishes first (less UI work). When you see it commit and report done, you can start reviewing its output while the other two are still working.

Termdock's workspace-level git sync is useful here. You can see at a glance which worktree has new commits, which has uncommitted changes, and which is still actively being written to. No need to run git status in each panel manually.

Step 5: Review Each Agent's Work

Once all three agents finish, review before merging. In each panel (or in the Termdock panel for that worktree):

# 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 the agent use the shared types correctly? Are there any files that two agents both modified?

Step 6: Merge in Dependency Order

The merge order matters. Merge the feature that other features depend on first.

In this scenario, the features are mostly independent, but there is a natural ordering: search and cart are standalone, while the order email flow references cart items. 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 are almost certainly in shared files like app/layout.tsx (multiple agents adding imports or providers) or package.json (different agents adding dependencies). These are mechanical conflicts that resolve in seconds.

Step 7: Verify and Clean Up

Run the full test suite on main to confirm everything works together:

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

Then clean up the worktrees:

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

Here is the real comparison between sequential and parallel development for these three features:

The parallel approach is not 3x faster. Each agent runs at the same speed whether alone or alongside others. The savings come from the overlap: while agent 1 is building search, agents 2 and 3 are simultaneously building cart and email. You pay a merge-and-review tax of about 15 minutes, but the net savings are substantial.

The 47% time savings scales with the number of independent features. Four features in parallel saves more. Two features saves less. The sweet spot is 3 parallel agents, which balances throughput against monitoring complexity.

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

Use parallel agents when:

• You have 2-4 features that touch different parts of the codebase
• The features share types or interfaces but not implementation files
• Each feature takes 20+ minutes for a single agent (below that, the 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 to iterate interactively

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. The agent cannot see files in other worktrees. Tell it explicitly: "The CartProvider is being built in a parallel worktree. For now, mock the cart context and we will integrate after merging."

Worktree creation fails with "already checked out." Each branch can only be checked out in one worktree. If you see this error, a previous worktree for that branch 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 will get merge conflicts. Prevention: before starting agents, add any shared configuration entries to main. If conflicts happen anyway, they are trivial to resolve manually.

Agent runs out of context mid-task. Long-running agents in complex codebases can hit context limits. If an agent loses track, 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 the working files but shares the git object database. For a 1 GB project, three worktrees use roughly 3 GB of additional disk space. If this is 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. The setup takes two minutes. The merge takes fifteen. Everything in between runs in parallel.