System diagnostics
Overview
Interactive skill for diagnosing system resource issues. Detects OS and applies appropriate diagnostic patterns. Focuses on real-world lessons from production incidents rather than generic command documentation.
Context
Expects a Unix-like system (Linux or macOS). User describes a resource problem (memory, disk, CPU, or general slowness).
Process
- Detect platform:
uname -s(Linux or Darwin) - Identify problem type: memory, disk, CPU, or I/O
- Run targeted diagnostics using platform-appropriate commands
- Apply cleanup patterns from references for Nix-aware environments
- Verify: confirm resource pressure reduced
References
- macos-disk-cleanup-learnings-2026-02-17.md: moondancer cleanup runbook, Determinate Nix GC behavior, safety tiers
- nix-gc-determinate-seasmoke-learnings-2026-02-17.md: Nix store root retention, profile generation pruning, container storage
- system-cleanup-report-20260117-reference.md: High-impact cleanup operations with space recovered
Guidelines
- Use
sudofor accurate disk usage on Linux (non-rootduunder-reports) - On macOS with Determinate Nix,
nix.gc.automaticis disabled by policy - use explicitnix-collect-garbage -d - Clean caches first (low risk, high value): trash, browser caches, package manager caches
- Prune Nix profile generations on all users, not just system
- Check container storage (
/var/lib/containers, rootless storage) as disk pressure source
Quick reference
Assess state:
df -h / /nix # disk usage
du -sh ~/.Trash ~/.cache ~/Library/Caches /nix/store 2>/dev/null # top consumersSafe cleanup (macOS):
rm -rf ~/.Trash/*
rm -rf ~/Library/Caches/*
uv cache clean && brew cleanup --prune=all
nix-collect-garbage -dSafe cleanup (Linux, as root):
sudo du -xhd 1 / | sort -hr | head -20 # find top consumers
sudo nix-collect-garbage -d
sudo nix-store --gc
sudo podman system prune --volumes -f # if containers presentAppendix
Determinate Nix GC behavior
When determinateNix.enable = true on macOS hosts, nix-darwin's nix.gc module is disabled. Determinate Nixd handles GC policy instead. Do not assume timer-based GC is running.
Reference: dragonix/modules/base/nix-settings/darwin.nix
Nix root retention patterns
Large Nix store after GC usually means:
- Old profile generations still rooted under
~/.local/state/nix/profiles/ - Running processes holding
/procroots - Solution: prune all user profiles, not just system
# Per-user profile pruning
nix-env -p ~/.local/state/nix/profiles/profile --delete-generations old
nix-env -p ~/.local/state/nix/profiles/home-manager --delete-generations oldSafety tiers
Low risk, high value: trash, caches, uv cache clean, brew cleanup Medium risk with verification: nix-collect-garbage -d, playwright cache, mediaanalysisd Do not delete: /System, /usr, /bin, /sbin, APFS system volumes, app databases