SethGammon/houseclean

/houseclean — Storage Audit and Cleanup

Use when disk space is low, AI tool caches are bloated, or worktrees need cleanup. Do NOT use for project structure issues (use /organize) or pre-merge worktree review (use /merge-review).

Orientation

Use when: cross-drive storage audit -- finds orphaned repos, stale branches, and large directories across all drives. Don't use when: auditing project infrastructure only (use /infra-audit); cleaning a specific directory (use Bash directly).

Invocation Forms

/houseclean              # Full audit — all phases
/houseclean --quick      # Drive survey + quick wins only (no deep scan)
/houseclean --worktrees  # Orphaned worktree audit only
/houseclean --ai-tools   # AI tool cache audit only
/houseclean --projects   # Project artifact scan only (node_modules, .venv, etc.)
/houseclean --migrate X  # Migration instructions for a specific tool (ollama, gemini, npm, cursor)

Protocol

Phase 1: Drive Survey

Windows (PowerShell):

Get-PSDrive -PSProvider FileSystem | Select-Object Name, Used, Free, Root | Format-Table -AutoSize

Present as a table with Drive, Total, Used, Free, Label columns.

Thresholds: C: free < 5 GB → CRITICAL. C: free < 20 GB → WARNING. Store which drives have free space — these are migration targets.

Phase 2: C Drive Hot Spots

Windows (PowerShell):

Get-ChildItem "C:\Users\$env:USERNAME" -Directory -ErrorAction SilentlyContinue |
  ForEach-Object {
    $s = (Get-ChildItem $_.FullName -Recurse -ErrorAction SilentlyContinue |
          Measure-Object -Property Length -Sum).Sum
    [PSCustomObject]@{ GB = [math]::Round($s/1GB,2); Path = $_.Name }
  } | Sort-Object GB -Descending | Select-Object -First 15 | Format-Table -AutoSize

Tag each entry:

• AI-tool-data — .ollama, .gemini, .cursor, .windsurf, .codex, .continue
• IDE-cache — .vscode, .idea, AppData\Local\JetBrains
• Package-cache — AppData\Local\npm-cache, AppData\Local\pip\cache, .gradle, .m2
• Conversation-history — .claude\projects
• Projects — Desktop, Documents, user project directories
• System — AppData\Local\Microsoft, AppData\Roaming

Phase 3: Orphaned Worktree Audit

git rev-parse --show-toplevel
git worktree list

For each worktree (excluding main):

1. Check if branch is merged: git branch --merged HEAD | grep "{branch-name}"
2. Verify worktree directory exists
3. Check uncommitted changes: git -C "{worktree-path}" status --short

Classify:

• SAFE TO REMOVE — merged into HEAD, no uncommitted changes
• REVIEW FIRST — not merged, has changes
• STALE — path missing (registered but deleted)
• ACTIVE — not merged, no changes (possibly in-flight)

Auto-remove SAFE TO REMOVE and STALE:

git worktree remove "{path}" --force
git branch -d "{branch-name}"

Report what was removed. Ask before touching REVIEW FIRST or ACTIVE.

Phase 4: AI Tool Cache Audit

Check these paths (Windows). Report any > 500 MB:

~/.ollama/models          → Ollama LLM models
~/.gemini/antigravity     → Gemini CLI data/cache
~/.cursor                 → Cursor editor
~/.windsurf               → Windsurf editor
~/.codex                  → Codex CLI
~/.continue               → Continue.dev extension
~/.cache/huggingface      → HuggingFace model cache
AppData/Local/npm-cache   → npm package cache
AppData/Local/pip/cache   → pip package cache
AppData/Local/Temp        → Windows temp files

Tag recommended action:

• SAFE TO CLEAR — rebuilds automatically (npm, pip, temp)
• MOVE — redirectable via env var (ollama models, gemini)
• REVIEW — needs user decision (cursor settings, IDE data)

Phase 5: Project Artifact Scan

Scan C: for rebuildable artifacts: node_modules, .venv, __pycache__, .pytest_cache, dist/, build/. Report path, size, last modified. Flag items not modified in > 30 days. Ask user before deleting any.

Phase 6: Quick Wins Report

