Safely audit and reclaim disk space on macOS and Ubuntu/Linux hosts, including remote servers over SSH. Use when the user says their Mac, Linux box, VPS, or server disk is full, asks what can be safely deleted, wants to clean caches, developer artifacts, Docker storage, apt/Homebrew/npm/pnpm/yarn/pip/uv caches, journal/log files, Xcode data, editor extensions, node_modules, Trash, crontab/systemd timer disk checks, or asks for a repeatable free-space cleanup workflow.
Safely audit and reclaim disk space on macOS and Ubuntu/Linux hosts, including remote servers over SSH. Use when the user says their Mac, Linux box, VPS, or server disk is full, asks what can be safely deleted, wants to clean caches, developer artifacts, Docker storage, apt/Homebrew/npm/pnpm/yarn/pip/uv caches, journal/log files, Xcode data, editor extensions, node_modules, Trash, crontab/systemd timer disk checks, or asks for a repeatable free-space cleanup workflow.
Free My Disk
Core Rule
Prefer a read-only audit before deleting anything. Classify findings into safety tiers, explain likely impact, and only delete after the user clearly asks to clean. Never delete personal documents, project archives, photos, mail, source repositories, Docker volumes, databases, app containers, or production data unless the user explicitly names them.
Quick Audit
Detect the platform first:
uname -a
df -h /
For macOS, run the bundled read-only script first when possible:
bash scripts/audit_macos_disk.sh
Use PROJECT_SCAN=1 bash scripts/audit_macos_disk.sh to include common project roots such as ~/projects, ~/code, ~/src, and ~/work. Use FULL_SCAN=1 bash scripts/audit_macos_disk.sh only when the user wants a deeper scan and the disk has enough free space for a slower traversal.
For Ubuntu/Linux, run the bundled read-only script first when possible:
bash scripts/audit_linux_disk.sh
Use PROJECT_SCAN=1 bash scripts/audit_linux_disk.sh to include common user and project roots such as ~/projects, ~/code, ~/src, , and . Use only when the user wants a deeper scan.
~/work
/opt
FULL_SCAN=1 bash scripts/audit_linux_disk.sh
For a remote host, replace my-server with the actual hostname or SSH config alias, then copy or stream the script over SSH:
Use du -xhd 1 <dir> | sort -h | tail for large directories. Prefer targeted scans over full-home scans when the disk is very full. On remote Linux servers, include inode pressure with df -ih /; many tiny logs or cache files can fill inodes before bytes.
Safety Tiers
Treat these as usually safe to clean on macOS:
Homebrew old versions and cache: brew cleanup, then optionally remove ~/Library/Caches/Homebrew/*.
Systemd journal vacuuming by size or time, for example sudo journalctl --vacuum-time=14d or sudo journalctl --vacuum-size=500M.
Reinstallable dependencies the user names: node_modules, .venv, build outputs, .next, dist, target.
User trash and caches: ~/.local/share/Trash and ~/.cache, after checking they are not application state.
Treat these as safe but with workflow impact:
VS Code/Cursor extensions under ~/.vscode/extensions and ~/.cursor/extensions; deleting them uninstalls extensions.
Xcode DerivedData and simulator caches; deleting them slows the next build or simulator boot.
Python/uv/pip caches and tool environments; deleting them may require reinstalling tools.
Agent or editor histories such as .claude/projects, .codex/sessions, .cursor/projects; deleting them may remove local history.
Large rotated logs under /var/log; truncate or rotate named logs rather than deleting active log files.
Snap, Flatpak, conda, and language runtime caches; deleting them may require redownloading packages or rebuilding environments.
Treat these as high impact:
Docker Desktop Docker.raw: never delete directly. Use Docker prune commands and Docker Desktop compaction/reset behavior.
Docker volumes: do not run docker volume prune unless the user explicitly accepts losing persistent container data. On servers, assume volumes may contain databases, Grafana/InfluxDB state, uploads, or other service data.
~/Downloads, project archives, media, iCloud Drive, Mail, Photos libraries, and app containers: report size and ask.
APFS local snapshots: report them, but avoid deleting snapshots unless the user explicitly asks and understands the backup/update implications.
Linux service data under /var/lib, /srv, /opt, /home/*, database directories, backups, and container bind mounts: report size and ask before changing.
Kernel or boot cleanup under /boot: prefer package-manager removal of old kernels; do not manually delete kernel files unless recovering from a blocked package manager and the user accepts the risk.
Remote Linux Example
Treat remote servers as production-like Ubuntu/Linux hosts unless the user says otherwise. In examples, replace my-server with the actual hostname or SSH config alias.
Skip docker volume prune, /var/lib/docker/volumes, database directories, and application data unless the user explicitly accepts losing or rebuilding that data.
Scheduled Monitoring
Do not create or edit crontab, launchd jobs, systemd timers, or Codex automations unless the user asks for scheduled monitoring or cleanup. Default scheduled jobs to read-only audit/reporting. Do not schedule destructive cleanup commands such as rm -rf, docker system prune, docker volume prune, apt-get autoremove, or journal vacuuming unless the user explicitly accepts the exact command, cadence, and impact.
Before adding a schedule, ask concise questions. If an interactive user-input tool such as AskUserQuestion or request_user_input is available, use it; otherwise ask in chat:
Target: local macOS, local Linux, or remote SSH host?
Mode: read-only audit/report only, or user-approved low-risk cleanup?
Cadence and output: daily/weekly/monthly, preferred time, log path, and alert threshold?
For Linux servers, prefer a report-only crontab entry with absolute paths and a dedicated log directory:
For macOS, prefer scheduled audit logs with launchd only if the user wants persistent local scheduling; otherwise run the audit on demand. For remote hosts, install the schedule on the remote host only after confirming the SSH target and where logs should live.
Summarize what was cleaned, what was intentionally skipped, the new free-space number, and any follow-up impact such as reinstalling editor extensions or dependencies.
