worktree-retry-cleanup — Claude Code skill
worktree-retry-cleanup is a Claude Code skill that cleans up a swarm worktree lane before a task is dispatched again.
MIT ★ 539 updated 2026-10-29
npx skills add ZaxbyHub/opencode-swarm --skill worktree-retry-cleanup -a claude-codeWhat worktree-retry-cleanup does
The skill fires before a task that already has a lane goes out a second time. Whatever the earlier run ended with, its worktree and branch are still on disk.
Most retries need nothing manual: the normal dispatch path pre-cleans a stale lane when ownership is clear and the lane is clean. A refusal from provisioning is the answer, not an obstacle. Dirty lanes, lanes checked out in another worktree, and lanes held by an active session get reported to you rather than deleted.
Manual removal comes last and starts with ownership. Read .swarm/session/state.json, confirm no other session's delegationChains point at <session>/<task>, and stop if one does. Only .swarm-worktrees/<session>/<task> is removed, never the session parent, using git worktree remove followed by git worktree prune. For the branch, git branch -d swarm/lane/<session>/<task> is allowed once you know nothing has it checked out and no commit is lost; forcing -D waits for a human to say yes. Finish by confirming git branch --list returns nothing for that lane.
What it helps with
- clear a stale worktree before re-dispatching a task
- avoid deleting a lane another active session owns
- tell a dirty lane apart from one that is safe to remove
- drop
swarm/lane/<session>/<task>without losing commits - confirm the lane branch is gone before the retry
Example prompts for the agent
- Re-dispatch the
auth-fixtask, but run the worktree cleanup protocol for its lane first - Check
.swarm/session/state.jsonfor another active session that owns<session>/<task> - Remove
.swarm-worktrees/<session>/<task>, rungit worktree prune, then confirm the lane branch is gone withgit branch --list
How to install worktree-retry-cleanup
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill worktree-retry-cleanup -a claude-code2Manually: put the files in place
~/.claude/skills/worktree-retry-cleanup/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/worktree-retry-cleanup/
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill worktree-retry-cleanup -a codex2Manually: put the files in place
.agents/skills/worktree-retry-cleanup/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill worktree-retry-cleanup -a cursor2Manually: put the files in place
.cursor/skills/worktree-retry-cleanup/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ZaxbyHub/opencode-swarm .opencode/skills/worktree-retry-cleanup2Manually: put the files in place
.github/skills/worktree-retry-cleanup/SKILL.md1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill worktree-retry-cleanup -a gemini-cli2Platform CLI
gemini skills install https://github.com/ZaxbyHub/opencode-swarm --path .opencode/skills/worktree-retry-cleanupManually: put the files in place
.devin/skills/worktree-retry-cleanup/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill worktree-retry-cleanup -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about worktree-retry-cleanup
How do I install worktree-retry-cleanup in Claude Code?
Run npx skills add ZaxbyHub/opencode-swarm --skill worktree-retry-cleanup -a claude-code. The skill file lands at ~/.claude/skills/worktree-retry-cleanup/SKILL.md.
What does worktree-retry-cleanup do?
It sets the order of operations for re-dispatching a task that already has a lane: built-in cleanup during dispatch first, then an ownership check and targeted removal of the worktree and branch.
What happens when another session owns the lane?
Deletion is off the table. That lane, like a dirty one or one checked out elsewhere, is surfaced to the user and left alone.
Source text
SKILL.md · MIT
--- name: worktree-retry-cleanup description: Protocol for cleaning parallel-coder worktree lanes before retry. Triggered before re-dispatching any task that already has a lane (completed, denied, cancelled, or failed). metadata: audience: swarm-plugin --- # Worktree Retry Cleanup ## Trigger Before re-dispatching a coder for a task that already has a lane (any prior dispatch status). ## Protocol 1. **Prefer built-in provisioning cleanup.** Re-dispatch normally through the standard coder/worktree path. Provisioning pre-cleans stale same-lane worktrees/branches when ownership is safe and the existing lane is clean. 2. **If provisioning blocks:** Treat the error as signal. Dirty lanes, lanes active in another worktree, and lanes owned by another active session must be surfaced to the user instead of deleted. 3. **If manual cleanup is explicitly required:** Do the ownership check FIRST. Confirm the lane is not owned by another ACTIVE session: read `.swarm/session/state.json` and verify no other session's `delegationChains` reference `<session>/<task>`. If another active session owns it, STOP. 4. **Remove only the specific lane.** Target `.swarm-worktrees/<session>/<task>`, never the session parent. Prefer `git worktree remove .swarm-worktrees/<session>/<task>` and then `git worktree prune`. 5. **Delete only confirmed stale branches.** `git branch -d swarm/lane/<session>/<task>` is allowed after confirming the branch is not checked out and contains no needed commits. Use force deletion only with explicit human approval. 6. **Verify:** `git branch --list "swarm/lane/<session>/<task>"` returns empty before retrying. ## Root cause Stale same-lane worktrees and branches used to require manual cleanup before retry. Provisioning now handles the safe clean/stale cases automatically and fails closed for dirty, active, or cross-session-owned lanes.
© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm