Skip to main content

​
Git Worktrees & Cursor Worktrees: The Elite Developer’s Guide (Nov 2025)

​
TL;DR - Why This Matters

Traditional Workflow:
  • One branch at a time
  • Stash or commit unfinished work to switch contexts
  • Wait for CI/CD to validate changes
  • AI agents block each other
  • Context switching kills productivity
Elite Worktrees Workflow:
  • Multiple branches simultaneously in separate directories
  • AI agents work in parallel without conflicts
  • Instant context switching (just switch folders)
  • Test branches side-by-side
  • No stashing, no conflicts, no waiting

​
Part 1: Git Worktrees (The Foundation)

​
What Are Git Worktrees?

Git worktrees let you check out multiple branches from the same repository into different directories, all sharing the same Git history. Traditional Git: 
~/projects/sanctiv-app/     # One directory, one branch at a time
With Worktrees: 
~/projects/sanctiv-app/                    # Main worktree (main branch)
~/.cursor/worktrees/sanctiv-app/feature-1/ # Feature 1 branch
~/.cursor/worktrees/sanctiv-app/bugfix-2/  # Bugfix 2 branch
~/.cursor/worktrees/sanctiv-app/ai-exp-3/  # AI experiment branch
Each directory is a separate working copy but shares the same .git repository.

​
Why Git Created This

Problems Git Worktrees Solve:
  1. Context Switching Hell
    • OLD: Stash → switch branch → unstash → pray nothing broke
    • NEW: cd to different worktree folder
  2. Testing Multiple Branches
    • OLD: Switch branches repeatedly to compare
    • NEW: Open both folders side-by-side
  3. Code Review While Developing
    • OLD: Commit work-in-progress to switch to review branch
    • NEW: Keep dev worktree open, review in another worktree
  4. CI/CD Testing Locally
    • OLD: Can only test one branch at a time
    • NEW: Run tests in parallel across worktrees

​
Git Worktree Commands

# Create new worktree for feature branch
git worktree add ~/.cursor/worktrees/sanctiv-app/feature-auth feature-auth

# Create worktree with new branch
git worktree add -b bugfix-123 ~/.cursor/worktrees/sanctiv-app/bugfix-123

# List all worktrees
git worktree list

# Remove worktree (after deleting branch)
git worktree remove ~/.cursor/worktrees/sanctiv-app/old-feature

# Cleanup stale worktrees
git worktree prune

​
Real-World Git Worktree Use Cases

​
Use Case 1: Emergency Hotfix During Feature Development

# You're deep in feature work (main worktree)
cd ~/projects/sanctiv-app
# lots of uncommitted changes...

# Production is down! Need hotfix NOW
git worktree add ~/.cursor/worktrees/sanctiv-app/hotfix-prod hotfix

# Work on hotfix in separate worktree
cd ~/.cursor/worktrees/sanctiv-app/hotfix-prod
# Fix, test, commit, push

# Back to feature work - nothing disturbed!
cd ~/projects/sanctiv-app

​
Use Case 2: Side-by-Side Branch Comparison

# Create worktrees for branches to compare
git worktree add ~/.cursor/worktrees/sanctiv-app/approach-a approach-a
git worktree add ~/.cursor/worktrees/sanctiv-app/approach-b approach-b

# Run both apps simultaneously
# Terminal 1:
cd ~/.cursor/worktrees/sanctiv-app/approach-a && npm start

# Terminal 2:
cd ~/.cursor/worktrees/sanctiv-app/approach-b && npm start

# Compare behavior side-by-side in iOS simulator

​
Part 2: Cursor Worktrees (The AI Superpower)

​
What Cursor Adds to Git Worktrees

Cursor (Nov 2025) takes Git worktrees and supercharges them for agentic, AI-first development:
  1. AI Agent Isolation - Each agent works in its own worktree
  2. Parallel AI Execution - Multiple AI agents work simultaneously
  3. Auto-Setup Scripts - Worktrees auto-configure on creation
  4. Context Preservation - Each worktree maintains separate AI context
  5. Smart Handoffs - AI agents can pass work between worktrees

