Skip to main content
← back to extensions

Housekeeping

@maphew/housekeepingv2026.10.21.1· MIT· 2d agoBEHAVIORSWORKFLOWSACCEPTED WARNINGS
01README

Generic, portable housekeeping sweep for any checkout. A read-only audit of dirty trees, diverged or deleted branches, forgotten stashes, stale worktrees, temp debris, leftover processes, disk pressure, and stuck tracker claims, plus explicitly-gated cleanup methods that dry-run by default. Project-agnostic: projectDir defaults to ., with .beads/ and .swamp/ awareness layered on when present.

02Behaviors1
@maphew/housekeepingv2026.10.21.1src/housekeeping.ts

Global Arguments

ArgumentTypeDescription
projectDir?stringRepository root to audit. Defaults to the current directory so the model stays portable.
defaultBranch?stringBranch to treat as the mainline. Auto-detected from origin/HEAD, then main, then master.
bdBin?stringBeads CLI binary name or path
staleClaimDays?numberAge (days) after which an in-progress tracker claim is reported stale even when its lease has not expired
staleTempHours?numberAge (hours) after which matched temp debris is reported stale
tempGlobs?arrayGlob patterns matched (one level deep) under the temp roots
tempRoots?arrayDirectories scanned for temp debris. Empty means $TMPDIR and projectDir.
processPatterns?arraypgrep patterns for leftover processes. Empty disables the process check.
includeBeads?booleanRun tracker hygiene checks when .beads/ is present
includeTemp?booleanScan for temp debris, leftover processes, and disk pressure
fn check()
Read-only fan-out: git, worktrees, temp/processes/disk, and tracker hygiene
fn pruneWorktrees(dryRun?: boolean, verbose?: boolean)
Remove worktrees whose path is missing on disk. Dry-run by default.
ArgumentTypeDescription
dryRun?boolean
verbose?boolean
fn unclaimStaleBeads(dryRun?: boolean, force?: boolean, reason?: string)
Release tracker claims whose lease expired or went idle. Dry-run by default.
ArgumentTypeDescription
dryRun?boolean
force?booleanPass --force to release another actor's claim
reason?string
fn cleanTemp(dryRun?: boolean, force?: boolean)
Remove matched temp debris older than staleTempHours. Dry-run by default.
ArgumentTypeDescription
dryRun?boolean
force?booleanRemove directories recursively; without it only files are removed

Resources

audit(7d)— Combined read-only housekeeping audit
git(7d)— Git branch, worktree-of-origin, stash, and status findings
worktrees(7d)— Worktree health: stale, prunable, locked, detached
temp(7d)— Temp debris, leftover processes, and disk pressure
beads(7d)— Tracker hygiene: version drift, stale claims, doctor checks
worktreePrune(30d)— Worktree prune candidate/result
beadUnclaim(30d)— Stale-claim release candidate/result
tempClean(30d)— Temp cleanup candidate/result

Files

report(text/markdown)— Markdown housekeeping report
03Workflows1
@maphew/housekeeping7b6f6d2e-2e2c-4d2a-9d0f-0e6f6b1a4c31

Run the read-only housekeeping sweep and refresh the markdown report. Requires a model instance named `housekeeping` created from @maphew/housekeeping.

sweepRun every read-only check and write the audit + report
1.checkhousekeeping.check— Audit git, worktrees, temp/processes/disk, and tracker hygiene
04Previous Versions4
2026.10.15.4MIT

Adversarial-review fixes: entry logging in every method; warn (instead of silently skip) on a missing bd binary and on bd JSON parse failure; report when the default branch cannot be resolved for merged-branch detection; add trunk/develop to default-branch candidates.

2026.10.15.3MIT

Packaging fix 2: quote the bundled workflow name so the scoped @maphew/housekeeping identifier parses as YAML (an unquoted @ is a reserved YAML indicator). The workflow now registers. No behavior changes.

Added 1 workflows

2026.10.15.2MIT

Packaging fix: the bundled workflow is now listed by basename so it extracts to extension/workflows/workflow-housekeeping.yaml and registers as @maphew/housekeeping. No behavior changes.

2026.10.15.1MIT

Initial release. Read-only generic housekeeping sweep: git (dirty/detached/diverged/gone/merged/stash), worktrees (stale/prunable/locked), temp debris + leftover processes + disk pressure, and tracker hygiene (bd version drift, expired/idle claims, stale/orphans/doctor). Cleanup methods (pruneWorktrees, unclaimStaleBeads, cleanTemp) dry-run by default. Bundled @maphew/housekeeping workflow.

05Stats
A
100 / 100
Downloads
9
Archive size
23.8 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
Repository
https://github.com/maphew/swamp-extensions.git

07Platforms
08Labels
#housekeeping#hygiene#git#worktree#beads#maintenance