/disk-analyze

Disk Analysis and Cleanup Command

IMPORTANT: This command is designed and tested for macOS only. It uses macOS-specific paths and utilities.

Your task is to help the user analyze disk usage, identify large files and directories consuming space, provide categorized cleanup recommendations, and optionally execute approved cleanup operations.

Context: Current Disk Status

First, check the current disk usage:

!df -h

This shows the overall disk space availability on all mounted filesystems.

Step 1: System Analysis

Perform a comprehensive disk analysis:

1.1 Overall Disk Usage

Parse the df -h output and identify:

• The main disk (usually / or /System/Volumes/Data on macOS)
• Total capacity
• Used space
• Available space
• Percentage used

Present this information clearly:

Disk Usage Summary
==================
Main Disk: [name]
Capacity: X.XX GB
Used: X.XX GB (XX%)
Available: X.XX GB

1.2 Find Largest Directories

Run these commands to identify space hogs:

1. Top 10 largest directories in home folder:

   du -h -d 1 ~ 2>/dev/null | sort -hr | head -10
   

2. Large directories in common locations:

   du -h -d 1 ~/Library 2>/dev/null | sort -hr | head -10
   du -h -d 1 ~/Downloads 2>/dev/null | sort -hr | head -5
   

Present the findings:

Largest Directories
===================

Home Directory (~):
1. [directory] - X.XX GB
2. [directory] - X.XX GB
...

Library (~Library):
1. [directory] - X.XX GB
2. [directory] - X.XX GB
...

1.3 Identify Specific Cleanup Targets

Check common space hogs:

1. Old Downloads (files older than 30 days):

   find ~/Downloads -type f -mtime +30 -exec ls -lh {} \; 2>/dev/null | head -20
   

   Count and calculate total size

2. Application Caches:

   du -sh ~/Library/Caches 2>/dev/null
   

3. System Logs:

   du -sh ~/Library/Logs 2>/dev/null
   

4. Trash:

   du -sh ~/.Trash 2>/dev/null
   

5. Temporary files:

   du -sh /tmp 2>/dev/null
   

Step 2: Provide Cleanup Recommendations

Based on the analysis, present categorized recommendations:

Cleanup Recommendations
=======================

SAFE (Low Risk)
---------------
These operations are generally safe and reversible:

1. Empty Trash (~/.Trash)
   Estimated space: X.XX GB
   Risk: Low - items can be restored before emptying

2. Old Downloads (files >30 days old)
   Estimated space: X.XX GB
   Risk: Low - review list before deletion

3. Clear temporary files (/tmp)
   Estimated space: X.XX MB
   Risk: Low - system recreates as needed


MODERATE (Medium Risk)
----------------------
These require some review before deletion:

4. Application Caches (~/Library/Caches)
   Estimated space: X.XX GB
   Risk: Medium - apps will rebuild caches, may slow down temporarily

5. System Logs (~/Library/Logs)
   Estimated space: X.XX MB
   Risk: Medium - useful for troubleshooting recent issues


CAREFUL (Higher Risk)
---------------------
These require careful review and may affect functionality:

6. Large files in specific directories
   [List specific large files found]
   Risk: Varies - requires manual review

Step 3: Ask for User Confirmation

Present cleanup options:

What would you like to do?

1. Review and clean specific items
   - I'll show you each category and you can approve individually

2. Quick clean (Safe items only)
   - Empty Trash
   - Clear temporary files
   - Estimated space freed: X.XX GB

3. Generate detailed report only
   - No cleanup, just save findings to a file

4. Cancel
   - Exit without making changes

Ask the user: "Which option would you like? (Enter 1, 2, 3, or 4)"

Wait for the user's response.

Step 4: Cleanup Phase (if approved)

Option 1: Review and Clean Specific Items

For each recommendation, ask the user:

For Trash:

ls -lh ~/.Trash | head -10

Show first 10 items, then ask: "Empty trash (~/.Trash)? This will permanently delete X.XX GB. (y/n)"

If yes:

