next.js/.conductor/README.md

Conductor Configuration for Next.js

This directory contains Conductor configuration for parallel Claude Code agent development.

What is Conductor?

Conductor is a macOS application that orchestrates multiple Claude Code agents in parallel. Each agent gets its own isolated git worktree, enabling concurrent development on different features without branch conflicts.

Directory Structure

.conductor/
├── conductor.json      # Main configuration (used for new workspaces)
├── README.md           # This file
├── scripts/
│   ├── setup.sh        # Runs on workspace creation
│   └── run.sh          # Runs when starting work
└── <workspace>/        # Individual workspace directories (git worktrees, gitignored)

Configuration

Main Configuration (conductor.json)

The root conductor.json defines:

• scripts.setup: Runs when creating a new workspace

  • Enables corepack for pnpm
  • Validates Node.js version (18+)
  • Installs dependencies with pnpm install
  • Builds all packages with pnpm build

• scripts.run: Runs when starting work in a workspace

  • Starts watch mode (pnpm --filter=next dev) for fast iteration

• environment: Environment variables for all workspaces

  • Disables telemetry for cleaner development

• worktree: Git worktree configuration

  • Default branch to create worktrees from

Usage

Creating a New Workspace

In the Conductor app:

1. Add this repository
2. Create a new workspace with a descriptive name
3. The setup script will automatically install dependencies and build

Manual Worktree Setup

If setting up worktrees manually (without Conductor app):

# Create a new worktree from canary
git worktree add ../next.js-worktrees/my-feature -b my-feature-branch canary

# Navigate to the worktree
cd ../next.js-worktrees/my-feature

# Run the setup script (same script Conductor uses)
./.conductor/scripts/setup.sh

# Or manually:
# pnpm install --prefer-offline
# pnpm build

Managing Worktrees

View all worktrees:

git worktree list

Best Practices

Disk Space Management

• Each worktree uses ~500MB-1GB after build
• Run pnpm sweep periodically to clean Rust build artifacts
• Remove unused worktrees with git worktree remove <path>

Development Workflow

1. Never run pnpm build while pnpm dev is active (causes build corruption)
2. Use pnpm test-dev-turbo for fastest test iteration
3. Use NEXT_SKIP_ISOLATE=1 for faster test runs during development

Parallel Agent Recommendations

• Limit to 3-4 concurrent agents to avoid:
  • GitHub API rate limits
  • Disk space exhaustion
  • System resource contention

Troubleshooting

Build Corruption

If builds become corrupted:

# Kill any running dev processes
pkill -f "pnpm dev"

# Clean and rebuild
pnpm clean
pnpm install
pnpm build

Worktree Issues

# List worktrees with status
git worktree list

# Prune stale worktree references
git worktree prune

# Remove a worktree
git worktree remove <path>

Related Documentation

• Conductor App
• Git Worktrees
• Next.js Contributing Guide