agentsclimarketplace

Worktree

Skill rmzi/portable-dev-system/skills/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

Install
npx -y skills add rmzi/portable-dev-system --skill worktree

Assembled 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:

  1. Resolve REPO_ROOT (see Path Resolution below).
  2. gh issue view <N> --json title -q .title to fetch the issue title.
  3. Slugify the title: lowercase, alphanumerics and hyphens only, collapse runs, truncate to ~40 chars.
  4. Compose the branch name: <type>/<N>-<slug> (default type=feat if omitted; use fix for bug issues, refactor for cleanup, etc.).
  5. Create the worktree:
    git worktree add "$REPO_ROOT/.worktrees/<type>-<N>-<slug>" -b <type>/<N>-<slug>
    
  6. cd into 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?

AlternativeProblem
git rev-parse --show-toplevelReturns 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

TypeDetectionRemoval
OrphanDirectory in .worktrees/ not in git worktree list (broken git metadata)rm -rf <path> (git doesn't know about it)
Merged branchWorktree whose branch is already merged to maingit worktree remove <path> + git branch -d <branch>

GC Protocol

  1. Resolve repo root:

    REPO_ROOT="$(git rev-parse --path-format=absolute --git-common-dir | sed 's|/.git$||')"
    
  2. 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
    
  3. 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
    
  4. 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)
  5. Triage before removal. Classify each stale worktree and handle accordingly:

    StateDetectionAction
    Dirty (uncommitted changes)git -C <path> status --porcelain is non-emptyOffer /pds:finish before removal — code may be unsaved
    Has artifacts (.claude/swarm/ exists)test -d <path>/.claude/swarmOffer extraction: archive *.md to docs/swarm-reports/ and distill 1-2 auto-memory entries
    Clean stale (no changes, no artifacts)Neither of the aboveRemove directly

    For dirty worktrees: warn the user and offer to run /pds:finish in that worktree first. Do not remove until the user confirms.

    For worktrees with artifacts: run the extraction step from /pds:finish Step 0 (archive swarm reports + distill to auto-memory), then proceed with removal.

  6. Ask user for confirmation before removing. List all candidates with their triage classification and wait for approval.

  7. Remove confirmed worktrees:

    • Git-registered: git worktree remove "$REPO_ROOT/.worktrees/<name>" then git branch -d <branch>
    • Orphans: rm -rf "$REPO_ROOT/.worktrees/<name>"
  8. Clean up: git worktree prune to clear stale git references.

  9. 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

  1. One branch per worktree — A branch can only be checked out in one worktree
  2. Shared git history — All worktrees share .git
  3. Independent state — Each has its own index, HEAD, uncommitted changes
  4. Clean up after merge — Remove worktrees when PRs are merged
  5. Never /tmp or ../ — Worktrees go in .worktrees/, not /tmp or ../
  6. 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

Keep looking

Skills are one crate of 613,373. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.