Worktree
Managing git worktrees for isolated parallel development. Use when creating branches, setting up agent worktrees, or cleaning up after merges.From its SKILL.md
npx -y skills add rmzi/portable-dev-system --skill worktreeAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 24 stars24 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
9.9 KB, as published. Nobody here has run it
/worktree — Isolated Parallel Development
Each stream of work gets its own directory. No stashing, no branch switching, no lost context.
Issue-tied creation (default)
Every meaningful branch should be tied to a GitHub tracking issue so /pds:finish can post a canonical dev diary comment. Branch names must encode the issue number:
<type>/<issue>-<slug>
# examples
feat/89-cg-receive
fix/132-tmux-socket
refactor/108-backpressure
Invoke with an issue number and (optional) type:
/pds:worktree <issue-number> [type]
Protocol:
- Resolve
REPO_ROOT(see Path Resolution below). gh issue view <N> --json title -q .titleto fetch the issue title.- Slugify the title: lowercase, alphanumerics and hyphens only, collapse runs, truncate to ~40 chars.
- Compose the branch name:
<type>/<N>-<slug>(defaulttype=featif omitted; usefixfor bug issues,refactorfor cleanup, etc.). - Create the worktree:
git worktree add "$REPO_ROOT/.worktrees/<type>-<N>-<slug>" -b <type>/<N>-<slug> cdinto the worktree.
Fail fast if gh issue view <N> returns no issue — do not fabricate a branch name from a stale or wrong number.
Fallback: free-form creation
For spike exploration, PR review, or other work that genuinely has no tracking issue, the raw git worktree add forms below remain supported. /pds:finish will prompt for an issue number at ship time if it encounters a branch without the <type>/<issue>-<slug> pattern.
Commands
REPO_ROOT="$(git rev-parse --path-format=absolute --git-common-dir | sed 's|/.git$||')"
git worktree list # List worktrees
git worktree add "$REPO_ROOT/.worktrees/dir" branch # Create from existing branch
git worktree add "$REPO_ROOT/.worktrees/dir" -b new-branch # Create with new branch
git worktree remove "$REPO_ROOT/.worktrees/dir" # Remove worktree
git worktree prune # Clean stale references
Naming Convention
Worktrees live inside the repo at .worktrees/:
project/ # main worktree (main/master)
project/.worktrees/feature-auth/ # feature work
project/.worktrees/hotfix-login/ # urgent fix
project/.worktrees/pr-123/ # reviewing a PR
Pattern: project/.worktrees/{branch-with-slashes-as-dashes}
.worktrees/ is auto-added to .gitignore on first use.
Path Resolution
When running inside a worktree, relative .worktrees/ paths create nested directories instead of sibling worktrees at the repo root. Always resolve REPO_ROOT first:
REPO_ROOT="$(git rev-parse --path-format=absolute --git-common-dir | sed 's|/.git$||')"
This uses git plumbing to find the shared .git directory (which always lives in the main repo), then strips the /.git suffix. It's idempotent — returns the same path from both the main repo and any worktree. Requires Git 2.13+.
Then use "$REPO_ROOT/.worktrees/" in all commands.
Why this approach?
| Alternative | Problem |
|---|---|
git rev-parse --show-toplevel | Returns the current worktree root, not the main repo root — exactly the bug this fixes |
dirname $(git rev-parse --git-common-dir) | Community pattern (anthropics/claude-code#1052) — same idea, but without --path-format=absolute it returns .git (relative) from the main repo, making dirname return . which is fragile |
git worktree list | head -1 | awk '{print $1}' | Works but slower (lists all worktrees), relies on output formatting |
Sibling directories (../project-feature) | Official Claude Code docs pattern — avoids the problem entirely but PDS uses .worktrees/ for organization |
We use --path-format=absolute to guarantee an absolute path regardless of where the command runs, combined with --git-common-dir to always resolve to the main repo's .git directory.
Workflow
REPO_ROOT="$(git rev-parse --path-format=absolute --git-common-dir | sed 's|/.git$||')"
# Start feature work
git worktree add "$REPO_ROOT/.worktrees/feature-user-profiles" -b feature/user-profiles
cd "$REPO_ROOT/.worktrees/feature-user-profiles"
# Urgent bug — new worktree, no context lost
git worktree add "$REPO_ROOT/.worktrees/hotfix-critical" -b hotfix/critical-fix
cd "$REPO_ROOT/.worktrees/hotfix-critical"
# Fix bug, PR, merge, clean up
git worktree remove "$REPO_ROOT/.worktrees/hotfix-critical"
git branch -d hotfix/critical-fix
Patterns
Review a PR without losing context
REPO_ROOT="$(git rev-parse --path-format=absolute --git-common-dir | sed 's|/.git$||')"
git fetch origin pull/123/head:pr-123
git worktree add "$REPO_ROOT/.worktrees/pr-123" pr-123
# Review, test, done
git worktree remove "$REPO_ROOT/.worktrees/pr-123"
git branch -d pr-123
Explore without fear
REPO_ROOT="$(git rev-parse --path-format=absolute --git-common-dir | sed 's|/.git$||')"
git worktree add "$REPO_ROOT/.worktrees/spike-idea" -b spike/crazy-idea
# If good: merge. If bad: remove worktree + delete branch
git worktree remove "$REPO_ROOT/.worktrees/spike-idea"
git branch -D spike/crazy-idea
Parallel feature development
REPO_ROOT="$(git rev-parse --path-format=absolute --git-common-dir | sed 's|/.git$||')"
git worktree add "$REPO_ROOT/.worktrees/feature-api" -b feature/api
git worktree add "$REPO_ROOT/.worktrees/feature-ui" -b feature/ui
# Work on API in one terminal, UI in another
# Each has its own index, HEAD, and uncommitted changes
Agent worktrees
REPO_ROOT="$(git rev-parse --path-format=absolute --git-common-dir | sed 's|/.git$||')"
# Create worktrees for multi-agent work (see /swarm)
git worktree add "$REPO_ROOT/.worktrees/task-1-auth" -b task-1/auth
git worktree add "$REPO_ROOT/.worktrees/task-2-api" -b task-2/api
# Each agent gets its own isolated environment
# Use TaskCreate/Task tool for agent dispatch (see /pds:swarm)
Garbage Collection
Invoke as /pds:worktree gc to detect and remove stale worktrees.
What Counts as Stale
| Type | Detection | Removal |
|---|---|---|
| Orphan | Directory in .worktrees/ not in git worktree list (broken git metadata) | rm -rf <path> (git doesn't know about it) |
| Merged branch | Worktree whose branch is already merged to main | git worktree remove <path> + git branch -d <branch> |
GC Protocol
-
Resolve repo root:
REPO_ROOT="$(git rev-parse --path-format=absolute --git-common-dir | sed 's|/.git$||')" -
Find orphans — dirs in
.worktrees/not registered with git:# Get git-registered worktree paths git worktree list --porcelain | grep '^worktree ' | sed 's|^worktree ||' # Compare against .worktrees/*/ on disk -
Find merged-branch worktrees:
# Determine main branch git symbolic-ref refs/remotes/origin/HEAD | sed 's|refs/remotes/origin/||' # List merged branches git branch --merged main # Cross-reference with git worktree list -
For each stale worktree, report:
- Path
- Why it's stale (orphan or merged branch)
- Whether it has uncommitted changes (git-registered only; skip for orphans)
-
Triage before removal. Classify each stale worktree and handle accordingly:
State Detection Action Dirty (uncommitted changes) git -C <path> status --porcelainis non-emptyOffer /pds:finishbefore removal — code may be unsavedHas artifacts ( .claude/swarm/exists)test -d <path>/.claude/swarmOffer extraction: archive *.mdtodocs/swarm-reports/and distill 1-2 auto-memory entriesClean stale (no changes, no artifacts) Neither of the above Remove directly For dirty worktrees: warn the user and offer to run
/pds:finishin that worktree first. Do not remove until the user confirms.For worktrees with artifacts: run the extraction step from
/pds:finishStep 0 (archive swarm reports + distill to auto-memory), then proceed with removal. -
Ask user for confirmation before removing. List all candidates with their triage classification and wait for approval.
-
Remove confirmed worktrees:
- Git-registered:
git worktree remove "$REPO_ROOT/.worktrees/<name>"thengit branch -d <branch> - Orphans:
rm -rf "$REPO_ROOT/.worktrees/<name>"
- Git-registered:
-
Clean up:
git worktree pruneto clear stale git references. -
Report summary: N removed, N extracted-then-removed, N skipped (dirty, user declined finish).
SessionStart Detection
PDS detects stale worktrees at session start and warns in context:
STALE WORKTREES: 3 stale worktree(s) in .worktrees/. Run /pds:worktree gc to clean up.
Manual Cleanup
REPO_ROOT="$(git rev-parse --path-format=absolute --git-common-dir | sed 's|/.git$||')"
# Remove a specific worktree and its branch
git worktree remove "$REPO_ROOT/.worktrees/done-feature"
git branch -d done-feature-branch
# Clean stale references (worktree dir already deleted)
git worktree prune
# Find branches already merged to main
git branch --merged main
# Delete merged branches
git branch -d merged-branch-name
Rules
- One branch per worktree — A branch can only be checked out in one worktree
- Shared git history — All worktrees share .git
- Independent state — Each has its own index, HEAD, uncommitted changes
- Clean up after merge — Remove worktrees when PRs are merged
- Never /tmp or ../ — Worktrees go in
.worktrees/, not/tmpor../ - Always resolve REPO_ROOT first — Use
git rev-parse --path-format=absolute --git-common-dir | sed 's|/.git$||'before any.worktrees/path to avoid nested directories when running from a worktree