| name | live-writer-branch-cleanup-guard |
| description | Guardrails for multi-repo sync and branch cleanup when workspace-hub or another shared repo has active writer sessions, worktree-backed branches, or unrelated-history branches. |
| version | 1.0.0 |
| source | session-learned |
Live-Writer Branch Cleanup Guard
Use when:
- doing repo-wide sync + branch cleanup across workspace-hub repos
- a shared repo keeps becoming dirty between checks
- many branches are worktree-backed or created by overnight agents
Core pattern
- Commit and push dirty repos first.
- Before mass branch cleanup, check for active writer sessions:
ps -ef | grep claudeps -ef | grep '[g]it'- repeated
git status --short
- If a repo becomes dirty again between checks, classify it as a live-writer repo.
- Do not do broad merge/delete passes on live-writer repos until the writers stop.
- Use temporary worktrees for branch-to-default merge attempts when the main working tree is dirty or on a non-default branch.
Branch triage rules
Safe to delete
- already merged branches with shared history
- stale worktree-agent branches not attached to active worktrees
- old local aliases like
master in a main-default repo once confirmed merged
Do not auto-merge
- branches that fail with
fatal: refusing to merge unrelated histories
- branches with real content conflicts
- branches currently attached to active worktrees
- branches in repos with active concurrent writer sessions
Interpretation of common failures
-
fatal: refusing to merge unrelated histories
- Treat as separate lineage/import branch.
- Do not auto-merge to main.
- Report for manual triage.
-
error: cannot delete branch '<name>' used by worktree
- Branch is active.
- Skip deletion.
- Clean the worktree first, then retry later.
-
repo gets dirty again right after commit/push
- Usually another agent/process is still writing.
- Stop mass cleanup in that repo and finish other repos first.
Practical order of operations
- Audit repos: default branch, dirty state, ahead/behind, branch inventory.
- Commit/push all dirty repos.
- Prune obviously merged branches in quiet repos.
- Attempt merges only for branches with shared history and no active worktree attachment.
- Leave shared-control repos like workspace-hub for a dedicated quiet window.
Why this exists
A large multi-repo cleanup run showed that the biggest blocker was not git itself but active background Claude/worktree activity. Treating live-writer repos as a special case avoids false cleanup attempts, repeated dirty-state churn, and unsafe branch operations.
