🍎 macOS Cleaner

A beautiful and powerful console application for cleaning and optimizing macOS systems

Features • Installation • Usage • Documentation • Contributing

</div>

✨ Features

🔍 Smart Scanning

Multi-threaded intelligent file scanning across 19+ categories
Real-time progress tracking with detailed statistics
NEW: Preview detailed file list before cleaning with pagination
Pattern-based file identification with safety checks
Configurable minimum file size filters

🧹 Safe Cleaning

Priority-based cleaning (HIGH, MEDIUM, LOW, OPTIONAL)
Built-in protection for system-critical files
Optional backup system with configurable retention
NEW: Show exactly what will be deleted with file paths and sizes
Batch operations with parallel processing
Dry-run mode for safe preview

⚡ System Optimization

Memory purging for performance boost
DNS cache flushing for network optimization
Startup items management (LaunchAgents/Daemons/LoginItems)
Spotlight index rebuilding
Disk verification utilities

🎨 Beautiful UI

Rich console interface with colors and animations
Interactive menu system with keyboard shortcuts
Real-time progress bars and status updates
Comprehensive scan results visualization
User-friendly file detail preview with pagination

🛡️ Safety First

Protected system paths and directories
Confirmation prompts for destructive operations
Automatic backup before deletion (configurable)
Post-cleaning verification
Comprehensive error handling and logging

📋 Supported Cleaning Categories

System Categories

🗄️ System Cache - System-level cache files (HIGH priority)
👤 User Cache - User application cache files (HIGH priority)
📁 Temporary Files - System temporary files (HIGH priority)
📝 Log Files - System and application logs (MEDIUM priority)
🗑️ Trash - Empty system trash bin (MEDIUM priority)

Browser Data

🌐 Browser Cache - Safari, Chrome, Firefox, Brave, Edge, Opera, Vivaldi (MEDIUM priority)

Developer Tools ⚡ NEW

🔨 Xcode Derived Data - Build artifacts and indexes (HIGH priority)
🏗️ Xcode Archives - Old app archives (MEDIUM priority)
🐳 Docker Data - Containers, images, volumes (MEDIUM priority)
🍺 Homebrew Cache - Package manager cache (MEDIUM priority)
🟢 Node.js Modules - node_modules directories (LOW priority)
🐍 Python Cache - pycache and .pyc files (LOW priority)

File Management

📥 Downloads - Old downloads folder files (OPTIONAL)
📋 Duplicate Files - Identical files detection (OPTIONAL)
📊 Large Files - Files over 100MB (OPTIONAL)
🕰️ Old Files - Files not accessed in 6+ months (OPTIONAL)
📦 App Leftovers - Files from uninstalled apps (MEDIUM priority)

🚀 Installation

Prerequisites

macOS 10.15 (Catalina) or later
Python 3.10 or higher
pip package manager

Quick Install

# Clone the repository
git clone https://github.com/QDenka/MacCleanCLI.git
cd MacCleanCLI

# Install with pip (development mode)
pip install -e .

Verify Installation

# Check if commands are available
macos-cleaner --help
mclean --help

System Permissions

For full functionality, grant Terminal Full Disk Access:

Open System Settings → Privacy & Security → Full Disk Access
Click the + button and add your Terminal app
Restart Terminal and rerun the application

📖 Usage

Interactive Mode (Recommended)

# Run with full interface
macos-cleaner

# Or use the short alias
mclean

Interactive Workflow:

Scan System - Choose categories to scan
Review Results - See detailed file list with sizes
Clean Files - Select items to delete
Optimize System - Run system optimizations

Command Line Options

# Scan only (no cleaning)
macos-cleaner --scan-only

# Automatic mode (clean recommended items)
macos-cleaner --auto

# Use custom config file
macos-cleaner --config ~/custom-config.json

# Enable verbose output
macos-cleaner --verbose

# Dry run mode (preview only)
macos-cleaner --dry-run

# Combine options
macos-cleaner --scan-only --verbose

Python Direct Execution

# Run directly with Python
python main.py

# With options
python main.py --scan-only
python main.py --auto --verbose

🎮 Interactive Menu Guide

Main Menu

