Parallel Git Worktrees: Run Multiple Agents Without Clashes

The problem

Running multiple checkouts of the same repository leads to port collisions, database schema corruption from competing migrations, and session clobbering. Developers and AI agents often lose hours when one workspace silently adopts the resources or runtime state of another.

What it does

• Orchestrates Git worktrees as isolated lanes with dedicated port blocks to prevent EADDRINUSE errors.
• Configures per-worktree environment overrides for databases, caches, and search indices to stop data cross-contamination.
• Manages runtime version pinning and dependency installation for each checkout to ensure version consistency.
• Provides automated scripts for lane creation, port registration, and clean teardown of worktree metadata.
• Handles session isolation for shared backends to prevent one lane from logging another out.

Frameworks & tools

Git, Bash, Node.js (Vite, Next.js, Webpack), Python, Ruby on Rails, Django, Docker Compose, and version managers like nvm or asdf.

Why this beats prompting it yourself

Manually setting up worktrees usually skips the non-obvious "shared mutable state" like HMR ports or database migrations. This skill enforces a rigorous isolation checklist and port-allocation registry that prevents hard-to-debug runtime failures that generic prompts ignore.

Use cases

• Working on a high-priority hotfix without stashing or switching away from a complex feature branch.
• Deploying a fleet of AI agents to work on independent tasks within the same repository.
• Comparing two versions of a frontend UI side-by-side on different local ports.
• Running integration tests on a feature branch while keeping a stable dev server active on main.

Known limitations

On Windows, nvm-windows cannot switch Node versions per shell, limiting concurrent lanes to a single global Node version. Requires manual pruning if worktree directories are deleted via file explorer.