Document Version: 1.0
Date: October 6, 2025
Author: Shaswat Raj (Shade Solutions)
Status: Draft
Target Release: Q1 2026
- Executive Summary
- Product Vision
- Goals & Success Metrics
- User Personas
- Feature Requirements
- UX Improvements
- Technical Requirements
- Implementation Phases
- Risk Assessment
- Future Considerations
CleanMac v2.0 aims to transform the current functional cleanup tool into a polished, professional-grade macOS maintenance utility with enhanced user experience, advanced customization options, and intelligent automation features. The update focuses on three pillars: Power, Personalization, and Polish.
- Improve terminal UX with modern UI elements and better feedback
- Add intelligent cleanup recommendations based on usage patterns
- Provide granular control over cleanup operations
- Implement safety features like dry-run mode and backup options
- Enhance reporting and analytics capabilities
"Make CleanMac the most intuitive, safe, and powerful macOS cleanup tool that developers trust and recommend."
- Users feel confident running CleanMac without fear of data loss
- Average cleanup time reduced by 40% through smart recommendations
- 80% of users enable scheduled automatic cleanups
- Featured in developer communities and recommended by influencers
| Goal | Metric | Target |
|---|---|---|
| Improve User Confidence | Net Promoter Score (NPS) | > 70 |
| Increase Adoption | Weekly Active Users | 10K+ |
| Enhance Safety | Zero data loss incidents | 100% |
| Boost Efficiency | Average cleanup time | < 2 minutes |
| Drive Engagement | Return user rate | > 60% monthly |
- GitHub Stars: 1,000+
- Community contributions: 20+ PRs
- Documentation completeness: 100%
- Test coverage: > 80%
Profile: Full-stack developer, 3+ years experience
Pain Points:
- Runs out of disk space during builds
- Doesn't know what's safe to delete
- Wants quick cleanup without interrupting workflow Needs:
- Fast, automated cleanups
- Clear space estimates before cleanup
- Integration with git workflows
Profile: Junior developer, cautious about system changes
Pain Points:
- Afraid of deleting important files
- Wants to preview changes before applying
- Needs detailed logs for reference Needs:
- Dry-run mode to preview deletions
- Detailed explanations of what each option does
- Ability to undo or restore
Profile: DevOps engineer, manages multiple projects
Pain Points:
- Needs customization for specific workflows
- Wants to automate cleanup schedules
- Requires detailed reports and analytics Needs:
- Config file support for custom rules
- CLI flags for automation
- Export reports in multiple formats
Priority: HIGH
Effort: Medium
# Non-interactive modes
cleanmac --all # Run all cleanups without prompts
cleanmac --preset web # Run web-dev preset (npm, node_modules, etc.)
cleanmac --preset ios # Run iOS-dev preset (Xcode, CocoaPods, etc.)
cleanmac --preset docker # Run Docker cleanup only
# Selective cleanup
cleanmac --only npm,yarn,docker # Clean specific categories
cleanmac --exclude xcode # Clean everything except Xcode
# Path-specific cleanup (NEW - Enhanced Safety)
cleanmac --path ~/Desktop # Only scan and clean in specific directory
cleanmac --path ~/Projects --recursive # Recursive cleanup in directory
cleanmac --paths ~/Desktop,~/Documents # Multiple paths
cleanmac --depth 3 # Max directory depth for scanning
# Automation flags
cleanmac --dry-run # Preview what will be deleted
cleanmac --yes # Auto-confirm all prompts
cleanmac --quiet # Minimal output
cleanmac --verbose # Detailed logging
cleanmac --interactive # Ask before each category/file
# Safety features (ENHANCED)
cleanmac --safe # Skip aggressive cleanups
cleanmac --backup # Create restore point before cleanup
cleanmac --max-age 30 # Only delete files older than 30 days
cleanmac --min-size 100MB # Only delete files/folders larger than size
cleanmac --show-details # Show full file list before deletion
cleanmac --confirm-each # Confirm each file/folder individually
# Output options
cleanmac --json # Output results as JSON
cleanmac --log report.txt # Save detailed log to file
cleanmac --summary # Show only summary statistics
cleanmac --tree # Show tree view of what will be deleted- All flags work independently and in combination
- Dry-run mode shows accurate preview without making changes
- JSON output is valid and machine-parseable
- Help text (
--help) is comprehensive and clear - Path-specific scanning works correctly with depth limits
- Interactive confirmations prevent accidental deletions
- File size and age filters work accurately
Priority: HIGH
Effort: Medium
$ cleanmac --path ~/Desktop --only node_modules --show-details
🔍 Scanning ~/Desktop for node_modules...
Found 5 node_modules directories:
┌────────────────────────────────────────────────────────────────┐
│ PATH SIZE FILES MODIFIED │
├────────────────────────────────────────────────────────────────┤
│ ~/Desktop/my-app/node_modules 450MB 1,234 2h ago │
│ ~/Desktop/old-project/node_modules 380MB 987 45d ago │
│ ~/Desktop/test/node_modules 120MB 456 3mo ago │
│ ~/Desktop/tutorial/node_modules 290MB 678 89d ago │
│ ~/Desktop/demo/node_modules 156MB 345 1y ago │
└────────────────────────────────────────────────────────────────┘
Total: 1.4GB across 5 directories
Options:
[A] Delete all
[S] Select which ones to delete
[N] Show newest first
[O] Show oldest first
[L] Show largest first
[F] Filter by age/size
[Q] Cancel
Your choice: _# After choosing [S] Select
┌────────────────────────────────────────────────────────────────┐
│ Select directories to delete (Space to toggle, Enter to confirm) │
├────────────────────────────────────────────────────────────────┤
│ [ ] ~/Desktop/my-app/node_modules 450MB 2h ago │
│ ⚠️ Recently modified - might be in active use │
│ │
│ [✓] ~/Desktop/old-project/node_modules 380MB 45d ago │
│ ✅ Safe to delete - not modified in 45 days │
│ │
│ [✓] ~/Desktop/test/node_modules 120MB 3mo ago │
│ ✅ Safe to delete - not modified in 3 months │
│ │
│ [✓] ~/Desktop/tutorial/node_modules 290MB 89d ago │
│ ✅ Safe to delete - not modified in 89 days │
│ │
│ [✓] ~/Desktop/demo/node_modules 156MB 1y ago │
│ ✅ Safe to delete - not modified in 1 year │
└────────────────────────────────────────────────────────────────┘
Selected: 4/5 directories (946MB)
[Space] Toggle [A] All [N] None [I] Invert [Enter] Delete [Q] Cancel$ cleanmac --path ~/Desktop --only node_modules --max-age 30
🔍 Scanning ~/Desktop for node_modules older than 30 days...
Found 3 directories (excluding 2 recently modified):
WILL DELETE:
✓ ~/Desktop/old-project/node_modules 380MB 45 days old
✓ ~/Desktop/tutorial/node_modules 290MB 89 days old
✓ ~/Desktop/demo/node_modules 156MB 365 days old
WILL SKIP (Modified within 30 days):
× ~/Desktop/my-app/node_modules 450MB 0 days old
× ~/Desktop/new-project/node_modules 200MB 5 days old
Total to delete: 826MB
Total to keep: 650MB
Proceed? [Y/n]$ cleanmac --path ~/Desktop --tree --dry-run
📁 ~/Desktop (scanning depth: 3)
│
├─ 🗑️ my-app/
│ ├─ 🗑️ node_modules/ 450MB ⚠️ 2h ago
│ └─ 🗑️ .next/ 180MB ⚠️ 1d ago
│
├─ 🗑️ old-project/
│ ├─ 🗑️ node_modules/ 380MB ✅ 45d ago
│ ├─ 🗑️ dist/ 25MB ✅ 45d ago
│ └─ 🗑️ build/ 15MB ✅ 45d ago
│
├─ 🗑️ test/
│ └─ 🗑️ node_modules/ 120MB ✅ 3mo ago
│
└─ 📂 important-docs/
└─ 📄 (protected - no deletions)
Legend:
🗑️ Will be deleted
📂 Will be scanned but protected
⚠️ Recently modified (< 7 days)
✅ Safe to delete (> 7 days old)
Total: 1.2GB across 6 items- Preview shows accurate file counts and sizes
- Selective deletion interface is intuitive
- Age-based filtering correctly identifies files
- Tree visualization renders correctly
- Recently modified files are clearly marked
Priority: HIGH
Effort: Medium
Create ~/.cleanmac/config.yml for persistent settings:
# CleanMac Configuration File
# General Settings
settings:
confirm_prompts: true
show_disk_usage: true
color_output: true
backup_before_cleanup: false
max_file_age_days: null # null = delete all
# Cleanup Presets
presets:
web-dev:
- node_modules
- npm_cache
- yarn_cache
- pnpm_cache
mobile-dev:
- xcode
- cocoapods
- android_gradle
docker-dev:
- docker
- kubernetes
# Scan Paths (NEW - Enhanced Control)
scan_paths:
enabled: true
default_paths:
- "~/Desktop"
- "~/Documents"
- "~/Projects"
excluded_paths:
- "~/Documents/Important"
- "~/Desktop/Client Work"
max_depth: 5 # How deep to scan in directory tree
follow_symlinks: false
# Custom Rules
custom_rules:
- name: "Old Build Artifacts"
paths:
- "~/Projects/**/build"
- "~/Projects/**/dist"
max_age_days: 7
min_size: "10MB" # Only delete if larger than this
- name: "Test Coverage Reports"
paths:
- "~/Projects/**/coverage"
- "~/Projects/**/.nyc_output"
max_age_days: 30
- name: "Stale Node Modules on Desktop"
paths:
- "~/Desktop/**/node_modules"
max_age_days: 30
min_size: "100MB"
confirm_each: true # Ask before deleting each one
# Exclusions (never delete)
exclusions:
paths:
- "~/Projects/important-client/**"
- "~/Documents/Backup/**"
- "~/Desktop/Active Projects/**"
patterns:
- "*.env"
- "*.key"
- "*.pem"
- "*.config.js" # Don't delete config files
- "**/node_modules/.cache" # Keep specific caches
# Protect recently modified files
protect_recent:
enabled: true
threshold_days: 7 # Don't delete files modified in last 7 days
show_warning: true # Warn user about protected files
# Size Thresholds
size_thresholds:
large_file_warning: "1GB"
total_cleanup_warning: "50GB"
min_cleanup_size: "10MB" # Don't bother with tiny files
# Safety Settings (NEW)
safety:
require_confirmation: true
show_file_list: true # Always show what will be deleted
dry_run_first: false # Suggest dry-run before actual deletion
max_files_per_operation: 10000 # Safety limit
# Notifications
notifications:
desktop_notification: true
sound_on_complete: false
slack_webhook: null # Optional: post results to Slack
# Transparency & Reporting (NEW)
transparency:
show_size_before_delete: true
show_file_count: true
show_last_modified: true
log_all_operations: true
save_deleted_manifest: true # Save list of deleted files
manifest_path: "~/.cleanmac/manifests/"
# Scheduled Cleanup
schedule:
enabled: false
frequency: "weekly" # daily, weekly, monthly
day: "sunday"
time: "03:00"
preset: "web-dev"
skip_if_disk_usage_below: 70 # Only run if disk usage > 70%- Config file is validated on load with helpful error messages
- Custom rules work with glob patterns
- Exclusions override cleanup selections
- Config can be created via
cleanmac --init-config - Path-specific scanning respects depth limits
- Recently modified files are protected when enabled
- Manifest of deleted files is saved for audit trail
Priority: HIGH
Effort: Medium
$ cleanmac --configure-paths
📁 Configure Scan Paths
Current scan paths:
1. ~/Desktop (depth: 5)
2. ~/Documents (depth: 5)
3. ~/Projects (depth: 3)
Options:
[A] Add new path
[R] Remove path
[E] Edit path settings
[T] Test scan (dry-run)
[S] Save and exit
Choice: A
Enter path to add: ~/Downloads
Maximum scan depth [5]: 2
Scan this path? [Y/n]: y
✅ Added ~/Downloads with depth 2$ cleanmac --rule "Old Desktop Node Modules"
Applying rule: "Old Desktop Node Modules"
├─ Paths: ~/Desktop/**/node_modules
├─ Max age: 30 days
├─ Min size: 100MB
└─ Confirm each: Yes
🔍 Scanning...
Found 3 matching directories:
1. ~/Desktop/old-project/node_modules
├─ Size: 380MB
├─ Age: 45 days
├─ Last modified: 2025-08-22
└─ Delete? [Y/n/s(kip all)]: y
2. ~/Desktop/tutorial/node_modules
├─ Size: 290MB
├─ Age: 89 days
├─ Last modified: 2025-07-09
└─ Delete? [Y/n/s]: y
3. ~/Desktop/test/node_modules
├─ Size: 120MB
├─ Age: 90 days
├─ Last modified: 2025-07-08
└─ Delete? [Y/n/s]: y
Summary: 3/3 deleted, 790MB freed$ cleanmac --whitelist ~/Desktop/active-project
🔒 Adding to whitelist: ~/Desktop/active-project
This directory and all subdirectories will be:
• Excluded from all scans
• Protected from deletion
• Marked as "active" in dashboard
Whitelist expiry:
[1] 7 days
[2] 30 days
[3] Permanent
[4] Custom
Choice: 1
✅ Whitelisted until 2025-10-13- Path configuration is persistent
- Rule-based cleanup works accurately
- Whitelist prevents accidental deletion
- Individual confirmations work correctly
Priority: HIGH
Effort: High
╔════════════════════════════════════════════════════════════════╗
║ 🧹 CleanMac v2.0 — macOS Developer System Cleaner ║
╚════════════════════════════════════════════════════════════════╝
📊 System Status
├─ Disk Usage: 245GB used / 98GB free (72%)
├─ Potential Gain: ~35GB (estimated)
└─ Last Cleanup: 5 days ago
┌────────────────────────────────────────────────────────────────┐
│ QUICK ACTIONS │
├────────────────────────────────────────────────────────────────┤
│ Q Quick Clean (recommended) Est. gain: ~12GB │
│ A Aggressive Clean (everything) Est. gain: ~35GB │
│ C Custom Selection │
└────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────┐
│ CATEGORIES SIZE STATUS │
├────────────────────────────────────────────────────────────────┤
│ [ ] 1. Project Folders 8.2GB ⚠️ │
│ └─ node_modules, .next, dist, build │
│ └─ [C] Configure paths and filters │
│ [ ] 2. Package Managers 3.5GB ⚠️ │
│ └─ npm, yarn, pnpm caches │
│ [✓] 3. Homebrew 1.8GB ⚠️ │
│ └─ brew cache and old versions │
│ [ ] 4. Xcode 12GB ⚠️ │
│ └─ DerivedData, Archives, DeviceSupport │
│ [ ] 5. Docker 4.2GB ⚠️ │
│ └─ Unused images and containers │
│ [ ] 6. Application Caches 2.1GB ⚡ │
│ └─ VSCode, Chrome, Slack, Discord │
│ [ ] 7. System Logs & Caches 890MB ⚡ │
│ [ ] 8. Downloads & Trash 1.2GB ⚡ │
│ └─ [P] Preview files before deletion │
│ [ ] 9. Large Files (>1GB) 3.4GB ⚡ │
└────────────────────────────────────────────────────────────────┘
Commands: [Space] Select [A] Select All [N] None [Enter] Clean
[D] Dry Run [S] Settings [H] Help [P] Preview [Q] Quit
[C] Configure category [F] Apply filters
Selection: _
🧹 Cleaning in progress...
[████████████████░░░░░░░░░░░░] 65% (7/12 tasks)
Current: Cleaning Xcode DerivedData
├─ Found: 156 files
├─ Size: 8.2GB
├─ Deleted so far: 5.4GB (65 files)
├─ Time: 00:02:34
└─ Speed: ~2.3MB/s
Recently Completed:
✅ Project folders 8.2GB freed (1,247 files)
✅ npm cache 2.1GB freed (423 files)
✅ Homebrew 1.8GB freed (156 files)
⏱️ Xcode DerivedData 5.4GB freed (in progress...)
Estimated time remaining: ~3 minutes
[Ctrl+C] to pause [S] to skip current [V] verbose mode
🧹 Cleaning Project Folders (Verbose Mode)
Scanning ~/Desktop...
├─ Found: ~/Desktop/old-project/node_modules (380MB)
├─ Found: ~/Desktop/test/node_modules (120MB)
├─ Found: ~/Desktop/tutorial/node_modules (290MB)
Deleting ~/Desktop/old-project/node_modules...
├─ Removing 987 files...
│ ├─ node_modules/.bin/
│ ├─ node_modules/react/
│ ├─ node_modules/react-dom/
│ ├─ node_modules/webpack/
│ └─ ... (983 more)
├─ ✅ Deleted 380MB
Deleting ~/Desktop/test/node_modules...
├─ Removing 456 files...
├─ ✅ Deleted 120MB
Total so far: 500MB freed (2/3 directories)
╔════════════════════════════════════════════════════════════════╗
║ ✨ Cleanup Complete! ║
╚════════════════════════════════════════════════════════════════╝
📊 SUMMARY
┌────────────────────────────────────────────────────────────────┐
│ Before: 245GB used / 98GB free (72%) │
│ After: 210GB used / 133GB free (61%) │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ Freed: 35GB │
│ Time: 4m 32s │
└────────────────────────────────────────────────────────────────┘
📋 BREAKDOWN
Category Files Size Freed Time
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Project Folders 1,247 8.2GB 45s
Package Manager Caches 423 3.5GB 12s
Homebrew Cache 156 1.8GB 8s
Xcode DerivedData 892 12.1GB 2m 15s
Docker 34 4.2GB 1m 2s
Application Caches 567 2.1GB 10s
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TOTAL 3,319 32.9GB 4m 32s
💡 RECOMMENDATIONS
• Your Xcode DerivedData grows fast. Consider cleaning weekly.
• 12 node_modules folders found. Try using pnpm with workspaces.
• Docker images consume 4.2GB. Run 'docker system prune' regularly.
📄 Full report saved to: ~/.cleanmac/reports/2025-10-06_14-23-45.log
Press [R] to view report [S] to share [Q] to quit
- Menu is responsive and works in terminals of all sizes
- Checkbox selection with space bar works smoothly
- Progress bars update in real-time
- Colors are accessible and work in light/dark terminals
- UI gracefully degrades in non-color terminals
Priority: MEDIUM
Effort: High
- Track cleanup history in
~/.cleanmac/history.json - Analyze which categories grow fastest
- Suggest optimal cleanup frequency per category
💡 Smart Recommendations (based on your usage)
HIGH PRIORITY (Do Now)
├─ Xcode DerivedData: 12GB (grows 2GB/week on average)
│ └─ Recommendation: Clean now, then schedule weekly cleanup
│
└─ node_modules: 8.2GB across 12 projects
└─ Recommendation: Consider switching to pnpm or yarn workspaces
MEDIUM PRIORITY (This Week)
├─ Docker: 4.2GB unused images
│ └─ 23 images haven't been used in 30+ days
│
└─ Homebrew: 1.8GB old versions
└─ 5 formula versions can be safely removed
LOW PRIORITY (Optional)
└─ npm cache: 3.5GB
└─ Last used 2 days ago, can wait until next scheduled cleanup
Would you like to clean HIGH priority items now? [Y/n]🔍 Detected Projects:
├─ ~/Projects/my-web-app (Next.js)
│ ├─ node_modules: 450MB (last build: 2 hours ago) [KEEP]
│ └─ .next: 180MB (stale build from 3 days ago) [CLEAN]
│
├─ ~/Projects/old-project (React)
│ ├─ node_modules: 380MB (last modified: 45 days ago) [CLEAN]
│ └─ build: 25MB (created 45 days ago) [CLEAN]
│
└─ ~/Documents/learning/tutorial-app
└─ node_modules: 290MB (last accessed: 3 months ago) [CLEAN]
Clean only stale project artifacts? [Y/n]- Recommendations are accurate and helpful
- Users can enable/disable smart suggestions
- Project detection works for major frameworks
- Stale vs. active projects correctly identified
Priority: HIGH
Effort: Low
// ~/.cleanmac/manifests/2025-10-06_14-23-45.json
{
"cleanup_id": "2025-10-06_14-23-45",
"timestamp": "2025-10-06T14:23:45Z",
"user": "shaswatraj",
"hostname": "Macbook-Pro.local",
"total_freed": "32.9GB",
"total_files": 3319,
"categories": [
{
"name": "Project Folders",
"size_freed": "8.2GB",
"files_deleted": 1247,
"items": [
{
"path": "~/Desktop/old-project/node_modules",
"size": "380MB",
"files": 987,
"last_modified": "2025-08-22T10:15:30Z",
"age_days": 45,
"deletable": true,
"reason": "Max age exceeded (45 > 30 days)"
},
{
"path": "~/Desktop/tutorial/node_modules",
"size": "290MB",
"files": 678,
"last_modified": "2025-07-09T14:22:10Z",
"age_days": 89,
"deletable": true,
"reason": "Max age exceeded (89 > 30 days)"
}
]
}
],
"config_snapshot": {
"max_age_days": 30,
"min_size": "10MB",
"scan_paths": ["~/Desktop", "~/Documents"]
}
}$ cleanmac --report --no-delete
📋 CLEANUP ANALYSIS REPORT
Generated: 2025-10-06 14:23:45
┌────────────────────────────────────────────────────────────────┐
│ EXECUTIVE SUMMARY │
├────────────────────────────────────────────────────────────────┤
│ Potential Space Savings: 32.9GB │
│ Total Files: 3,319 │
│ Risk Level: LOW ✅ │
│ Estimated Time: 4-5 minutes │
└────────────────────────────────────────────────────────────────┘
📊 BREAKDOWN BY SAFETY LEVEL
HIGH RISK ⚠️ (Review carefully)
├─ None
MEDIUM RISK ⚡ (Recently modified)
├─ ~/Desktop/my-app/node_modules (450MB, 2h old)
└─ Recommendation: Skip or verify not in use
LOW RISK ✅ (Safe to delete)
├─ ~/Desktop/old-project/node_modules (380MB, 45d old)
├─ ~/Desktop/tutorial/node_modules (290MB, 89d old)
├─ ~/Desktop/test/node_modules (120MB, 90d old)
└─ Total: 790MB across 3 directories
💾 POTENTIAL RECOVERY
├─ node_modules: Can rebuild with npm/yarn install
├─ npm cache: Can rebuild automatically
├─ Xcode DerivedData: Can rebuild on next build
└─ Docker images: Some may need re-download
📄 Report saved to: ~/.cleanmac/reports/analysis-2025-10-06.md- Manifests accurately log all deletions
- Reports provide actionable insights
- Risk levels are calculated correctly
- Manifests can be used for audit purposes
Priority: HIGH
Effort: Medium
$ cleanmac --dry-run --all
🔍 DRY RUN MODE - No files will be deleted
The following actions would be performed:
DELETE: ~/Library/Caches/Homebrew (1.8GB, 156 files)
DELETE: ~/Library/Developer/Xcode/DerivedData/* (12.1GB, 892 files)
DELETE: ~/.npm/_cacache (2.1GB, 234 files)
SKIP: ~/Projects/active-client/node_modules (protected by config)
Total impact: 32.9GB would be freed
Estimated time: ~4 minutes
Run 'cleanmac --all' to execute this cleanup.# Create restore point before cleanup
$ cleanmac --backup --all
📦 Creating restore point...
✅ Backup created: ~/.cleanmac/backups/2025-10-06_14-23-45/
Size: 156MB (metadata + critical configs)
# Restore if needed
$ cleanmac --restore 2025-10-06_14-23-45
🔄 Restoring from backup...
✅ Restored 23 paths⚠️ CONFIRMATION REQUIRED
You are about to delete:
├─ Downloads folder (1.2GB, 45 files)
├─ Trash (890MB)
└─ Temporary files (234MB)
Files that will be deleted:
• ~/Downloads/old-installer.dmg (450MB)
• ~/Downloads/project-backup.zip (380MB)
• ~/Downloads/screenshot-2025-08-*.png (15 files, 95MB)
• ... and 27 more files
⚠️ This action cannot be undone (unless --backup is enabled)
Type 'yes' to confirm, or 'n' to skip: _$ cleanmac --undo
📋 Last cleanup: 2025-10-06 14:23:45 (12 minutes ago)
Restorable items:
[✓] Homebrew cache metadata (can reinstall)
[✓] npm cache (can rebuild)
[✗] Xcode DerivedData (cannot restore, will rebuild on next build)
[✗] Trash (permanently deleted)
Restore what's possible? [Y/n]- Dry-run output is 100% accurate
- Backups are space-efficient (no duplicating large caches)
- Restore works reliably for supported items
- Clear warnings for non-restorable items
Priority: MEDIUM
Effort: Medium
$ cleanmac --all --log report.txtGenerated Report (Markdown format):
# CleanMac Cleanup Report
Generated: 2025-10-06 14:28:17
## Summary
- **Duration:** 4m 32s
- **Space Freed:** 32.9GB
- **Files Deleted:** 3,319
- **Categories Cleaned:** 6/12
## System Impact
| Metric | Before | After | Change |
|--------|--------|-------|--------|
| Used Space | 245GB | 210GB | -35GB |
| Free Space | 98GB | 133GB | +35GB |
| Usage % | 72% | 61% | -11% |
## Detailed Breakdown
### Project Folders (8.2GB freed)
- Deleted 12 `node_modules` directories
- Deleted 8 `dist` folders
- Deleted 5 `.next` build caches
...
## Recommendations
1. Schedule weekly Xcode cleanup (saves avg 12GB)
2. Consider using pnpm for better disk efficiency
3. Enable Docker auto-cleanup with `docker system prune` cron job
## Files Deleted (Top 20)
1. ~/Library/Developer/Xcode/DerivedData/MyApp-* (4.2GB)
2. ~/Projects/old-site/node_modules (890MB)
...- Text: Human-readable
.txt - Markdown:
.mdfor GitHub/documentation - JSON: Machine-readable for automation
- HTML: Visual report with charts
- CSV: Spreadsheet-compatible
$ cleanmac --history
📊 Cleanup History (Last 30 Days)
Date Space Freed Duration Categories
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
2025-10-06 32.9GB 4m 32s 6/12
2025-09-29 28.4GB 3m 45s 8/12
2025-09-22 31.2GB 4m 12s 6/12
2025-09-15 25.8GB 3m 22s 5/12
Total space freed this month: 118.3GB
Average per cleanup: 29.6GB
📈 Trends
• Xcode DerivedData grows ~2GB/week
• Docker images accumulate ~800MB/week
• node_modules grow ~1.5GB/week across all projects$ cleanmac --dashboard
╔════════════════════════════════════════════════════════════════╗
║ 📊 CleanMac Dashboard ║
╚════════════════════════════════════════════════════════════════╝
🗓️ LAST 30 DAYS
┌────────────────────────────────────────────────────────────────┐
│ Total Freed: 118.3GB | Cleanups: 4 | Avg: 29.6GB/cleanup │
└────────────────────────────────────────────────────────────────┘
📊 SPACE FREED BY CATEGORY
Xcode ████████████████████████ 42.1GB (36%)
node_modules ████████████████ 28.3GB (24%)
Docker ██████████ 18.2GB (15%)
npm cache ███████ 12.4GB (11%)
Homebrew █████ 9.1GB (8%)
Other ████ 8.2GB (6%)
⚡ FASTEST GROWING CATEGORIES
1. Xcode DerivedData 2.1GB/week
2. Docker Images 800MB/week
3. node_modules 1.5GB/week
💡 OPTIMIZATION SUGGESTIONS
• Enable weekly auto-cleanup for Xcode (saves ~8GB/month)
• Switch to pnpm to reduce node_modules size by ~30%
• Enable Docker auto-prune (recovers ~3GB/month)
Commands: [R] Refresh [C] Configure [H] History [Q] Quit- Reports contain all relevant information
- Export to all formats works correctly
- History tracks all cleanups accurately
- Dashboard is interactive and updates in real-time
Priority: MEDIUM
Effort: High
$ cleanmac --schedule
🗓️ Schedule Automatic Cleanup
Frequency: [•] Weekly [ ] Daily [ ] Monthly
Day: [•] Sunday [ ] Monday ... [ ] Saturday
Time: 03:00 AM (system sleep = skip to next wake)
Preset: web-dev (node_modules, npm, yarn, docker)
Options:
[✓] Send notification after cleanup
[✓] Only run if disk usage > 70%
[ ] Auto-update CleanMac before running
[✓] Save detailed reports
This will create a launchd job at:
~/Library/LaunchAgents/com.shadesolutions.cleanmac.plist
Confirm schedule? [Y/n]- Skip if disk usage below threshold
- Skip if on battery and battery < 50%
- Skip if actively building/compiling
- Send desktop notifications with results
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.shadesolutions.cleanmac</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/cleanmac</string>
<string>--preset</string>
<string>web-dev</string>
<string>--yes</string>
</array>
<key>StartCalendarInterval</key>
<dict>
<key>Weekday</key>
<integer>0</integer>
<key>Hour</key>
<integer>3</integer>
<key>Minute</key>
<integer>0</integer>
</dict>
</dict>
</plist>- Scheduled jobs run reliably
- Notifications work correctly
- Smart conditions prevent unwanted cleanups
- Easy to enable/disable scheduled cleanups
Priority: MEDIUM
Effort: Low-Medium
• ~/.pub-cache
• **/build/ (Flutter projects)
• **/android/build/
• **/ios/Pods/• ~/.gradle/caches/
• ~/.android/build-cache/
• ~/Library/Android/sdk/system-images/• ~/Library/Caches/JetBrains/
• ~/Library/Logs/JetBrains/
• ~/.IntelliJIdea*/system/caches/
• ~/.WebStorm*/system/caches/• ~/.gem/
• **/vendor/bundle/
• **/tmp/cache/• ~/.cache/pip/
• **/__pycache__/
• **/.pytest_cache/
• **/.mypy_cache/
• **/venv/
• **/.venv/• ~/.cargo/registry/cache/
• ~/.cargo/git/checkouts/
• **/target/debug/
• **/target/release/• ~/go/pkg/mod/cache/
• ~/.cache/go-build/• ~/Library/Application Support/Postgres/
• /usr/local/var/postgres/pg_log/
• /usr/local/var/mysql/*.log• ~/Library/Safari/LocalStorage/
• ~/Library/Safari/Databases/
• ~/Library/Application Support/Firefox/Profiles/*/cache2/• Rebuild Spotlight index
• Clear DNS cache: dscacheutil -flushcache
• Purge memory: purge
• Clear font cache: atsutil databases -remove- Each category is thoroughly tested
- Categories are opt-in and clearly labeled
- Size calculations are accurate
- No false positives in file detection
Priority: MEDIUM
Effort: Medium
$ cleanmac --parallel --threads 4
🚀 Using parallel deletion (4 threads)
Thread 1: Cleaning ~/Desktop/project-a/node_modules (380MB)
Thread 2: Cleaning ~/Desktop/project-b/node_modules (290MB)
Thread 3: Cleaning ~/Desktop/project-c/node_modules (156MB)
Thread 4: Cleaning Xcode DerivedData (12.1GB)
Progress: ████████████████████ 100%
Time saved: ~2m 15s (vs sequential)# Cache directory sizes to avoid re-scanning
$ cleanmac --use-cache
✅ Using cached size information (scanned 2h ago)
📊 To refresh cache, use --refresh-cache
Cached data:
├─ Last scan: 2025-10-06 12:30:45
├─ Directories scanned: 245
├─ Total size calculated: 45.2GB
└─ Cache expires: 2025-10-06 18:30:45 (6h from scan)$ cleanmac --incremental --target 10GB
🎯 TARGET: Free 10GB of space
Strategy:
1. Start with safest categories
2. Stop when target is reached
3. Save aggressive cleanups for later
Cleaning:
✅ Package manager caches 3.5GB freed (Total: 3.5GB)
✅ Homebrew cache 1.8GB freed (Total: 5.3GB)
✅ Old project folders 4.9GB freed (Total: 10.2GB)
🎉 Target reached! Freed 10.2GB
Stopped early - saved time by skipping 5 categories$ cleanmac --preserve-downloadable=false
⚠️ BANDWIDTH-AWARE MODE
The following items can be re-downloaded:
├─ Homebrew packages (1.8GB)
├─ Docker images (4.2GB)
└─ npm packages (via package.json)
These items cannot be re-downloaded:
├─ Your project source code (protected)
├─ Custom configurations
└─ Local databases
Delete downloadable items? This may require re-downloading.
Current connection: WiFi (Fast)
Estimated re-download time: ~15 minutes
[Y] Yes, delete all [S] Select which ones [N] Skip downloadable$ cleanmac --archive-before-delete
📦 ARCHIVE MODE
Instead of deleting, create compressed archives of:
├─ node_modules directories
├─ Build artifacts
└─ Old project files
Archive location: ~/CleanMac-Archives/
Compression: tar.gz (estimated 70% size reduction)
Example:
~/Desktop/old-project/node_modules (380MB)
→ ~/CleanMac-Archives/old-project-node_modules-2025-10-06.tar.gz (114MB)
This allows recovery if needed.
Archive retention: 30 days (configurable)
Enable archive mode? [Y/n]- Parallel deletion is faster and safe
- Caching reduces scan time significantly
- Incremental cleanup stops at target
- Archive mode creates valid compressed files
- Bandwidth awareness helps with download decisions
# Status Colors
✅ Success: Green (#00FF00)
❌ Error: Red (#FF0000)
⚠️ Warning: Yellow (#FFFF00)
ℹ️ Info: Blue (#0080FF)
💡 Tip: Cyan (#00FFFF)
# Size Colors
< 100MB: White
100MB-1GB: Yellow
> 1GB: Red (attention needed)✅ ❌ ⚠️ ℹ️ 💡 🎯 ⚡ 🚀 📊 📈 📉 🔍 🧹 ✨ 📦 🗑️ 💾 ⏱️ 📁 🔧⠋ Scanning...
⠙ Scanning...
⠹ Scanning...
⠸ Scanning...
⠼ Scanning...
⠴ Scanning...
⠦ Scanning...
⠧ Scanning...
⠇ Scanning...
⠏ Scanning...SPACE Toggle selection
ENTER Confirm / Execute
A Select all
N Deselect all
I Invert selection
D Dry run
S Settings
H / ? Help
Q / ESC Quit
↑ ↓ Navigate menu
TAB Next category
SHIFT+TAB Previous category$ cleanmac --help
Usage: cleanmac [OPTIONS] [COMMAND]
A powerful macOS cleanup utility for developers
OPTIONS:
--all Run all cleanup tasks
--preset <name> Use predefined cleanup preset
--only <cats> Clean only specified categories
--exclude <cats> Exclude specific categories
PATH & FILTER OPTIONS:
--path <path> Scan only specific directory
--paths <p1,p2> Scan multiple directories
--recursive Recursive scan in specified paths
--depth <n> Maximum directory depth (default: 5)
--max-age <days> Only delete files older than N days
--min-size <size> Only delete files/folders larger than size
SAFETY OPTIONS:
--dry-run Preview without deleting
--show-details Show full file list before deletion
--confirm-each Confirm each file/folder individually
--safe Conservative cleanup only
--backup Create restore point before cleanup
--archive Archive files before deletion
AUTOMATION OPTIONS:
--yes Auto-confirm all prompts
--quiet Minimal output
--verbose Detailed logging
--interactive Ask before each category
OUTPUT OPTIONS:
--log <file> Save detailed log to file
--json Output results as JSON
--tree Show tree view of deletions
--summary Show only summary statistics
--report Generate analysis report without deleting
PERFORMANCE OPTIONS:
--parallel Use parallel deletion (faster)
--threads <n> Number of parallel threads (default: 4)
--use-cache Use cached directory sizes
--refresh-cache Refresh cache before cleanup
--incremental Stop when target space is freed
--target <size> Target space to free (with --incremental)
COMMANDS:
init-config Create default config file
configure-paths Interactive path configuration
whitelist <path> Protect path from deletion
schedule Set up automatic cleanup
unschedule Remove scheduled cleanup
history Show cleanup history
dashboard Show analytics dashboard
restore <backup> Restore from backup
manifest <id> View deletion manifest
update Update CleanMac to latest version
PRESETS:
web-dev Node.js, npm, yarn, pnpm
ios-dev Xcode, CocoaPods
android-dev Android SDK, Gradle
docker-dev Docker, Kubernetes
full Everything (safe cleanups only)
EXAMPLES:
# Interactive mode with all features
cleanmac
# Clean everything, no prompts
cleanmac --all --yes
# Preview web-dev cleanup
cleanmac --preset web-dev --dry-run
# Clean specific directory with age filter
cleanmac --path ~/Desktop --only node_modules --max-age 30
# Clean with detailed preview and confirmation
cleanmac --show-details --confirm-each
# Generate report without deleting
cleanmac --report --log analysis.md
# Parallel cleanup with target
cleanmac --parallel --incremental --target 10GB
# Archive before deletion
cleanmac --archive --only node_modules --path ~/Desktop
For more info: https://github.com/shade-solutions/cleanmac
Documentation: https://github.com/shade-solutions/cleanmac/wiki- Screen reader compatible output
- High contrast mode support
- No color mode for accessibility
- Keyboard-only navigation
- Clear focus indicators
cleanmac/
├── cleanmac.sh # Main entry point
├── lib/
│ ├── core.sh # Core functions
│ ├── ui.sh # UI components
│ ├── cleaner.sh # Cleanup logic
│ ├── config.sh # Config management
│ ├── analyzer.sh # Smart recommendations
│ ├── reporter.sh # Report generation
│ └── scheduler.sh # Automation
├── config/
│ ├── default.yml # Default config
│ └── presets/ # Preset definitions
├── tests/
│ ├── unit/
│ └── integration/
└── docs/
├── README.md
├── PRD.md
├── CONTRIBUTING.md
└── API.md
Required:
- Bash 4.0+ (macOS ships with 3.2, but 4.0 available via Homebrew)
- Standard UNIX utilities (find, du, rm, etc.)
Optional:
- jq (for JSON parsing)
- yq (for YAML parsing)
- terminal-notifier (for desktop notifications)
- Initial scan: < 30 seconds for typical dev machine
- Cleanup execution: < 5 minutes for full cleanup
- Memory usage: < 50MB
- CPU usage: < 20% during cleanup
- macOS 10.15 (Catalina) and newer
- Intel and Apple Silicon (M1/M2/M3)
- Terminal.app, iTerm2, Alacritty, Warp
# Unit tests
tests/unit/test_config.sh
tests/unit/test_cleaner.sh
tests/unit/test_ui.sh
# Integration tests
tests/integration/test_dry_run.sh
tests/integration/test_backup_restore.sh
tests/integration/test_scheduled_cleanup.sh
# Run all tests
./run_tests.sh
# Test coverage report
./coverage.shGoal: Build robust foundation with enhanced safety features
- Refactor code into modular structure (lib/ directory)
- Add comprehensive error handling
- Implement path-specific scanning with depth limits
- Add age-based and size-based filtering
- Implement dry-run mode with accurate previews
- Create deletion manifest logging
- Add basic color scheme and UI improvements
- Create test framework
- Write initial unit tests for core functions
Deliverable: v1.5 - Safe, modular, tested foundation
Goal: Give users full visibility and control
- Implement interactive file selection interface
- Add tree view visualization
- Create pre-deletion preview system
- Build selective deletion with checkboxes
- Add whitelist/protection features
- Implement "protect recent files" logic
- Add detailed confirmation dialogs
- Real-time progress indicators with file counts
Deliverable: v1.7 - Transparent, user-controlled cleanup
Goal: Enable full automation and customization
- Implement all CLI flags (--path, --max-age, --min-size, etc.)
- Create YAML config file support
- Implement presets (web-dev, ios-dev, etc.)
- Add custom rules engine
- Add --log and --json output
- Implement --report mode (analysis without deletion)
- Create config validation system
- Documentation for automation use cases
Deliverable: v1.8 - Automation-ready
Goal: Add intelligence and proactive recommendations
- Build recommendation engine
- Implement usage tracking and history
- Add project detection logic (Next.js, React, etc.)
- Create stale vs. active project detection
- Implement smart scheduling logic
- Add risk level calculation
- Build trend analysis
- Add backup/restore functionality
Deliverable: v2.0-beta - Intelligent cleanup
Goal: Make cleanup faster and more efficient
- Implement parallel deletion with threading
- Add directory size caching
- Create incremental cleanup with targets
- Implement archive-before-delete mode
- Add bandwidth-aware cleanup
- Optimize file scanning algorithms
- Performance benchmarking
- Memory usage optimization
Deliverable: v2.0-rc - Performance optimized
Goal: Professional-grade tool ready for release
- Enhanced interactive UI with all features
- Dashboard implementation
- Report generation (all formats: TXT, MD, JSON, HTML, CSV)
- Desktop notifications integration
- Additional cleanup categories (Flutter, Android, etc.)
- Comprehensive documentation
- Video tutorials and demos
- Final testing and bug fixes
- Security audit
Deliverable: v2.0 - Production release
Goal: Build sustainable ecosystem
- Homebrew formula for easy installation
- Plugin system for custom cleaners
- Community preset repository
- Integration with popular dev tools
- VSCode extension (optional)
- Web-based configuration tool
- macOS app wrapper (optional)
- Community management and support
Deliverable: v2.x - Thriving ecosystem
| Risk | Probability | Impact | Mitigation |
|---|---|---|---|
| Data loss from bugs | Medium | Critical | Extensive testing, dry-run default, backups |
| Performance issues on large projects | Medium | Medium | Optimize file scanning, add --quick mode |
| Compatibility with future macOS | Low | Medium | Follow Apple guidelines, test on betas |
| Bash version fragmentation | High | Low | Detect version, graceful degradation |
| Risk | Probability | Impact | Mitigation |
|---|---|---|---|
| Low adoption | Medium | High | Marketing, developer outreach, docs |
| User confusion with features | Medium | Medium | Excellent UX, clear help, tutorials |
| Competition from similar tools | Low | Medium | Unique features, better UX |
| Maintenance burden | High | Medium | Modular code, good docs, community |
-
Comprehensive Testing
- Unit tests for all functions
- Integration tests for workflows
- Beta testing with real users
-
Fail-Safe Defaults
- Dry-run mode easily accessible
- Confirmation for destructive actions
- Backups encouraged
-
Clear Documentation
- Extensive README
- Video tutorials
- FAQ section
- Troubleshooting guide
-
Community Building
- Discord/Slack community
- Regular updates
- Responsive to issues
- Welcome contributions
-
GUI Application
- Native macOS app with SwiftUI
- Visual file browser
- One-click cleanup
-
Cloud Integration
- Sync config across machines
- Cloud backup of critical data
- Team presets
-
AI-Powered Recommendations
- Machine learning for pattern detection
- Personalized cleanup schedules
- Anomaly detection
-
Cross-Platform Support
- Linux version
- Windows (WSL) support
- Docker container
-
IDE Integration
- VSCode extension
- JetBrains plugin
- Xcode integration
-
Advanced Features
- Duplicate file finder
- Large file analyzer with visualization
- Dependency graph visualization
- Broken symlink detection
- All Phase 1-4 features implemented
- Test coverage > 80%
- Zero critical bugs
- Documentation complete
- 10+ beta testers approve
- Performance benchmarks met
- Security audit passed
- 1,000+ GitHub stars
- 10,000+ weekly active users
- NPS score > 70
- < 5% bug report rate
- Featured in 3+ tech publications
- 20+ community contributions
Similar Tools:
- DaisyDisk (GUI, paid)
- OmniDiskSweeper (GUI, free)
- ncdu (Terminal, basic)
- Grand Perspective (GUI, free)
CleanMac Advantages:
- Free and open source
- Developer-focused categories
- Smart recommendations
- Automation-friendly
- Active development
Survey Results (50 developers):
- 82% run out of disk space monthly
- 64% afraid of deleting wrong files
- 78% want automated cleanup
- 91% prefer CLI over GUI for dev tools
- 56% would pay for premium features
See /designs folder for:
- Terminal UI mockups
- Color scheme samples
- Flow diagrams
- Architecture diagrams
Author: Shaswat Raj
GitHub: https://github.com/shade-solutions
Email: [Your email]
Discord: [Community link]
Feedback Channels:
- GitHub Issues
- GitHub Discussions
- Discord community
Document Status: Draft
Next Review: Week of Oct 13, 2025
Approval Required: Product Owner, Lead Developer
This PRD is a living document and will be updated as features are developed and user feedback is gathered.