​
Cursor Worktrees Configuration (.cursor/worktrees.json)

This file defines setup scripts that run when creating new worktrees. Why This Matters: When you (or an AI agent) creates a new worktree, it needs:
  • Dependencies installed (bun install)
  • Linting configured
  • Environment validated
  • Tests passing
Without configuration, every new worktree is a blank slate requiring manual setup. With .cursor/worktrees.json: 
{
  "setup-worktree": [
    "bun install",
    "bun run lint:md:fix",
    "echo '✅ Worktree ready'"
  ]
}
Now every new worktree is instantly ready for development.

​
Elite Cursor Worktrees Workflows (Nov 2025)

​
Workflow 1: Parallel AI Agents

Scenario: You need to implement 3 features simultaneously for a sprint deadline. 
# Create 3 worktrees with 3 branches
cursor worktree create feature-auth
cursor worktree create feature-payments  
cursor worktree create feature-analytics

# Each auto-runs setup-worktree:
# → bun install
# → lint:md:fix
# → Ready for AI agent

# Assign AI agents to each worktree
# Agent 1: feature-auth worktree → implement OAuth
# Agent 2: feature-payments worktree → implement Stripe
# Agent 3: feature-analytics worktree → implement tracking

# All agents work in parallel without conflicts!
Result: 3 features completed in parallel, 3x faster than sequential.

​
Workflow 2: AI Experiment Branching

Scenario: Try 3 different AI-generated approaches to a problem. 
# Create experiment worktrees
cursor worktree create experiment-approach-a
cursor worktree create experiment-approach-b
cursor worktree create experiment-approach-c

# Give same prompt to 3 different AI models
# Each works in isolated worktree
# Compare results side-by-side
# Keep the best, discard the rest

​
Workflow 3: Code Review + Development

Scenario: You need to review a PR while continuing feature work. 
# Your main work (feature development)
cd ~/projects/sanctiv-app  # main worktree

# PR comes in for review
cursor worktree create review-pr-456

# Review in separate worktree
cd ~/.cursor/worktrees/sanctiv-app/review-pr-456
# Test PR, leave comments

# Switch back to your work - no context loss
cd ~/projects/sanctiv-app

​
Workflow 4: Multi-Version Testing

Scenario: Test that a feature works on multiple release branches. 
# Create worktrees for each release branch
git worktree add ~/.cursor/worktrees/sanctiv-app/v1.0 release-v1.0
git worktree add ~/.cursor/worktrees/sanctiv-app/v2.0 release-v2.0
git worktree add ~/.cursor/worktrees/sanctiv-app/v3.0 release-v3.0

# Cherry-pick bugfix to all versions
cd ~/.cursor/worktrees/sanctiv-app/v1.0 && git cherry-pick abc123
cd ~/.cursor/worktrees/sanctiv-app/v2.0 && git cherry-pick abc123
cd ~/.cursor/worktrees/sanctiv-app/v3.0 && git cherry-pick abc123

# Test all versions in parallel

​
Part 3: Elite Cursor Worktrees Configurations

​
Our Configuration Breakdown

{
  "setup-worktree": [
    "bun install",              // Install dependencies fresh
    "bun run lint:md:fix",      // Auto-fix markdown
    "echo '✅ Worktree ready'"  // Confirmation
  ]
}
Runs when: New worktree is created Purpose: Zero-config worktree setup Time saved: ~2-5 minutes per worktree

​
Pre-Commit Check Configuration

{
  "pre-commit-check": [
    "bun run typecheck",
    "bun run lint",
    "bun run lint:md",
    "echo '✅ Ready to commit'"
  ]
}
Runs when: Developer runs pre-commit validation Purpose: Catch issues before committing Prevents: Failed CI/CD, rejected PRs

​
Full Validation Configuration

