parallel-worktree-dev

A Claude Code / agent skill for running multiple AI coding sessions in parallel on the same git repo without stepping on each other.

Each feature lives in its own git worktree with:

• isolated working dir, branch, deps, .env.local
• auto-assigned dev port (no 3000 collisions)
• shared cross-worktree registry so AI sessions can see what siblings are touching
• pre-merge file-conflict scanner

Install

# As an agent skill (Claude Code / Codex / agentskills runtime):
npx skills add github:SnowWarri0r/parallel-worktree-dev -g

# Or just clone for the helper script alone:
git clone https://github.com/SnowWarri0r/parallel-worktree-dev ~/.local/share/parallel-worktree-dev
ln -s ~/.local/share/parallel-worktree-dev/worktree-helper.sh ~/.local/bin/wt
# (make sure ~/.local/bin is on your PATH)

Quickstart

# Inside any worktree of your target repo:
wt start feat-a               # build worktree + branch + assign port 3100
wt start feat-b               # next port 3101
wt list                       # see all active worktrees
wt check                      # scan for file overlap across worktrees
wt finish feat-a              # dry-run rebase, show conflicts (does NOT merge)
wt remove feat-a              # delete worktree + registry entry

Recommended: /feat slash command (Claude Code)

For a one-line "start a new isolated feature" workflow inside Claude Code, copy the included slash command into your user-level command directory:

mkdir -p ~/.claude/commands
cp commands/feat.md ~/.claude/commands/feat.md

Then in any Claude Code session inside your repo:

/feat user-auth          # creates worktree + branch + port for feat/user-auth
/feat user-auth main     # explicit base branch

Claude will run the helper, show you the worktree path + assigned port, and remind you to install deps before starting work.

What problem it solves

When you run two Claude / Codex sessions on the same repo:

Layer	Problem	This skill
Files	Both AIs edit foo.go, conflict surfaces only at merge	check flags overlap before merge
Resources	Both dev servers want port 3000, same .env.local, same DB	Auto-assigns ports; isolated worktree dirs
Semantics	AI A renames Foo(), AI B still writes calls to old name	Not solved — needs shared plan docs / human review

How it works

• Each start runs git worktree add to a sibling directory <repo>-wt-<name>.
• Registry lives at ~/.claude/worktree-registry/<repo-hash>.json and is shared by all worktrees (keyed off git --git-common-dir).
• Default base branch is auto-detected via origin/HEAD, falling back to main/master.
• check runs git diff --name-only <base>...HEAD per worktree, intersects pairs, prints OVERLAP warnings.
• finish uses git merge-tree --write-tree to detect conflicts without actually merging.

Config

Env var	Default	Effect
WORKTREE_PORT_BASE	3100	starting port for new worktrees

Registry is in JSON — feel free to hand-edit or wrap with your own tooling.

What it doesn't do

• DB / migration coordination — multiple worktrees still share the dev DB. Run migrations serially.
• Lockfile sync — go.sum / package-lock.json changes need manual rebase like always.
• Inter-AI awareness — AIs in different worktrees don't see each other unless you share a plan.md. This skill only surfaces filesystem-level overlap.

License

MIT