macOS 13 Junk Cleaner

Overview

Safely clean up junk files on macOS 13 (Ventura). The skill uses a four-phase workflow: Scan → Report → Confirm → Clean — all deletions go to macOS Trash (recoverable), never permanent deletion. Covers system caches, logs, trash, temp files, dev environment caches (npm, pip, maven, gradle, docker, homebrew, Xcode, etc.), app residual files, and large single files (>100MB such as installers, old archives, VM images, oversized logs).

Critical Safety Rules

These rules are non-negotiable and must be followed at every step:

NEVER use rm, rm -rf, or any permanent deletion command on user files. All cleanup goes through move_to_trash.py which uses macOS Finder via osascript to move items to Trash (recoverable).
NEVER delete these paths (the scripts enforce this, but verify manually too):
- /, /System, /usr, /bin, /sbin, /etc, /private/var, /dev
- The user's home directory root (~)
- ~/Library (the directory itself — only clean individual subdirectories)
- ~/Library/Caches (the directory itself — only clean individual subdirectories)
- /private/var/folders/ (system-managed temp — macOS handles cleanup)
ALWAYS scan first, then confirm before cleaning. Never skip the confirmation step. Present the scan report to the user and ask which categories/items to clean.
Use small batches. Process no more than 10-20 items at a time. Verify success after each batch before continuing.
Skip sudo-requiring paths by default. System-wide caches in /Library/Caches/ and /private/var/log/ require sudo. Mention them in the report but do not attempt to clean them unless the user explicitly asks and provides sudo access.
Back up first (optional). If the user is concerned, suggest creating a Time Machine backup before cleaning.

Workflow

Phase 1: Scan

Run the scan script to identify all junk files and their sizes:

python3 scripts/scan_junk.py

Options:

--category caches|trash|dev|app_residual|large_files|all — scan specific category only
--min-size 100 — minimum file size in MB for the large_files category (default: 100)
--json --output /tmp/scan_report.json — output JSON for programmatic processing
--quiet — suppress progress messages

The script scans five categories:

System caches & logs — ~/Library/Caches/, ~/Library/Logs/, crash reports, saved app states
Trash & temp files — ~/.Trash/, volume trashes, .DS_Store, temporary items
Dev caches — npm, pnpm, yarn, pip, maven, gradle, docker, homebrew, Xcode, Go, Rust, Cargo, node_modules, __pycache__
App residual files — orphaned data in ~/Library/Application Support/, Preferences/, Containers/ from uninstalled apps
Large single files — individual files >100MB in ~/Downloads, ~/Desktop, ~/Documents, ~/Movies, ~/Library/Logs, ~/Library/Caches (installers, archives, VM images, oversized logs)

Phase 2: Report

Present the scan results to the user in a clear, organized format:

Group items by category
Show size for each item and category subtotal
Show grand total reclaimable space
Mark each item with safety level: [SAFE], [PARTIAL], [REVIEW]
Flag items requiring sudo with [SUDO]

If the scan was run with --json, parse the JSON and format a readable summary.

Example report structure:

[System Caches & Logs]  Total: 2.3 GB
   1.2 GB  User cache: com.apple.helpd  [SAFE]
          Path: ~/Library/Caches/com.apple.helpd
   850 MB  User cache: com.google.Chrome  [SAFE]
          Path: ~/Library/Caches/com.google.Chrome
   ...

[Development Caches]  Total: 8.7 GB
   3.2 GB  Xcode DerivedData (build cache)  [SAFE]
   2.1 GB  Maven repository cache  [SAFE]
   1.5 GB  Docker: Images 1.2GB reclaimable  [SAFE]
   ...

Grand Total Reclaimable: 12.4 GB

Phase 3: Confirm

Ask the user which categories and items to clean. Present options:

Clean all [SAFE] items — recommended, lowest risk
Clean specific categories — let the user pick (caches, trash, dev, app_residual, large_files)
Clean specific items — let the user select individual paths from the report
Include [PARTIAL] / [REVIEW] items — requires explicit per-item confirmation
Dry run first — show exactly what will be moved before doing anything

Note on large files: The large_files category is always marked [REVIEW] because single large files may be important (personal videos, project assets, legitimate disk images). Always list the individual files with their modification dates and let the user decide which to remove. Prefer removing older files (installers and archives from months/years ago are usually safe).

Never proceed without explicit user confirmation. If the user says "just clean everything safe," that counts as confirmation for [SAFE] items only.

Phase 4: Clean

Execute the cleanup using move_to_trash.py:

Option A: Clean from JSON report

# Dry run first — show what would be moved
python3 scripts/move_to_trash.py --from-json /tmp/scan_report.json --dry-run

