claude-task-master/docs/contributor-docs/worktree-setup.md

Git Worktree Setup for Parallel Development

Simple git worktree setup for running multiple AI coding assistants in parallel.

Why Worktrees?

Instead of Docker complexity, use git worktrees to create isolated working directories:

✅ Editor Agnostic - Works with Cursor, Windsurf, VS Code, Claude Code, etc. ✅ Simple - No Docker, no containers, just git ✅ Fast - Instant setup, shared git history ✅ Flexible - Each worktree can be on a different branch ✅ Task Master Works - Full access to .taskmaster/ in each worktree

Quick Start

1. Create a Worktree

# Using current branch as base
./scripts/create-worktree.sh

# Or specify a branch name
./scripts/create-worktree.sh feature/my-feature

This creates a worktree in ../claude-task-master-worktrees/<branch-name>/

2. Open in Your Editor

# Navigate to the worktree
cd ../claude-task-master-worktrees/auto-main/  # (or whatever branch)

# Open with your preferred AI editor
cursor .        # Cursor
code .          # VS Code
windsurf .      # Windsurf
claude          # Claude Code CLI

3. Work in Parallel

Main directory (where you are now):

# Keep working normally
git checkout main
cursor .

Worktree directory:

cd ../claude-task-master-worktrees/auto-main/
# Different files, different branch, same git repo
claude

Usage Examples

Example 1: Let Claude Work Autonomously

# Create worktree
./scripts/create-worktree.sh auto/taskmaster-work

# Navigate there
cd ../claude-task-master-worktrees/auto-taskmaster-work/

# Start Claude
claude

# In Claude session
> Use task-master to get the next task and complete it

Meanwhile in your main directory:

# You keep working normally
cursor .
# No conflicts!

Example 2: Multiple AI Assistants in Parallel

# Create multiple worktrees
./scripts/create-worktree.sh cursor/feature-a
./scripts/create-worktree.sh claude/feature-b
./scripts/create-worktree.sh windsurf/feature-c

# Terminal 1
cd ../claude-task-master-worktrees/cursor-feature-a/
cursor .

# Terminal 2
cd ../claude-task-master-worktrees/claude-feature-b/
claude

# Terminal 3
cd ../claude-task-master-worktrees/windsurf-feature-c/
windsurf .

Example 3: Test vs Implementation

# Main directory: Write implementation
cursor .

# Worktree: Have Claude write tests
cd ../claude-task-master-worktrees/auto-main/
claude -p "Write tests for the recent changes in the main branch"

How It Works

Directory Structure

/Volumes/Workspace/workspace/contrib/task-master/
├── claude-task-master/              # Main directory (this one)
│   ├── .git/                        # Shared git repo
│   ├── .taskmaster/                 # Synced via git
│   └── your code...
│
└── claude-task-master-worktrees/    # Worktrees directory
    ├── auto-main/                   # Worktree 1
    │   ├── .git -> (points to main .git)
    │   ├── .taskmaster/             # Same tasks, synced
    │   └── your code... (on branch auto/main)
    │
    └── feature-x/                   # Worktree 2
        ├── .git -> (points to main .git)
        ├── .taskmaster/
        └── your code... (on branch feature/x)

Shared Git Repository

All worktrees share the same .git:

• Commits in one worktree are immediately visible in others
• Branches are shared
• Git history is shared
• Only the working files differ

Task Master in Worktrees

Task Master works perfectly in worktrees:

# In any worktree
task-master list        # Same tasks
task-master next        # Same task queue
task-master show 1.2    # Same task data

# Changes are shared (if committed/pushed)

Recommended Workflow

Use tags to separate task contexts:

# Main directory - use default tag
task-master list

# Worktree 1 - use separate tag
cd ../claude-task-master-worktrees/auto-main/
task-master add-tag --name=claude-auto
task-master use-tag --name=claude-auto
task-master list  # Shows claude-auto tasks only

Managing Worktrees

List All Worktrees

./scripts/list-worktrees.sh

# Or directly with git
git worktree list

Remove a Worktree

# Remove specific worktree
git worktree remove ../claude-task-master-worktrees/auto-main/

# Or if there are uncommitted changes, force it
git worktree remove --force ../claude-task-master-worktrees/auto-main/

Sync Changes Between Worktrees

