claude-code-skills-reference/macos-cleaner/references/cleanup_targets.md

macOS Cleanup Targets Reference

Detailed explanations of cleanup targets, their safety levels, and impact.

System Caches

~/Library/Caches

What it is: Application-level cache storage for user applications.

Contents:

• Browser caches (Chrome, Firefox, Safari)
• Application temporary files
• Download caches
• Thumbnail caches
• Font caches

Safety: 🟢 Safe to delete

Impact:

• Apps may be slower on first launch after deletion
• Websites may load slower on first visit (need to re-download assets)
• No data loss (caches are regenerated)

Size: Typically 10-100 GB depending on usage

Cleanup command:

rm -rf ~/Library/Caches/*

/Library/Caches

What it is: System-level cache storage (shared across all users).

Safety: 🟢 Safe to delete (requires sudo)

Impact: Same as user caches, but system-wide

Cleanup command:

sudo rm -rf /Library/Caches/*

Package Manager Caches

Homebrew Cache

Location: $(brew --cache) (typically ~/Library/Caches/Homebrew)

What it is: Downloaded package installers and build artifacts

Safety: 🟢 Safe to delete

Impact: Will need to re-download packages on next install/upgrade

Cleanup:

brew cleanup -s          # Safe cleanup (removes old versions)
brew cleanup --prune=all # Aggressive cleanup (removes all cached downloads)

npm Cache

Location: ~/.npm or configured cache directory

Safety: 🟢 Safe to delete

Impact: Packages will be re-downloaded when needed

Cleanup:

npm cache clean --force

pip Cache

Location: ~/Library/Caches/pip (macOS)

Safety: 🟢 Safe to delete

Impact: Packages will be re-downloaded when needed

Cleanup:

pip cache purge
# or for pip3
pip3 cache purge

Application Logs

~/Library/Logs

What it is: Application log files

Safety: 🟢 Safe to delete

Impact: Loss of diagnostic information (only matters if debugging)

Typical size: 1-20 GB

Cleanup:

rm -rf ~/Library/Logs/*

/var/log (System Logs)

What it is: System and service log files

Safety: 🟢 Safe to delete old logs (requires sudo)

Impact: Loss of system diagnostic history

Note: macOS automatically rotates logs, manual deletion rarely needed

Application Data

~/Library/Application Support

What it is: Persistent application data, settings, and databases

Safety: 🟡 Caution required

Contains:

• Application databases
• User preferences and settings
• Downloaded content
• Plugins and extensions
• Save games

When safe to delete:

• Application is confirmed uninstalled
• Folder belongs to trial software no longer used
• Folder is for outdated version of app (check first!)

When to KEEP:

• Active applications
• Any folder you're uncertain about

Recommendation: Use find_app_remnants.py to identify orphaned data

~/Library/Containers

What it is: Sandboxed application data (for App Store apps)

Safety: 🟡 Caution required

Same rules as Application Support - only delete for uninstalled apps

~/Library/Preferences

What it is: Application preference files (.plist)

Safety: 🟡 Caution required

Impact of deletion: App returns to default settings

When to delete:

• App is confirmed uninstalled
• Troubleshooting a misbehaving app (as last resort)

Development Environment

Docker

ABSOLUTE RULE: NEVER use any prune command (docker image prune, docker volume prune, docker system prune, docker container prune). Always delete by specifying exact object IDs or names.

Images

What it is: Container images (base OS + application layers)

Safety: 🟡 Requires per-image verification

Analysis:

# List all images sorted by size
docker images --format "table {{.ID}}\t{{.Repository}}:{{.Tag}}\t{{.Size}}\t{{.CreatedSince}}" | sort -k3 -h -r

# Identify dangling images
docker images -f "dangling=true" --format "{{.ID}}\t{{.Size}}\t{{.CreatedSince}}"

# For EACH image, verify no container references it
docker ps -a --filter "ancestor=<IMAGE_ID>" --format "{{.Names}}\t{{.Status}}"

Cleanup (only after per-image verification):

# Remove specific images by ID
docker rmi a02c40cc28df 555434521374 f471137cd508

Containers

What it is: Running or stopped container instances

Safety: 🟡 Stopped containers may be restarted -- verify with user

Analysis:

docker ps -a --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Size}}"

Cleanup (only after user confirms each container/project):

# Remove specific containers by name
docker rm container-name-1 container-name-2

Volumes

What it is: Persistent data storage for containers

Safety: 🔴 CAUTION - May contain databases, user uploads, and irreplaceable data

Analysis:

# List all volumes
docker volume ls

# Check which container uses each volume
docker ps -a --filter "volume=<VOLUME_NAME>" --format "{{.Names}}\t{{.Status}}"

# CRITICAL: For database volumes (mysql, postgres, redis in name), inspect contents
docker run --rm -v <VOLUME_NAME>:/data alpine ls -la /data
docker run --rm -v <VOLUME_NAME>:/data alpine du -sh /data/*

Cleanup (only after per-volume confirmation, database volumes require content inspection):

# Remove specific volumes by name
docker volume rm project-mysql-data project-redis-data

Build Cache

What it is: Intermediate build layers

Safety: 🟢 Safe to delete (rebuilds just take longer)

Note: docker builder prune is the ONE exception to the prune prohibition -- build cache contains only intermediate layers, never user data.

Cleanup:

docker builder prune -a

node_modules

What it is: Installed npm packages for Node.js projects

Safety: 🟢 Safe to delete (can be regenerated)

Impact: Need to run npm install to restore

Finding large node_modules:

find ~ -name "node_modules" -type d -prune -print 2>/dev/null | while read dir; do
  du -sh "$dir"
done | sort -hr

Cleanup:

# For old projects
rm -rf /path/to/old-project/node_modules

Python Virtual Environments

What it is: Isolated Python environments

Location: venv/, .venv/, env/ in project directories

Safety: 🟢 Safe to delete (can be recreated)

Impact: Need to recreate virtualenv and reinstall packages

Finding venvs:

find ~ -type d -name "venv" -o -name ".venv" 2>/dev/null

Git Repositories (.git directories)

What it is: Git version control data

Safety: 🟡 Depends on use case

When SAFE to delete:

• Project is archived and you have remote backup
• You only need final code, not history

When to KEEP:

• Active development
• No remote backup exists
• You might need the history

Cleanup (convert to plain folder, lose history):

rm -rf /path/to/old-project/.git

Large Files

Downloads Folder

What it is: Files downloaded from internet

Safety: 🟡 User judgment required

Common cleanable items:

• Old installers (.dmg, .pkg)
• Zip archives already extracted
• Temporary downloads
• Duplicate files

Check before deleting: Might contain important downloads

Disk Images (.dmg, .iso)

What it is: Mountable disk images, often installers

Safety: 🟢 Safe to delete after installation

Typical location: ~/Downloads

Cleanup: Delete .dmg files for already-installed apps

Archives (.zip, .tar.gz)

What it is: Compressed archives

Safety: 🟡 Check if extracted

Before deleting: Verify contents are extracted elsewhere

Old iOS Backups

Location: ~/Library/Application Support/MobileSync/Backup/

What it is: iTunes/Finder iPhone/iPad backups

Safety: 🟡 Caution - backup data

Check:

ls -lh ~/Library/Application\ Support/MobileSync/Backup/

Cleanup: Delete old backups via Finder preferences, not manually

Old Time Machine Local Snapshots

What it is: Local Time Machine backups

Safety: 🟢 Safe - macOS manages automatically

macOS automatically deletes these when disk space is low

Check:

tmutil listlocalsnapshots /

Manual cleanup (rarely needed):

tmutil deletelocalsnapshots <snapshot_date>

What to NEVER Delete

User Data Directories

• ~/Documents
• ~/Desktop
• ~/Pictures
• ~/Movies
• ~/Music

System Files

• /System
• /Library/Apple (unless you know what you're doing)
• /private/etc

Security & Credentials

• ~/.ssh (SSH keys)
• ~/Library/Keychains (passwords, certificates)
• Any files containing credentials

Active Databases

• *.db, *.sqlite files for running applications
• Docker volumes in active use

Safety Checklist

Before deleting ANY directory:

1. ✅ Do you know what it is?
2. ✅ Is the application truly uninstalled?
3. ✅ Have you checked if it's in use? (lsof, Activity Monitor)
4. ✅ Do you have a Time Machine backup?
5. ✅ Have you confirmed with the user?

When in doubt, DON'T DELETE.

Recovery Options

Trash vs. Permanent Deletion

Use Trash when possible:

# Move to trash (recoverable)
osascript -e 'tell app "Finder" to move POSIX file "/path/to/file" to trash'

Permanent deletion:

# Cannot be recovered without Time Machine
rm -rf /path/to/file

Time Machine

If you deleted something important:

1. Open Time Machine
2. Navigate to parent directory
3. Select date before deletion
4. Restore

File Recovery Tools

If no Time Machine backup:

• Disk Drill (commercial)
• PhotoRec (free, for photos)
• TestDisk (free, for files)

Note: Success rate depends on how recently deleted and disk usage since deletion.