rm -rf ~/.Trash/*

For Old Downloads:

find ~/Downloads -type f -mtime +30 -exec ls -lh {} \;

Show the list and ask: "Delete these files from Downloads? (y/n)"

If yes:

find ~/Downloads -type f -mtime +30 -delete

For Application Caches: Show size and ask: "Clear application caches (~/Library/Caches)? Apps will rebuild as needed. (y/n)"

If yes:

rm -rf ~/Library/Caches/*

For System Logs: Ask: "Clear system logs (~/Library/Logs)? (y/n)"

If yes:

rm -rf ~/Library/Logs/*

For Temporary Files: Ask: "Clear temporary files (/tmp)? (y/n)"

If yes:

sudo rm -rf /tmp/*

Option 2: Quick Clean (Safe Items Only)

First, show the user what will be cleaned:

Quick Clean Summary
===================
The following items will be deleted:

1. Trash (~/.Trash)
   - Size: X.XX GB

2. Temporary files (/tmp)
   - Size: X.XX MB

Total Space to be Freed: X.XX GB

Ask for final confirmation: "Proceed with quick clean? This will permanently delete the items listed above. (y/n)"

Wait for user response.

If user confirms (y):

Execute these commands in sequence:

1. Empty Trash:

   rm -rf ~/.Trash/*
   

   Report: "✓ Emptied Trash"

2. Clear temporary files:

   sudo rm -rf /tmp/*
   

   Report: "✓ Cleared temporary files"

Report total space freed.

If user declines (n):

Respond: "Quick clean cancelled. No changes were made."

Option 3: Generate Detailed Report

Create a report file:

cat > ~/disk-analysis-report.txt <<EOF
Disk Analysis Report
Generated: $(date)

[Include all analysis findings]
EOF

Tell user: "Report saved to ~/disk-analysis-report.txt"

Option 4: Cancel

Respond: "Disk analysis complete. No changes were made."

Step 5: Final Report

After any cleanup operations:

1. Run final disk check:

   df -h
   

2. Calculate space freed:

   • Compare before/after disk usage
   • Show specific space reclaimed

3. Present final report:

Disk Cleanup Complete!
======================

Space Reclaimed: X.XX GB

Current Disk Status:
- Total: X.XX GB
- Used: X.XX GB (XX%)
- Available: X.XX GB

Items Cleaned:
✓ [Item 1] - X.XX GB freed
✓ [Item 2] - X.XX GB freed
...

Next Steps:
- Run this command monthly to maintain disk space
- Consider removing large unused applications
- Review Downloads folder regularly
- For more aggressive cleanup, consider:
  - `docker system prune -a` (if using Docker)
  - Clearing Xcode derived data (if using Xcode)
  - Clearing Homebrew cache: `brew cleanup`

Error Handling

If commands fail:

1. Permission errors:

   • "Permission denied error occurred"
   • "Some operations may require administrator access"
   • "Try running specific commands with 'sudo' if needed"

2. File not found:

   • Skip that item gracefully
   • Continue with other cleanup operations
   • Note in final report which items were skipped

3. Disk full:

   • "Disk is critically low on space"
   • "Recommend starting with Trash and Downloads cleanup"
   • "Consider moving large files to external storage"

If critical commands fail:

• Show the error message
• Suggest manual alternatives
• Provide command examples user can run directly

Validation Criteria

Success indicators:

• Disk usage analysis completes successfully
• Recommendations are clear and categorized by risk
• Space savings estimates are accurate
• User receives explicit confirmation prompts
• Final report shows actual space freed

Safety checks:

• Never delete files without explicit confirmation
• Show preview of files before deletion
• Categorize operations by risk level
• Provide undo suggestions where possible
• Only delete from known safe locations (Trash, tmp, caches)

Additional Tips for User

Include in final output:

Pro Tips for Disk Management:
- Use `du -sh * | sort -hr | head -20` to find large items in any directory
- macOS Storage Management: System Settings > General > Storage
- Consider cloud storage for large media files
- Regular maintenance prevents critical low-disk situations
- Check for large files: `find ~ -type f -size +1G 2>/dev/null`