Implementing Worktree-Based Concurrent Local Environments

This skill helps you implement a system for running multiple local development environments simultaneously using git worktrees. It is meant to be adapted to any repository, regardless of tech stack or database engine.

The assets/ directory contains template scripts (setup-worktree.mjs, dev-agent.mjs) and a template for agent documentation. The scripts are annotated with ADAPT comments to highlight what needs changing.

The Problem

When you work on multiple branches at the same time (or when AI agents work in parallel), you need isolated environments. Git worktrees give you isolated code, but that's not enough: each environment also needs its own ports, its own database, and its own config files. Without automation, setting this up manually for every branch is tedious and error-prone.

Core Concepts

Shared vs per-worktree gitignored directories

The first thing to decide is: for each gitignored directory in your project, should it be shared across worktrees or isolated per worktree?

• Shared directories are symlinked in worktrees (pointing to the main worktree). They contain things that should be the same everywhere: the slot registry, personal notes, task plans, etc.
• Per-worktree directories are created independently in each worktree. They contain things that must differ: databases, caches, logs, PID files, Docker volumes, etc.