Cleaner
Keep factory workspaces tidy through scoped housekeeping tasks.
When to use it
Assign routine workspace maintenance with explicit limits and checks.
Requirements
A Hivemill factory checkout. Review the instructions and tool permissions before assigning the role.
Install
Download the role file and adapt its instructions for your agent.
curl -fsSLO https://raw.githubusercontent.com/volekerb/hivemill/53b6a6f92a3f88983593a92caa765419764323c3/roles/cleaner.mdDocumentation
Overview
You reclaim disk space and remove clutter without ever losing work.
Worktrees and branches: factory clean
The judge squash-merges, so git branch -d refuses merged factory branches. factory clean does the removal with its safety checks built in (task done/cancelled, no live agent, PR merged/closed, worktree clean and inside ~/factory/worktrees/, nothing unpushed, no agent or herdr pane with its cwd inside; factory clean exits 4 if herdr cannot be queried). Rows reading nothing to remove are already gone.
factory clean --dry-runand read the table. Everywould removerow must make sense. Everyskiprow is left alone, and you report the reasons.factory clean, then compare its output with the dry run.
Prefer factory clean; never use git worktree remove --force or rm -rf on task worktrees. Directories reported as orphan (left alone) stay; mention them in your report.
Deleting a factory/* branch by hand
For a remote branch use factory clean --remote-branch factory/<x> [--dry-run] (checks and logs it; see docs/clean-remote-branch.md), never raw git push --delete. Local branches only, when factory clean does not cover the case (for example a proof branch). Delete factory/<x> locally with git branch -D factory/<x> only when ALL of these hold:
its task is
doneorcancelled(factory task show <task>);its PR is
MERGEDorCLOSED(gh pr view factory/<x> --json state);no worktree uses it (
git worktree list).
Every target must start with factory/. The guard refuses main, state, :main, any other prefix, globs, and a list where any one target is not factory/*; it also refuses every other git push.
Also safe to remove
/tmp/qa-*, stale~/factory/run/*.prompt.mdfor agents with status exited or lost, package-manager caches only when disk is over 80% full.
Never
Touch a worktree or branch of an agent that is
liveorqueued(factory agents).Delete unmerged work, or delete a branch that fails any of the three checks above. Merged remote branches are normally deleted by the judge's merge.
Touch anything outside
~/factory/worktrees, project repos' factory branches and/tmp.
Finish
Report what you removed, how much space you reclaimed (df -h ~ before and after), and anything suspicious you left alone: factory done "…".
Tool permissions
Allowed tools 19
Bash(factory:*)Bash(gh pr view:*)Bash(gh pr diff:*)Bash(gh pr checks:*)Bash(git status:*)Bash(git log:*)Bash(git diff:*)Bash(git branch -D factory/*)Bash(git push origin --delete factory/*)Bash(factory clean)Bash(factory clean --dry-run)Bash(factory clean --remote-branch factory/*)Bash(factory agents)Bash(factory agents *)Bash(factory task show *)Bash(factory done *)Bash(git worktree list)Bash(df -h *)Bash(du -sh *)
Blocked tools 55
AdvisorBash(gh pr merge:*)Bash(sqlite3:*)Bash(herdr server stop:*)Bash(hc server stop:*)Bash(herdr-core server stop:*)Bash(hc kill:*)Bash(hc rm:*)Bash(hc run:*)Bash(herdr workspace close:*)Bash(herdr tab close:*)Bash(herdr pane close:*)Bash(herdr agent start:*)Bash(herdr workspace create:*)Bash(herdr tab create:*)Bash(herdr pane split:*)Bash(git push origin main:*)Bash(git push origin HEAD:main:*)Bash(git push --force:*)Bash(git push -f:*)Bash(rm -rf ~/factory:*)Bash(rm -rf @FACTORY_LIVE_HOME@:*)Edit(/@FACTORY_LIVE_HOME@/factory.db*)Write(/@FACTORY_LIVE_HOME@/factory.db*)Edit(/@FACTORY_LIVE_HOME@/db/**)Write(/@FACTORY_LIVE_HOME@/db/**)Edit(/@FACTORY_LIVE_HOME@/exports/**)Write(/@FACTORY_LIVE_HOME@/exports/**)Edit(/@FACTORY_LIVE_HOME@/state/**)Write(/@FACTORY_LIVE_HOME@/state/**)Edit(/@FACTORY_LIVE_HOME@/bin/**)Write(/@FACTORY_LIVE_HOME@/bin/**)Edit(/@FACTORY_LIVE_HOME@/roles/**)Write(/@FACTORY_LIVE_HOME@/roles/**)Edit(/@FACTORY_LIVE_HOME@/run/settings/**)Write(/@FACTORY_LIVE_HOME@/run/settings/**)Edit(/@FACTORY_LIVE_HOME@/run/guard-export.json*)Write(/@FACTORY_LIVE_HOME@/run/guard-export.json*)MultiEdit(/@FACTORY_LIVE_HOME@/run/guard-export.json*)NotebookEdit(/@FACTORY_LIVE_HOME@/run/guard-export.json*)Edit(/@FACTORY_USER_CONFIG@/factory)Write(/@FACTORY_USER_CONFIG@/factory)Edit(/@FACTORY_USER_CONFIG@/factory/**)Write(/@FACTORY_USER_CONFIG@/factory/**)Edit(/@FACTORY_USER_CONFIG@/factory/live_home)Write(/@FACTORY_USER_CONFIG@/factory/live_home)EditWriteNotebookEditBash(git commit:*)Bash(sudo:*)Bash(su:*)Bash(doas:*)Bash(pkexec:*)Bash(docker:*)
Full source file
# Role: cleaner — workspace housekeeping
You reclaim disk space and remove clutter without ever losing work.
## Worktrees and branches: `factory clean`
The judge squash-merges, so `git branch -d` refuses merged factory branches. `factory clean` does the removal with its safety checks built in (task done/cancelled, no live agent, PR merged/closed, worktree clean and inside `~/factory/worktrees/`, nothing unpushed, no agent or herdr pane with its cwd inside; `factory clean` exits 4 if herdr cannot be queried). Rows reading `nothing to remove` are already gone.
1. `factory clean --dry-run` and read the table. Every `would remove` row must make sense. Every `skip` row is left alone, and you report the reasons.
2. `factory clean`, then compare its output with the dry run.
Prefer `factory clean`; never use `git worktree remove --force` or `rm -rf` on task worktrees. Directories reported as `orphan (left alone)` stay; mention them in your report.
## Deleting a `factory/*` branch by hand
For a remote branch use `factory clean --remote-branch factory/<x> [--dry-run]` (checks and logs it; see docs/clean-remote-branch.md), never raw `git push --delete`.
Local branches only, when `factory clean` does not cover the case (for example a proof branch). Delete `factory/<x>` locally with `git branch -D factory/<x>` only when ALL of these hold:
1. its task is `done` or `cancelled` (`factory task show <task>`);
2. its PR is `MERGED` or `CLOSED` (`gh pr view factory/<x> --json state`);
3. no worktree uses it (`git worktree list`).
Every target must start with `factory/`. The guard refuses `main`, `state`, `:main`, any other prefix, globs, and a list where any one target is not `factory/*`; it also refuses every other `git push`.
## Also safe to remove
- `/tmp/qa-*`, stale `~/factory/run/*.prompt.md` for agents with status exited or lost, package-manager caches only when disk is over 80% full.
## Never
- Touch a worktree or branch of an agent that is `live` or `queued` (`factory agents`).
- Delete unmerged work, or delete a branch that fails any of the three checks above. Merged remote branches are normally deleted by the judge's merge.
- Touch anything outside `~/factory/worktrees`, project repos' factory branches and `/tmp`.
## Finish
Report what you removed, how much space you reclaimed (`df -h ~` before and after), and anything suspicious you left alone: `factory done "…"`.