{
  "full-validation": [
    "bun install",
    "npx expo-doctor",
    "bun run typecheck",
    "bun run lint",
    "bun run lint:md",
    "bun run test:e2e:smoke",
    "echo '✅ Ready to push'"
  ]
}
Runs when: Before pushing to GitHub Purpose: Comprehensive validation Ensures: Green builds, first-time PR approval

​
AI Handoff Configuration

{
  "ai-handoff": [
    "bun run typecheck",
    "bun run lint",
    "bun run lint:md",
    "git status",
    "echo '✅ Validated for AI handoff'"
  ]
}
Runs when: AI agent completes work Purpose: Validate AI output before human review Ensures: Clean handoffs between agents/humans

​
Part 4: How Elite Teams Use This (Nov 2025)

​
Pattern 1: The Parallel Sprint

Team Structure:
  • 1 Product Manager
  • 1 Human Developer (you)
  • 5 AI Agents (via Cursor)
Sprint Setup: 
# PM defines 5 user stories

# Create 5 worktrees (one per story)
cursor worktree create story-1-auth
cursor worktree create story-2-payments
cursor worktree create story-3-analytics
cursor worktree create story-4-notifications
cursor worktree create story-5-profile

# Assign 1 AI agent per worktree
# Each agent works independently
# You review completed work in each worktree

# Result: 5 features in parallel = 5x velocity

​
Pattern 2: The Experiment Matrix

Scenario: Unsure of best technical approach 
# Create matrix of experiments
cursor worktree create exp-graphql
cursor worktree create exp-rest
cursor worktree create exp-trpc

cursor worktree create exp-postgres
cursor worktree create exp-mongodb
cursor worktree create exp-supabase

# AI agents implement each combination
# You test all 9 permutations
# Data-driven decision on architecture

​
Pattern 3: The Review Pipeline

Scenario: High-velocity team with constant PRs 
# Main worktree: Your active development
~/projects/sanctiv-app

# Review worktrees: One per PR
~/.cursor/worktrees/sanctiv-app/review-pr-101
~/.cursor/worktrees/sanctiv-app/review-pr-102
~/.cursor/worktrees/sanctiv-app/review-pr-103

# You can review 3 PRs simultaneously
# Without disturbing your main work
# Each review environment is isolated

​
Pattern 4: The Hotfix Factory

Scenario: Production issues need immediate fixes 
# Production down? Create hotfix worktree
cursor worktree create hotfix-prod-123

# Staging broken? Create separate worktree  
cursor worktree create hotfix-staging-456

# Both fixed in parallel
# Neither affects main development

​
Part 5: Cursor-Specific Advantages (Nov 2025)

​
1. AI Context Isolation

Problem: AI agents share context = confused responses Cursor Solution: Each worktree has isolated AI context
  • Agent A in worktree 1: Context about feature-auth
  • Agent B in worktree 2: Context about feature-payments
  • No cross-contamination

​
2. Automated Worktree Scripts

Problem: Manual setup for each worktree is tedious Cursor Solution: .cursor/worktrees.json auto-runs scripts
  • setup-worktree: Auto-runs on creation
  • pre-commit-check: One command validation
  • ai-handoff: Validates AI output

​
3. Visual Worktree Management

Problem: Terminal commands are hard to track Cursor Solution: Visual worktree panel (Nov 2025)
  • See all worktrees at a glance
  • One-click switching
  • Status indicators (clean, dirty, running tests)
  • AI agent assignments visible

​
4. Intelligent Agent Routing

Problem: Assigning agents to worktrees manually Cursor Solution: Smart agent routing
  • “Claude, work on feature-auth in its worktree”
  • Cursor automatically routes to correct worktree
  • Agent inherits worktree context

​
Part 6: Common Pitfalls & Solutions

​
Pitfall 1: Forgetting Which Worktree You’re In

Problem: Make changes in wrong worktree Solution: 
# Add to shell prompt
PS1='[\W ($(git branch --show-current))]$ '