[1] 🔍 Scan System      - Scan for cleanable files
[2] 🧹 Clean Files      - Remove scanned files
[3] ⚡ Optimize System  - System optimization tasks
[4] ⚙️  Settings        - Configure application
[q] 🚪 Quit            - Exit application

Scan Menu

[a] All Categories     - Scan everything
[1-9] Specific Category - Select individual category
[q] Back              - Return to main menu

New Feature: File Detail Preview ✨

When cleaning, you can now preview exactly what will be deleted:

Show detailed file list before cleaning? [Y/n]: y

📁 System Cache Files
┌─────────────────────────────────────────────────────────┐
│ Path: ~/Library/Caches/com.apple.Safari/Cache.db       │
│ Size: 45.2 MB                                          │
│ Safe: ✅ Yes                                            │
├─────────────────────────────────────────────────────────┤
│ ... (showing 1-20 of 156 files)                        │
└─────────────────────────────────────────────────────────┘

Continue to next page? [Y/n]:

⚙️ Configuration

Config File Location

~/.MacCleanCLI/config.json

Default Configuration

{
  "dry_run": false,
  "enable_backup": true,
  "verify_cleaning": true,
  "remove_empty_dirs": true,
  "max_workers": 4,
  "backup_retention_days": 7,
  "min_file_size_mb": 0.001,
  "scan_hidden_files": false,
  "protected_extensions": [".dmg", ".pkg", ".app"],
  "protected_directories": [
    "/System",
    "/Library/System",
    "/private/var/db"
  ]
}

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | dry_run | bool | false | Preview mode without deletion | | enable_backup | bool | true | Backup files before cleaning | | verify_cleaning | bool | true | Verify files are deleted | | remove_empty_dirs | bool | true | Remove empty directories | | max_workers | int | 4 | Parallel processing threads | | backup_retention_days | int | 7 | Days to keep backups | | min_file_size_mb | float | 0.001 | Minimum file size (1KB) | | scan_hidden_files | bool | false | Include hidden files |

🛡️ Safety Features

Protected Paths

The following paths are never touched:

/System/* - System files
/Library/System/* - System libraries
/private/var/db/* - System databases
/usr/bin/*, /usr/sbin/* - System binaries
User home directory root files

Safety Mechanisms

✅ Pre-flight safety checks
✅ User confirmation for all destructive operations
✅ Optional automatic backup system
✅ Post-cleaning verification
✅ Dry-run mode for risk-free preview
✅ Comprehensive error handling and logging

Backup System

# Backups stored in
~/.macos-cleaner/backups/

# Structure
backups/
├── 2024-10-06_170000/    # Timestamp-based folders
│   ├── Caches/
│   └── manifest.json      # Backup metadata
└── 2024-10-05_120000/

🏗️ Project Architecture

Directory Structure

MacCleanCLI/
├── main.py                 # Application entry point
├── core/                   # Core business logic
│   ├── scanner.py          # Multi-threaded file scanning
│   ├── cleaner.py          # Safe file deletion engine
│   └── optimizer.py        # System optimization utilities
├── models/                 # Data models and types
│   └── scan_result.py      # Result structures and enums
├── ui/                     # User interface layer
│   ├── interface.py        # Interactive menu system
│   └── components.py       # Reusable UI components
├── utils/                  # Utility modules
│   ├── config.py           # Configuration management
│   ├── logger.py           # Logging system
│   ├── backup.py           # Backup management
│   └── exceptions.py       # Custom exceptions
└── tests/                  # Test suite (87 tests)
    ├── test_scanner.py
    ├── test_cleaner.py
    ├── test_integration.py
    ├── test_optimizer.py
    └── test_new_categories.py

Design Principles

SOLID Principles - Clean, maintainable code architecture
Type Safety - Full type hints with dataclasses
Error Handling - Comprehensive exception handling
Testing - 87 tests with 41% coverage
Performance - Multi-threaded parallel processing
Safety - Multiple layers of protection

🔧 Development

Setup Development Environment

# Clone and navigate
git clone https://github.com/QDenka/MacCleanCLI.git
cd MacCleanCLI

# Create virtual environment (recommended

MacCleanCLI

Install / Use

README