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.

Layout Convention

Keep worktrees as siblings of the repo root to avoid .gitignore noise:

~/projects/
  myrepo/              ← main checkout (main branch)
  myrepo-wt/           ← worktree root (sibling dir)
    feat/auth/         ← worktree for branch feat/auth
    fix/login-bug/     ← worktree for branch fix/login-bug

Lifecycle

1. Create a worktree

# New branch (most common)
git worktree add ../myrepo-wt/feat/auth -b feat/auth

# From an existing remote branch
git worktree add ../myrepo-wt/fix/login-bug origin/fix/login-bug

2. Brief the agent

Give the agent its workspace clearly:

Working directory: /home/user/projects/myrepo-wt/feat/auth
Branch: feat/auth
Scope: implement JWT authentication — do not touch files outside this scope

The agent operates entirely within this directory. It should have no awareness of other worktrees.

3. Work and commit

Normal git flow inside the worktree — the agent uses git add, git commit as usual. The branch is isolated from main and all sibling worktrees.

4. Push and open PR

git push -u origin feat/auth
gh pr create \
  --title "feat(auth): implement JWT login" \
  --body "Parallel session. Related: #<pr-number> (if any)."

See references/github-pr-sync.md for draft PRs, PR templates, and linking.

5. Sync with main

# Inside the worktree
git fetch origin
git rebase origin/main   # keep history linear

Run this before opening a PR and before the final merge.

6. Merge and clean up

After the PR merges on GitHub:

# From the main repo (not inside the worktree)
git worktree remove ../myrepo-wt/feat/auth
git branch -d feat/auth
git worktree prune          # removes stale metadata entries

Branch Naming

Use a consistent pattern so agents (and humans) can parse ownership at a glance:

<type>/<scope>/<short-description>

feat/auth/jwt-login
fix/api/null-pointer
chore/deps/upgrade-pnpm
agent/experiment/refactor-parser   ← for exploratory agent sessions

Pitfalls

Symptom	Cause	Fix
fatal: 'branch' is already checked out	Branch open in another worktree	Use a new branch name
.git/index.lock errors	Two processes on same worktree	One agent per worktree
Detached HEAD	Created from a commit SHA, not a branch	git switch -c <new-branch>
Worktree path gone after reboot	Dir deleted externally	git worktree prune, then recreate
git worktree list shows stale entries	Dir removed without git worktree remove	git worktree prune
Agent edits files in main checkout	Agent not scoped to worktree path	Re-brief agent with explicit working directory

References

Read these when you need more depth:

• references/worktree-lifecycle.md — Full command reference, flags, edge cases (multiple worktrees, bare repos, moving worktrees)
• references/github-pr-sync.md — PR creation, draft PRs, linking, status checks, merge strategies via gh CLI
• references/agent-coordination.md — Patterns for coordinating output across parallel sessions: sequencing, handoffs, shared state via PRs

Setup & Activation

npx skills add -g onsager-ai/dev-skills --skill parallel-worktrees -a claude-code -y

Auto-activates when: user mentions "worktree", "parallel agents", "multiple agent sessions", or asks to work on several features simultaneously with AI.