astahmer/nixfiles/disk-space-cleanup

Disk Space Cleanup (macOS)

Audit first, then make the narrowest cleanup that fits the user's request. Read RECIPES.md for concrete commands before inspecting or removing candidates. Recipes cover pnpm/Bun/Nub cache commands, shared virtual store checks, and separately reviewed Docker volume removal.

Workflow

1. Measure overall pressure and rank large paths. Include shared reference

clones and Codex session logs in the user-space scan; concrete commands are in RECIPES.md. Record the exact Docker context, workspace, database, volume, cache, or VM image involved.

1. Check current processes, ownership, configured storage, service references,

and a usable backup where data could matter. A large size or old timestamp alone does not make something disposable.

1. Explain the exact target, expected space reclaimed, and service or rollback

impact. A broad request to audit does not authorize cleanup; follow the user's stated scope for cleanup actions and clarify only when that scope is ambiguous.

1. Use confirmation prompts where available and review proposed removals. Use

--force only when the user explicitly authorized the exact scope and daemon context. Do not combine unrelated targets or include volumes in a broad prune.

1. Measure the same paths again and check service, container, and workspace

state. Report measured recovery separately from estimates.

Guardrails

• Protect databases, backup repositories, iCloud data, VM disks, JJ workspaces,

Codex sessions and memories, authenticated browser state, and active app data until their owner and recovery path are understood.

• PostgreSQL statistics only cover counters since reset, and activity views

show current connections. Neither proves a database is unused; file mtimes are not a reliable last-use signal.

• Confirm the Docker context before inspection or pruning. system prune can

remove stopped containers, unused networks, dangling images, and build cache. --all broadens image removal; --volumes can remove data volumes.

• OrbStack restarts interrupt local containers. State that impact and get

authorization before restarting it. Do not use a privileged helper container as a generic disk-inspection or trim command.

• Treat Nix generations as rollback points. Do not run garbage collection or

remove generations automatically as routine maintenance.

• Prefer an available Nix-backed one-shot tool for diagnostics; do not install

cleanup tools globally just to inspect a disk.