Clean Worktrees

Clean Stale Agent Worktrees

Remove worktree directories and orphaned worktree-agent-* branches left behind by agent isolation mode.

Based on community patterns from claude-codex-settings and claude-code-ultimate-guide, adapted for Claude Code's agent worktree pattern.

Related upstream issue: anthropics/claude-code#26725

Process

1. Inventory

Run these commands and report counts:

# Count worktree directories
WORKTREE_DIRS=$(find .claude/worktrees -maxdepth 1 -type d -name 'agent-*' 2>/dev/null | wc -l | tr -d ' ')

# Count git worktree registrations (excluding main)
GIT_WORKTREES=$(git worktree list 2>/dev/null | grep 'worktree-agent-' | wc -l | tr -d ' ')

# Count orphaned branches
ORPHANED_BRANCHES=$(git branch --list 'worktree-agent-*' 2>/dev/null | wc -l | tr -d ' ')

Report:

## Worktree Inventory

- Worktree directories: {WORKTREE_DIRS}
- Git worktree registrations: {GIT_WORKTREES}
- Orphaned branches: {ORPHANED_BRANCHES}

If all counts are 0: report "No stale worktrees found." and stop.

2. Dry Run Check

If $ARGUMENTS contains --dry-run: report the inventory and stop. Do not delete anything.

3. Clean Up

Run in this order:

# Prune stale git worktree references
git worktree prune

# Remove registered worktrees that match agent pattern
git worktree list | grep 'worktree-agent-' | awk '{print $1}' | while read wt; do
  git worktree remove --force "$wt"
done

# Delete orphaned branches (allowed by block-git-commit.sh for worktree-agent-* only)
git branch --list 'worktree-agent-*' | xargs git branch -D

4. Report

## Cleanup Complete

- Removed {N} worktree directories
- Deleted {N} orphaned branches
- Pruned git worktree references

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: stuartshields
• Source: stuartshields/claude-setup
• License: MIT
• Homepage: https://stuartshields.github.io/claude-setup/

Install and usage instructions live in the source repository linked above.