Last-Login Janitor
Use when you have developer debt - stacks of repos, venvs, node_modules, Docker images, caches, model files - and need to know what is safe to delete. Scans last-access and last-commit times, sizes every artifact, flags stale-vs-protected, and produces size-sorted deletion candidates with one-command cleanup.
Last-Login Janitor
Overview
Developer machines fill with gigabytes of things nobody has touched in a year: 38 cloned repos (7 abandoned), 22 virtualenvs (14 orphaned - their repos are gone), node_modules directories from failed experiments, 12 versions of the same Docker image, caches that no longer serve any project, and LLM model files from an interest that passed.
The danger of cleanup is deleting the WRONG thing: the venv a cron job uses, the image a stopped-but-important container references, the repo with uncommitted work, the cache that would take 40 minutes to rebuild before tomorrow's demo. That's why people don't clean up - and why disks hit 100%.
This skill makes cleanup decision-safe:
- FIND every space-consuming artifact (repos, venvs, node_modules, Docker images/volumes, pip/npm/uv/HF caches, model weights, build dirs).
- DATE it by the right signal: last commit for repos (not file mtime - git updates mtimes on checkout), last atime for venvs and caches, last run for Docker images, registry date for model files.
- PROTECT anything with a live reason to exist: dirty worktrees, unpushed commits, stashes, active containers, venvs referenced by projects newer than themselves, caches modified this week, model files referenced by config.
- RANK deletion candidates by size and produce a reviewable manifest + ready-to-run cleanup commands - nothing is deleted without your yes.
When to Use
- "Disk is full" on a dev machine / build server / homelab SBC
- "I have 40 repos in ~/dev, which ones can I archive?"
- "What's eating my disk?" - honest size accounting per artifact type
- Periodic hygiene: quarterly dev-environment audit
- Onboarding/audit of an inherited machine ("what's actually alive here?")
- Before a big install (models, SDKs) that needs space
Don't use for: system-package cleanup (apt autoremove territory),
photo/video library organization, or deleting anything you can't rebuild or
re-clone. Always run --dry-run semantics: this skill reports, YOU decide.
Artifact types & their truth signals
| Artifact | Truth signal | Protected when |
|---|---|---|
| Git repo | last commit date (git log -1) | dirty worktree, unpushed branches, stashes, recent commit < stale threshold |
| Python venv | last access (atime) OR mtime of newest .py | referenced by a sibling/parent project modified after venv creation |
| node_modules | mtime of newest file inside | sibling package.json modified recently; sibling node_modules newer than repo staleness |
| Docker image | last container run from it (events/ctimes) | ANY container (running OR stopped) uses it; < N days since pull in active project |
| Docker volume | last mount/write | attached to any container |
| pip cache | dir mtime | modified within cache-warm window (default 14d) |
| npm/pnpm cache | dir mtime | same |
| uv cache | dir mtime | same |
| HF model dir | dir mtime | modified within 30d, or referenced by active config/compose file |
| Build dirs (dist/, target/, build/, .next) | mtime | parent project active |
| IDE indexes (.idea, .vscode+bin) | mtime | project active |
Files
| File | Purpose |
|---|---|
scripts/dev_janitor.py | The scanner/classifier: finds artifacts, dates them, flags stale/protected, emits ranked report + cleanup manifest |
references/cleanup-playbook.md | Safe-deletion rules per artifact type, restore-cost table, command cookbook |
README.md | The problem, in dollars and gigabytes |
Usage
# Audit a whole home dir (read-only, always)
python3 scripts/dev_janitor.py scan ~/dev ~/projects --stale-days 180
# Include Docker (requires docker group membership), exclude model dirs
python3 scripts/dev_janitor.py scan ~/ --docker --skip ~/.cache/huggingface
# Emit a ready-to-review cleanup manifest (NOT auto-executed)
python3 scripts/dev_janitor.py scan ~/dev --stale-days 365 --manifest cleanup.json
Output sections: SIZING (bytes per category), STALE candidates (size-sorted, with reason + restore cost), PROTECTED (with why), then a conservative cleanup script printed for human review.
Workflow
- Run the scanner on candidate roots. Start wide (
~), narrow later. - Read SIZING - know what dominates before touching anything.
- Walk STALE top-down (biggest first). For each item check the PROTECT reason column; the script already excluded protected items, but read the reason - "protected" can be overridden by human knowledge ("that cron job was removed last month, delete the venv").
- Generate the manifest, review the printed commands, run them in batches - smallest risk first (caches), highest risk last (repos with unpushed work: NEVER auto-delete, push first).
- After cleanup, rerun the scan and report bytes freed.
Common Pitfalls
- mtime lies for git repos. A
git checkout/pulltouches every file. Date repos by last COMMIT, not file mtime - the script does this. - Deleting a venv a cron/systemd unit needs. Check units before
removing any venv older than the service (
grep -r venv /etc/systemd). The script can't see systemd; you must. - Stopped ≠ dead Docker containers. A stopped container may be a deliberately-paused service; its image must survive. The script treats ANY container's image as protected.
- atime disabled. Many filesystems mount with
noatime/relatime; venv dating falls back to ctime/mtime - treat as "older than reported". - The unpushed-branch trap. A repo with zero remotes and dirty files
contains the ONLY copy of work. Never delete; archive instead
(
tar czf ~/archive/$(basename $r).tgz $r). - Caches aren't always rebuildable locally. On metered/slow links, an HF model cache can cost real money/time to re-download. Check the restore-cost column, not just size.
- One-shot experiments in /tmp die anyway - don't waste review time there; exclude tmp dirs from scans.
Verification Checklist
- Scan ran with default (report-only) mode - no deletions happened yet
- Every deletion candidate has a stated reason + restore cost
- Repos with dirty worktree / unpushed commits are in PROTECTED (or archived, not deleted)
- Docker images used by any container are protected
- Cleanup commands were human-reviewed before execution
- Post-cleanup rescan confirms freed bytes
- Downloads
- Security audit
- Review
- Last updated
- 1mo ago
- Current version
- v1.0.1
- License
- MIT-0
