parallel-worktrees

Parallel Worktrees

Run multiple AI coding sessions in parallel — each isolated in its own git worktree, pushing to its own branch, opening its own PR.

When to Use This Skill

Activate when:

• User wants to run two or more AI agents on different features/bugs at once
• User asks about git worktree for agent sessions
• User wants parallel PRs from a single repo without multiple clones
• User needs to set up, coordinate, or clean up concurrent agent workspaces

Decision Tree

What does the user need?

Start a new parallel session?
  → Create a worktree + branch (Lifecycle §1–2)
  → Open a terminal/agent session pointed at the worktree path
  → Brief the agent: "Work only in <worktree-path>. Branch: <branch-name>."

Push and open a PR?
  → git push -u origin <branch>
  → gh pr create (GitHub PR Sync reference)
  → Note related PRs in the description

Sync a worktree with the latest main?
  → Inside the worktree: git fetch origin && git rebase origin/main
  → Never merge across worktrees directly

Merge and clean up?
  → Merge PR on GitHub
  → git worktree remove <path> && git branch -d <branch>
  → git worktree prune

Hit an error?
  → "already checked out" → branch open elsewhere; use a new branch name
  → ".git/index.lock" → two processes on same worktree; one agent per worktree
  → Detached HEAD → git switch -c <new-branch> inside the worktree
  → Stale entry after dir deleted → git worktree prune

Core Concepts

Worktree vs clone — A worktree shares the same .git directory as the main checkout. No double-fetch, no disk waste. Each worktree checks out a different branch. Isolated at the filesystem level; same object store.

One agent, one worktree, one branch — This is the cardinal rule. Two agents sharing a worktree will corrupt each other's index. Two agents on the same branch will produce conflicting history.

PRs as the coordination channel — Agents communicate intent through PR titles, descriptions, and comments — not through shared files or direct worktree reads.