# If the dry run looks correct, run for real
python3 scripts/move_to_trash.py --from-json /tmp/scan_report.json

Option B: Clean specific paths

python3 scripts/move_to_trash.py ~/Library/Caches/com.apple.helpd ~/.npm/_cacache

Option C: Run special cleanup commands

Some dev caches are better cleaned via their own tools:

# Homebrew — removes old versions
python3 scripts/move_to_trash.py --brew-cleanup
# Or directly: brew cleanup

# Docker — removes unused images, containers, volumes
python3 scripts/move_to_trash.py --docker-prune
# Or directly: docker system prune -a --volumes -f

Option D: Clean node_modules from old projects

If the scan found node_modules directories, list them and let the user choose:

# The scan report's "details" field contains individual node_modules paths
# Present them to the user and move selected ones to trash:
python3 scripts/move_to_trash.py /path/to/project1/node_modules /path/to/project2/node_modules

Option E: Clean large single files

Large files are always [REVIEW] — never batch-clean them from JSON. Instead, present the individual files (with sizes and modification dates) and move only the specific ones the user selects:

# Present the list from the scan report, then move selected files by absolute path:
python3 scripts/move_to_trash.py ~/Downloads/googlechrome.dmg ~/Movies/.pp.dmg

# Or run the large_files scan alone and review the output:
python3 scripts/scan_junk.py --category large_files
# Optional: change the threshold (e.g., find files > 500 MB)
python3 scripts/scan_junk.py --category large_files --min-size 500

After Cleaning

Report what was moved to Trash and how much space was reclaimed
Suggest emptying the Trash from Finder when the user is confident
Optionally re-run the scan to verify the cleanup

Category Details

For detailed information about each junk file location, safety level, and notes, refer to references/junk_locations.md.

Quick Reference: What's Safe vs. What Needs Review

Always safe to delete:

User caches (~/Library/Caches/<app>/)
User logs and crash reports (~/Library/Logs/)
Trash contents (~/.Trash/)
.DS_Store files
npm/pnpm/yarn caches
pip cache, __pycache__ directories
Maven repository, Gradle caches
Xcode DerivedData
Homebrew cache (use brew cleanup)
Docker unused resources (use docker system prune)
Go module cache, Cargo registry cache
node_modules in old projects (restorable via npm install)

Needs review:

App residual files in ~/Library/Application Support/ (may contain user data)
Xcode Archives (may contain needed archives)
iOS Simulator Devices (may contain app data for testing)
.plist preference files (usually small, not worth the risk)
Large single files >100MB (could be installers, old archives, VM images, or personal media — review dates)

Never touch:

/private/var/folders/ (system-managed)
/System/ (OS core)
~/Library/ root directory (only clean subdirectories)
iCloud Drive contents
Personal media in ~/Movies, ~/Pictures, ~/Music (excluded from automatic scans)

Script Reference

scripts/scan_junk.py

Read-only scanner. Identifies junk files across five categories and reports sizes.

# Full scan with table output
python3 scripts/scan_junk.py

# JSON output to file for programmatic processing
python3 scripts/scan_junk.py --json --output /tmp/scan_report.json

# Scan only development caches
python3 scripts/scan_junk.py --category dev

scripts/move_to_trash.py

Safe mover. Moves files/directories to macOS Trash (recoverable). Enforces safety checks — blocks system-critical paths automatically.

# Move specific paths to Trash
python3 scripts/move_to_trash.py ~/Library/Caches/com.example.app ~/.npm/_cacache

# Move from JSON scan report (only SAFE items)
python3 scripts/move_to_trash.py --from-json /tmp/scan_report.json

# Dry run — preview without moving
python3 scripts/move_to_trash.py --from-json /tmp/scan_report.json --dry-run

# Include PARTIAL/REVIEW items (use with caution)
python3 scripts/move_to_trash.py --from-json /tmp/scan_report.json --include-unsafe

# Run Homebrew cleanup
python3 scripts/move_to_trash.py --brew-cleanup

# Run Docker prune
python3 scripts/move_to_trash.py --docker-prune

Error Handling

Permission denied: Some system caches require sudo. Skip these and note them in the report. Do not attempt to use sudo with the scripts unless the user explicitly asks and understands the risks.
Path not found: The scan may report paths that no longer exist by the time cleanup runs. move_to_trash.py handles this gracefully and reports skipped items.
Finder locked file: If Finder refuses to move a file (e.g., it's in use), move_to_trash.py tries alternative methods (System Events, trash CLI). If all methods fail, report the item to the user — they may need to close the app first.
Docker not running: If Docker is not running, docker system df will fail silently. The scan skips Docker in this case. Mention to the user that Docker cleanup is available if they start Docker.