Agent Broom

Agent Broom is the portable CLI + skill package for agent process hygiene: a small memory hook plus deterministic shell scripts for tracking, auditing, and cleaning up agent-spawned local processes and build artifacts.

Agent Broom packages the same model used by Kevin's Agent Operations Skills skill: the prompt stays small, while the script owns process tracking, localhost listener audit, dry-run cleanup, and artifact deletion. The repo exposes bin/agent-broom plus lib/*.sh; the reusable skill lives at skill/SKILL.md. Source: Kevin-Liu-01/agent-broom README, commit 1bab484c38a3061826cbb93cec591c5d786a48db

Current State

Available; current dry-run doctor passes. The standalone repository and vendored skill are real implementations. A fresh 2026-08-12 run against commit ea8dffb6 completed with exit 0, inventoried listeners and agent browsers, reported build artifacts without deletion, and identified two candidate orphan dev processes without acting on them. The earlier empty-nested_repos failure did not reproduce in the same checkout, so the owner is no longer marked failing. The repository still lacks an automated regression suite for empty nested repositories, protected processes, and mutation modes; a passing live doctor is operational proof, not full release coverage.

When To Use

Use Agent Broom before starting another dev server, before ending a turn that spawned long-running processes, when CPU or memory is high, when disk is low, or when a user asks what is running. The correct operating shape is audit first, then act only after reviewing ownership and risk.

In this wiki, Agent Operations Skills remains the canonical skill owner so there is one process-hygiene route. The full Agent Broom repo is vendored at skills/productivity/cleanup-terminals-browsers/references/agent-broom/ for source comparison and cross-harness reconstruction.

Commands

Agent Broom exposes the following command family:

agent-broom list
agent-broom audit
agent-broom add --pid <PID> --kind dev --port <PORT> --purpose "<why>" -- <command>
agent-broom stop
agent-broom stop --kill
agent-broom prune
agent-broom artifacts
agent-broom artifacts --clean
agent-broom devclean
agent-broom devclean --deep
agent-broom devclean --optimize
agent-broom devclean --disk
agent-broom devclean --apply
agent-broom doctor

Everything risky is dry-run first. stop --kill, artifacts --clean, and devclean --apply are the explicit mutation gates.

Safety Model

Agent Broom records long-running commands in ~/.cache/agent-processes/ledger.tsv, including repo root, cwd, PID, PGID, process kind, port, purpose, and command. That ledger turns cleanup from inference into ownership-aware accounting.

The safety model is conservative: kill by process group only after ownership is clear, prefer SIGTERM before SIGKILL, never kill the editor, Codex, the user's shell, or shared MCP servers, and delete only known regenerable artifacts.

---

Timeline

• 2026-08-12 | Re-ran agent-broom doctor at ea8dffb6: exit 0, dry-run only, listeners/browsers/artifacts inventoried, and candidate orphans reported without mutation. Corrected the stale failing status while retaining the missing-regression-suite gap. Source: local live doctor

• 2026-08-10 | Reconciled the public standalone repo at commit ea8dffb6 and ran its doctor. The CLI is present; doctor currently fails on an empty nested_repos array in clean-artifacts.sh. Source: local read-only audit

• 2026-06-30 | Imported Agent Broom as the portable package/source form for Kevin's process-hygiene stack. The local cleanup skill keeps ownership, and the full repo is vendored under the skill's references with commit 1bab484c38a3061826cbb93cec591c5d786a48db. Source: https://github.com/Kevin-Liu-01/agent-broom