=== QUICK WINS (safe to act on now) ===
1. npm-cache              5.7 GB   CLEAR    npm cache clean --force
2. Merged worktrees (17)   50 MB   REMOVED  (already done)

=== MOVE TO ANOTHER DRIVE ===
3. ~/.ollama/models       15.8 GB  MOVE→F:  See migration guide
4. ~/.gemini              10.2 GB  MOVE→F:  See migration guide

=== REVIEW WITH USER ===
5. ~/.claude/projects      3.1 GB  REVIEW   Old conversation history

Total recoverable on C: ~47 GB

Phase 7: Migration Reference

Ollama (models → another drive)

Get-Process ollama -ErrorAction SilentlyContinue | Stop-Process
robocopy "C:\Users\$env:USERNAME\.ollama" "F:\.ollama" /E /MOVE /LOG:ollama-move.log
[Environment]::SetEnvironmentVariable("OLLAMA_MODELS", "F:\.ollama\models", "User")

Gemini CLI

Check if GEMINI_HOME is supported: gemini --help | grep -i "home\|data\|dir"

If supported:

robocopy "C:\Users\$env:USERNAME\.gemini" "F:\.gemini" /E /MOVE
[Environment]::SetEnvironmentVariable("GEMINI_HOME", "F:\.gemini", "User")

If not supported, create a junction:

robocopy "C:\Users\$env:USERNAME\.gemini" "F:\.gemini" /E /MOVE
cmd /c mklink /J "C:\Users\$env:USERNAME\.gemini" "F:\.gemini"

npm cache

npm cache clean --force
npm config set cache "F:/npm-cache"

Cursor/Windsurf/Codex (junction method)

robocopy "C:\Users\$env:USERNAME\.cursor" "F:\.cursor" /E /MOVE
cmd /c mklink /J "C:\Users\$env:USERNAME\.cursor" "F:\.cursor"

git worktrees

Move the main repo to another drive:

robocopy "C:\Users\$env:USERNAME\Desktop\ProjectName" "F:\Projects\ProjectName" /E /MOVE

After moving, record in .claude/harness.json:

{ "storage": { "projects_root": "F:/Projects" } }

Claude conversation history (.claude/projects)

Cannot be relocated. Archive inactive subdirectories to a backup drive, or test symlinking.

---

Fringe Cases

macOS/Linux: Use du -sh, df -h. Paths shift to ~/. Worktree removed but branch exists: git branch -d {branch} after git worktree remove. Ollama in use: Stop before moving model files. Junction already exists: cmd /c rmdir "C:\...\tool-dir" (no contents deleted), then recreate. No other drives: Clear caches first (npm, pip, temp), then rebuildable artifacts, then unused Ollama models.

---

Citadel Infrastructure Integration

After running /houseclean, update .claude/harness.json storage section with projects_root, ai_tools paths, and last_audit date. Future runs verify migrations are still in place.

---

Contextual Gates

Disclosure: "Auditing all drives. Will present deletion suggestions — nothing deleted without your confirmation." Reversibility: amber — deletes files and directories if user confirms; undo requires git or manual recovery for non-git files Trust gates:

• Any: view audit findings and suggestions
• Familiar (5+ sessions): confirms deletions before executing; novices should review suggestions carefully before confirming

Quality Gates

• Never delete data without confirming branch is merged into HEAD
• Always verify uncommitted changes before removing a worktree
• Always stop Ollama before moving model files
• Show exact commands — no vague instructions
• Re-run drive survey to confirm C: free space increased
• Update harness.json storage section for any migrations completed
• If total freed is 0 GB, surface why and what the user must do manually

---

Exit Protocol

1. Show total space freed this session
2. Show space still recoverable with user action
3. Show current C: free space
4. Suggest: "/houseclean runs well as a monthly check — use /schedule to add it"

---HANDOFF---
- Freed: {X} GB (caches cleared, worktrees removed)
- Pending user action: {Y} GB (AI tools to move, projects to migrate)
- C: free space now: {Z} GB
- harness.json storage section: updated / not updated
- Reversibility: amber — deleted files require git or manual recovery; moved files can be moved back manually
---