Changes are automatically synced through git:

# In worktree
git add .
git commit -m "feat: implement feature"
git push

# In main directory
git pull
# Changes are now available

Common Workflows

1. Autonomous Claude with Task Master

Setup:

./scripts/create-worktree.sh auto/claude-work
cd ../claude-task-master-worktrees/auto-claude-work/

Run:

# Copy the autonomous script
cp ../claude-task-master/run-autonomous-tasks.sh .

# Run Claude autonomously
./run-autonomous-tasks.sh

Monitor from main directory:

# In another terminal, in main directory
watch -n 5 "task-master list"

2. Code Review Workflow

Main directory:

# You write code
cursor .
git add .
git commit -m "feat: new feature"

Worktree:

cd ../claude-task-master-worktrees/auto-main/
git pull

# Have Claude review
claude -p "Review the latest commit and suggest improvements"

3. Parallel Feature Development

Worktree 1 (Backend):

./scripts/create-worktree.sh backend/api
cd ../claude-task-master-worktrees/backend-api/
cursor .
# Work on API

Worktree 2 (Frontend):

./scripts/create-worktree.sh frontend/ui
cd ../claude-task-master-worktrees/frontend-ui/
windsurf .
# Work on UI

Main directory:

# Monitor and merge
git log --all --graph --oneline

Tips

1. Branch Naming Convention

Use prefixes to organize:

• auto/* - For autonomous AI work
• cursor/* - For Cursor-specific features
• claude/* - For Claude-specific features
• review/* - For code review worktrees

2. Commit Often in Worktrees

Worktrees make it easy to try things:

# In worktree
git commit -m "experiment: trying approach X"
# If it doesn't work, just delete the worktree
git worktree remove .

3. Use Different npm Dependencies

Each worktree can have different node_modules:

# Main directory
npm install

# Worktree (different dependencies)
cd ../claude-task-master-worktrees/auto-main/
npm install
# Installs independently

4. .env Files

Each worktree can have its own .env:

# Main directory
echo "API_URL=http://localhost:3000" > .env

# Worktree
cd ../claude-task-master-worktrees/auto-main/
echo "API_URL=http://localhost:4000" > .env
# Different config!

Cleanup

Remove All Worktrees

# List and manually remove
./scripts/list-worktrees.sh

# Remove each one
git worktree remove ../claude-task-master-worktrees/auto-main/
git worktree remove ../claude-task-master-worktrees/feature-x/

# Or remove all at once (careful!)
rm -rf ../claude-task-master-worktrees/
git worktree prune  # Clean up git's worktree metadata

Delete Remote Branches

# After merging/done with branches
git branch -d auto/claude-work
git push origin --delete auto/claude-work

Troubleshooting

"Cannot create worktree: already exists"

# Remove the existing worktree first
git worktree remove ../claude-task-master-worktrees/auto-main/

"Branch already checked out"

Git won't let you check out the same branch in multiple worktrees:

# Use a different branch name
./scripts/create-worktree.sh auto/main-2

Changes Not Syncing

Worktrees don't auto-sync files. Use git:

# In worktree with changes
git add .
git commit -m "changes"
git push

# In other worktree
git pull

npm install Fails

Each worktree needs its own node_modules:

cd ../claude-task-master-worktrees/auto-main/
npm install

Comparison to Docker

Feature	Git Worktrees	Docker
Setup time	Instant	Minutes (build)
Disk usage	Minimal (shared .git)	GBs per container
Editor support	Native (any editor)	Limited (need special setup)
File sync	Via git	Via volumes (can be slow)
Resource usage	None (native)	RAM/CPU overhead
Complexity	Simple (just git)	Complex (Dockerfile, compose, etc.)
npm install	Per worktree	Per container
AI editor support	✅ All editors work	⚠️ Need web-based or special config

TL;DR: Worktrees are simpler, faster, and more flexible for this use case.

---

Summary

# 1. Create worktree
./scripts/create-worktree.sh auto/claude-work

# 2. Open in AI editor
cd ../claude-task-master-worktrees/auto-claude-work/
cursor .   # or claude, windsurf, code, etc.

# 3. Work in parallel
# Main directory: You work
# Worktree: AI works
# No conflicts!

Simple, fast, editor-agnostic. 🚀