# Or use Cursor's visual indicator
# Bottom-left shows: "worktree: feature-auth"

​
Pitfall 2: Node Modules Bloat

Problem: Each worktree has its own node_modules = disk space explosion Solution: 
# Use pnpm or bun (shared dependencies)
# Or use symlinks for node_modules

# Calculate disk usage
du -sh ~/.cursor/worktrees/sanctiv-app/*/node_modules

​
Pitfall 3: Stale Worktrees

Problem: Old worktrees pile up after branches are merged Solution: 
# Regular cleanup
git worktree list
git worktree remove old-feature
git worktree prune

# Add to weekly routine

​
Pitfall 4: Conflicting Ports

Problem: Multiple worktrees try to use same port (8081) Solution: 
# Worktree 1: PORT=8081 npm start
# Worktree 2: PORT=8082 npm start
# Worktree 3: PORT=8083 npm start

# Add to worktree config
{
  "setup-worktree": [
    "bun install",
    "echo 'PORT=$((8081 + RANDOM % 100))' > .env"
  ]
}

​
Part 7: Your Worktree Configuration Explained

​
Configuration 1: setup-worktree

What it does: Prepares new worktree for immediate use 
{
  "setup-worktree": [
    "bun install",              // Fresh dependencies
    "bun run lint:md:fix",      // Auto-fix docs
    "echo '✅ Worktree ready'"  // Confirmation
  ]
}
When to run:
  • Automatically on worktree creation
  • After pulling latest changes
  • When switching to old worktree
Time saved: 2-3 minutes per worktree

​
Configuration 2: validate-worktree

What it does: Comprehensive validation suite 
{
  "validate-worktree": [
    "bun install",
    "bun run typecheck",
    "bun run lint",
    "bun run lint:md",
    "echo '✅ All checks passed'"
  ]
}
When to run:
  • Before starting work in worktree
  • After AI agent completes work
  • When unsure if worktree is healthy
Catches: Type errors, linting issues, doc problems

​
Configuration 3: pre-commit-check

What it does: Fast pre-commit validation 
{
  "pre-commit-check": [
    "bun run typecheck",
    "bun run lint",
    "bun run lint:md",
    "echo '✅ Ready to commit'"
  ]
}
When to run:
  • Before every commit
  • In pre-commit hook (optional)
Prevents: Committing broken code

​
Configuration 4: full-validation

What it does: CI/CD-level validation locally 
{
  "full-validation": [
    "bun install",
    "npx expo-doctor",
    "bun run typecheck",
    "bun run lint",
    "bun run lint:md",
    "bun run test:e2e:smoke",
    "echo '✅ Ready to push'"
  ]
}
When to run:
  • Before pushing to GitHub
  • Before creating PR
  • After major changes
Ensures: Green CI/CD, first-time PR approval

​
Configuration 5: ai-handoff

What it does: Validates AI agent output 
{
  "ai-handoff": [
    "bun run typecheck",
    "bun run lint",
    "bun run lint:md",
    "git status",
    "echo '✅ Validated for handoff'"
  ]
}
When to run:
  • After AI agent completes task
  • Before reviewing AI changes
  • When switching from AI to human
Ensures: Clean code from AI agents

​
Part 8: Advanced Patterns

​
Pattern 1: The Worktree Matrix

Goal: Test all combinations of features 
# Create grid of worktrees
for feature_a in v1 v2; do
  for feature_b in enabled disabled; do
    name="matrix-${feature_a}-${feature_b}"
    cursor worktree create $name
    cd ~/.cursor/worktrees/sanctiv-app/$name
    # Configure feature flags
  done
done

# Result: 4 worktrees testing all combinations

​
Pattern 2: The Rolling Review

Goal: Review PRs as fast as they come in 
# Script: review-pr.sh
#!/bin/bash
PR=$1
cursor worktree create review-pr-$PR
cd ~/.cursor/worktrees/sanctiv-app/review-pr-$PR
gh pr checkout $PR
cursor worktree run validate-worktree
cursor .  # Open in Cursor

# Usage: ./review-pr.sh 456

​
Pattern 3: The Performance Lab

Goal: Compare performance across branches 
# Create worktrees for branches to compare
cursor worktree create perf-baseline
cursor worktree create perf-optimized

# Run benchmarks in each
cd ~/.cursor/worktrees/sanctiv-app/perf-baseline
bun run benchmark > baseline.txt

cd ~/.cursor/worktrees/sanctiv-app/perf-optimized
bun run benchmark > optimized.txt

# Compare results
diff baseline.txt optimized.txt

​
Part 9: Integration with Sanctiv Workflow

​
Sanctiv-Specific Worktree Usage

​
Use Case 1: Multi-Church Testing

# Create worktrees for different church configs
cursor worktree create church-small-config
cursor worktree create church-medium-config
cursor worktree create church-large-config

# Each worktree configured with different org_id
# Test RLS policies in isolation

​
Use Case 2: Guided Journal Experiments

# Try 3 different guided journal UX approaches
cursor worktree create journal-ux-v1
cursor worktree create journal-ux-v2
cursor worktree create journal-ux-v3

# Run user testing in parallel
# Choose winner based on data

​
Use Case 3: Dashboard + Mobile Sync

# Main worktree: Mobile app development
~/projects/sanctiv-app

# Separate worktree: Dashboard (web)
~/.cursor/worktrees/sanctiv-app/dashboard

# Both running simultaneously
# Test real-time sync between them

​
Part 10: The Future (2025+)

​
Cursor’s Worktree Roadmap

Based on Nov 2025 trajectory:
  1. AI Agent Pools
    • Pre-configured agent teams per worktree
    • Auto-assignment based on task type
  2. Cross-Worktree Refactoring
    • Make change in one worktree
    • Automatically propagate to others
  3. Worktree Templates
    • Pre-built worktree configs for common patterns
    • One-click setup for microservices, monorepos
  4. Visual Dependency Graphs
    • See how worktrees relate to each other
    • Understand merge order automatically
  5. Cloud Worktrees
    • Worktrees in cloud = instant access anywhere
    • No local disk space issues

​
Summary: The Elite Mindset

Old Way (Single Branch):
  • Linear development
  • Context switching overhead
  • One thing at a time
  • Stash hell
Elite Way (Worktrees):
  • Parallel development
  • Zero context switching
  • Multiple things simultaneously
  • No stashing ever
With AI Agents (Cursor + Worktrees):
  • 5-10x velocity
  • Experiment fearlessly
  • Data-driven decisions
  • Human reviews, AI implements

​
Quick Reference

​
Essential Commands

# Create worktree
cursor worktree create <name>
git worktree add <path> <branch>

# List worktrees
cursor worktree list
git worktree list

# Remove worktree
cursor worktree remove <name>
git worktree remove <path>

# Run configuration
cursor worktree run setup-worktree
cursor worktree run pre-commit-check

​
When to Use Each Configuration

ConfigurationWhen to UseTime Saved
setup-worktreeCreating new worktree2-3 min
validate-worktreeAfter AI agent work1-2 min
pre-commit-checkBefore committing30 sec
smoke-testQuick validation1 min
full-validationBefore pushing3-5 min
quick-fixAuto-fix linting10 sec
clean-installDependencies broken1-2 min
test-criticalFast critical checks1 min
validate-docsDocs changes10 sec
ai-handoffAfter AI completes30 sec

​
The Bottom Line

Worktrees = Multiple Realities Each worktree is a parallel universe where:
  • Different code exists
  • Different experiments run
  • Different AI agents work
  • Different tests execute
And they all share the same Git history. This is how elite teams ship fast in 2025.
Last Updated: November 19, 2025
For: Sanctiv Development Team
Context: Cursor AI + Git Worktrees Integration