| name | cleanup-workspaces |
| description | Use when the user wants to clean up stale or merged git worktrees under ~/.workspace (e.g. after PRs are merged and their remote branches deleted). Prunes workspaces whose remote branch is gone. Companion to pick-issue-to-pr. |
Cleanup Workspaces
Remove git worktrees under ~/.workspace/<group>/<project>/<branch> whose upstream branch has been deleted on the remote (typically because the PR was merged). Companion to the pick-issue-to-pr skill, which creates those workspaces.
Workflow
1. Discover workspaces
Scan ~/.workspace/ for <group>/<project>/<branch> directories. Group them by their main repository (the worktree's common git dir). For each distinct repository, run the steps below once.
git worktree list from any checkout of a repo lists all its worktrees with paths and branches — use it to get the authoritative list rather than relying on directory names alone.
2. Prune remote-tracking refs
For each repository:
git fetch --prune origin
This deletes remote-tracking refs for branches that no longer exist on the remote.
3. Identify workspaces whose branch is gone
A workspace branch is a cleanup candidate when its upstream is gone:
git branch -vv
Branches whose upstream was pruned show : gone] in the output. Cross-check that the branch is actually merged or its PR is closed before removing — prefer : gone] (branch deleted on remote) as the signal, since that means the PR was merged or the branch was deleted intentionally.
Optionally confirm via the GitHub MCP / gh that the associated PR is merged/closed when in doubt.
4. Remove the workspace and its branch
For each confirmed candidate:
git worktree remove "<path>"
git branch -D "<branch>"
Then tidy administrative files:
git worktree prune
Also remove now-empty <group>/<project> parent directories under ~/.workspace/.
5. Report
List what was removed and what was kept (and why, e.g. uncommitted changes blocking removal). Never force-remove a workspace that has uncommitted or unpushed work without explicitly flagging it to the user and getting confirmation.
Safety
- Only ever operate inside
~/.workspace/.
- Do not remove the main working checkout, only linked worktrees.
- A workspace with uncommitted/unpushed changes is surfaced to the user, never silently force-removed.