{"id":28794185,"url":"https://github.com/qdenka/maccleancli","last_synced_at":"2026-04-16T03:33:17.393Z","repository":{"id":298443474,"uuid":"999966125","full_name":"QDenka/MacCleanCLI","owner":"QDenka","description":"🚀 MacCleanCLI is a sleek, powerful, and interactive command-line application designed specifically for macOS, providing efficient disk cleanup, system optimization, and an outstanding user experience directly from your terminal.","archived":false,"fork":false,"pushed_at":"2025-06-11T06:42:45.000Z","size":59,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-19T03:03:52.440Z","etag":null,"topics":["cache-cleaner","cleaner","cleanup","cli","command-line","console-application","disk-cleaner","disk-space","macos","optimization","performance","productivity","python","storage","system-cleaner","system-utility","terminal"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/QDenka.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-11T04:24:46.000Z","updated_at":"2025-06-11T09:38:25.000Z","dependencies_parsed_at":"2025-06-11T06:24:48.167Z","dependency_job_id":"2c7f583a-90e1-4efe-a538-e2fa089d1296","html_url":"https://github.com/QDenka/MacCleanCLI","commit_stats":null,"previous_names":["qdenka/maccleancli"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/QDenka/MacCleanCLI","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QDenka%2FMacCleanCLI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QDenka%2FMacCleanCLI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QDenka%2FMacCleanCLI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QDenka%2FMacCleanCLI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/QDenka","download_url":"https://codeload.github.com/QDenka/MacCleanCLI/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QDenka%2FMacCleanCLI/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262637630,"owners_count":23341164,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache-cleaner","cleaner","cleanup","cli","command-line","console-application","disk-cleaner","disk-space","macos","optimization","performance","productivity","python","storage","system-cleaner","system-utility","terminal"],"created_at":"2025-06-18T02:05:01.850Z","updated_at":"2026-04-16T03:33:17.358Z","avatar_url":"https://github.com/QDenka.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🍎 macOS Cleaner\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg width=\"1737\" alt=\"macOS Cleaner Interface\" src=\"https://github.com/user-attachments/assets/fdeb8a4e-3d95-4408-9e4b-484ee47000a7\" /\u003e\n\n**A beautiful and powerful console application for cleaning and optimizing macOS systems**\n\n[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square)](https://www.python.org/downloads/)\n[![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)\n[![Platform](https://img.shields.io/badge/platform-macOS-lightgrey?style=flat-square)](https://www.apple.com/macos/)\n[![GitHub Stars](https://img.shields.io/github/stars/QDenka/MacCleanCLI?style=flat-square)](https://github.com/QDenka/MacCleanCLI/stargazers)\n[![GitHub Issues](https://img.shields.io/github/issues/QDenka/MacCleanCLI?style=flat-square)](https://github.com/QDenka/MacCleanCLI/issues)\n[![GitHub Forks](https://img.shields.io/github/forks/QDenka/MacCleanCLI?style=flat-square)](https://github.com/QDenka/MacCleanCLI/network/members)\n\n[Features](#-features) • [Installation](#-installation) • [Usage](#-usage) • [Documentation](#-documentation) • [Contributing](#-contributing)\n\n\u003c/div\u003e\n\n---\n\n## ✨ Features\n\n### 🔍 **Smart Scanning**\n- Multi-threaded intelligent file scanning across 19+ categories\n- Real-time progress tracking with detailed statistics\n- **NEW:** Preview detailed file list before cleaning with pagination\n- Pattern-based file identification with safety checks\n- Configurable minimum file size filters\n\n### 🧹 **Safe Cleaning**\n- Priority-based cleaning (HIGH, MEDIUM, LOW, OPTIONAL)\n- Built-in protection for system-critical files\n- Optional backup system with configurable retention\n- **NEW:** Show exactly what will be deleted with file paths and sizes\n- Batch operations with parallel processing\n- Dry-run mode for safe preview\n\n### ⚡ **System Optimization**\n- Memory purging for performance boost\n- DNS cache flushing for network optimization\n- Startup items management (LaunchAgents/Daemons/LoginItems)\n- Spotlight index rebuilding\n- Disk verification utilities\n\n### 🎨 **Beautiful UI**\n- Rich console interface with colors and animations\n- Interactive menu system with keyboard shortcuts\n- Real-time progress bars and status updates\n- Comprehensive scan results visualization\n- User-friendly file detail preview with pagination\n\n### 🛡️ **Safety First**\n- Protected system paths and directories\n- Confirmation prompts for destructive operations\n- Automatic backup before deletion (configurable)\n- Post-cleaning verification\n- Comprehensive error handling and logging\n\n---\n\n## 📋 Supported Cleaning Categories\n\n### System Categories\n- 🗄️ **System Cache** - System-level cache files (HIGH priority)\n- 👤 **User Cache** - User application cache files (HIGH priority)\n- 📁 **Temporary Files** - System temporary files (HIGH priority)\n- 📝 **Log Files** - System and application logs (MEDIUM priority)\n- 🗑️ **Trash** - Empty system trash bin (MEDIUM priority)\n\n### Browser Data\n- 🌐 **Browser Cache** - Safari, Chrome, Firefox, Brave, Edge, Opera, Vivaldi (MEDIUM priority)\n\n### Developer Tools ⚡ NEW\n- 🔨 **Xcode Derived Data** - Build artifacts and indexes (HIGH priority)\n- 🏗️ **Xcode Archives** - Old app archives (MEDIUM priority)\n- 🐳 **Docker Data** - Containers, images, volumes (MEDIUM priority)\n- 🍺 **Homebrew Cache** - Package manager cache (MEDIUM priority)\n- 🟢 **Node.js Modules** - node_modules directories (LOW priority)\n- 🐍 **Python Cache** - __pycache__ and .pyc files (LOW priority)\n\n### File Management\n- 📥 **Downloads** - Old downloads folder files (OPTIONAL)\n- 📋 **Duplicate Files** - Identical files detection (OPTIONAL)\n- 📊 **Large Files** - Files over 100MB (OPTIONAL)\n- 🕰️ **Old Files** - Files not accessed in 6+ months (OPTIONAL)\n- 📦 **App Leftovers** - Files from uninstalled apps (MEDIUM priority)\n\n---\n\n## 🚀 Installation\n\n### Prerequisites\n- macOS 10.15 (Catalina) or later\n- Python 3.10 or higher\n- pip package manager\n\n### Quick Install\n\n```bash\n# Clone the repository\ngit clone https://github.com/QDenka/MacCleanCLI.git\ncd MacCleanCLI\n\n# Install with pip (development mode)\npip install -e .\n```\n\n### Verify Installation\n\n```bash\n# Check if commands are available\nmacos-cleaner --help\nmclean --help\n```\n\n### System Permissions\n\nFor full functionality, grant Terminal **Full Disk Access**:\n\n1. Open **System Settings** → **Privacy \u0026 Security** → **Full Disk Access**\n2. Click the **+** button and add your Terminal app\n3. Restart Terminal and rerun the application\n\n---\n\n## 📖 Usage\n\n### Interactive Mode (Recommended)\n\n```bash\n# Run with full interface\nmacos-cleaner\n\n# Or use the short alias\nmclean\n```\n\n**Interactive Workflow:**\n1. **Scan System** - Choose categories to scan\n2. **Review Results** - See detailed file list with sizes\n3. **Clean Files** - Select items to delete\n4. **Optimize System** - Run system optimizations\n\n### Command Line Options\n\n```bash\n# Scan only (no cleaning)\nmacos-cleaner --scan-only\n\n# Automatic mode (clean recommended items)\nmacos-cleaner --auto\n\n# Use custom config file\nmacos-cleaner --config ~/custom-config.json\n\n# Enable verbose output\nmacos-cleaner --verbose\n\n# Dry run mode (preview only)\nmacos-cleaner --dry-run\n\n# Combine options\nmacos-cleaner --scan-only --verbose\n```\n\n### Python Direct Execution\n\n```bash\n# Run directly with Python\npython main.py\n\n# With options\npython main.py --scan-only\npython main.py --auto --verbose\n```\n\n---\n\n## 🎮 Interactive Menu Guide\n\n### Main Menu\n```\n[1] 🔍 Scan System      - Scan for cleanable files\n[2] 🧹 Clean Files      - Remove scanned files\n[3] ⚡ Optimize System  - System optimization tasks\n[4] ⚙️  Settings        - Configure application\n[q] 🚪 Quit            - Exit application\n```\n\n### Scan Menu\n```\n[a] All Categories     - Scan everything\n[1-9] Specific Category - Select individual category\n[q] Back              - Return to main menu\n```\n\n### New Feature: File Detail Preview ✨\n\nWhen cleaning, you can now preview exactly what will be deleted:\n\n```\nShow detailed file list before cleaning? [Y/n]: y\n\n📁 System Cache Files\n┌─────────────────────────────────────────────────────────┐\n│ Path: ~/Library/Caches/com.apple.Safari/Cache.db       │\n│ Size: 45.2 MB                                          │\n│ Safe: ✅ Yes                                            │\n├─────────────────────────────────────────────────────────┤\n│ ... (showing 1-20 of 156 files)                        │\n└─────────────────────────────────────────────────────────┘\n\nContinue to next page? [Y/n]:\n```\n\n---\n\n## ⚙️ Configuration\n\n### Config File Location\n`~/.MacCleanCLI/config.json`\n\n### Default Configuration\n\n```json\n{\n  \"dry_run\": false,\n  \"enable_backup\": true,\n  \"verify_cleaning\": true,\n  \"remove_empty_dirs\": true,\n  \"max_workers\": 4,\n  \"backup_retention_days\": 7,\n  \"min_file_size_mb\": 0.001,\n  \"scan_hidden_files\": false,\n  \"protected_extensions\": [\".dmg\", \".pkg\", \".app\"],\n  \"protected_directories\": [\n    \"/System\",\n    \"/Library/System\",\n    \"/private/var/db\"\n  ]\n}\n```\n\n### Configuration Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `dry_run` | bool | `false` | Preview mode without deletion |\n| `enable_backup` | bool | `true` | Backup files before cleaning |\n| `verify_cleaning` | bool | `true` | Verify files are deleted |\n| `remove_empty_dirs` | bool | `true` | Remove empty directories |\n| `max_workers` | int | `4` | Parallel processing threads |\n| `backup_retention_days` | int | `7` | Days to keep backups |\n| `min_file_size_mb` | float | `0.001` | Minimum file size (1KB) |\n| `scan_hidden_files` | bool | `false` | Include hidden files |\n\n---\n\n## 🛡️ Safety Features\n\n### Protected Paths\nThe following paths are **never** touched:\n- `/System/*` - System files\n- `/Library/System/*` - System libraries\n- `/private/var/db/*` - System databases\n- `/usr/bin/*`, `/usr/sbin/*` - System binaries\n- User home directory root files\n\n### Safety Mechanisms\n- ✅ Pre-flight safety checks\n- ✅ User confirmation for all destructive operations\n- ✅ Optional automatic backup system\n- ✅ Post-cleaning verification\n- ✅ Dry-run mode for risk-free preview\n- ✅ Comprehensive error handling and logging\n\n### Backup System\n```bash\n# Backups stored in\n~/.macos-cleaner/backups/\n\n# Structure\nbackups/\n├── 2024-10-06_170000/    # Timestamp-based folders\n│   ├── Caches/\n│   └── manifest.json      # Backup metadata\n└── 2024-10-05_120000/\n```\n\n---\n\n## 🏗️ Project Architecture\n\n### Directory Structure\n```\nMacCleanCLI/\n├── main.py                 # Application entry point\n├── core/                   # Core business logic\n│   ├── scanner.py          # Multi-threaded file scanning\n│   ├── cleaner.py          # Safe file deletion engine\n│   └── optimizer.py        # System optimization utilities\n├── models/                 # Data models and types\n│   └── scan_result.py      # Result structures and enums\n├── ui/                     # User interface layer\n│   ├── interface.py        # Interactive menu system\n│   └── components.py       # Reusable UI components\n├── utils/                  # Utility modules\n│   ├── config.py           # Configuration management\n│   ├── logger.py           # Logging system\n│   ├── backup.py           # Backup management\n│   └── exceptions.py       # Custom exceptions\n└── tests/                  # Test suite (87 tests)\n    ├── test_scanner.py\n    ├── test_cleaner.py\n    ├── test_integration.py\n    ├── test_optimizer.py\n    └── test_new_categories.py\n```\n\n### Design Principles\n- **SOLID Principles** - Clean, maintainable code architecture\n- **Type Safety** - Full type hints with dataclasses\n- **Error Handling** - Comprehensive exception handling\n- **Testing** - 87 tests with 41% coverage\n- **Performance** - Multi-threaded parallel processing\n- **Safety** - Multiple layers of protection\n\n---\n\n## 🔧 Development\n\n### Setup Development Environment\n\n```bash\n# Clone and navigate\ngit clone https://github.com/QDenka/MacCleanCLI.git\ncd MacCleanCLI\n\n# Create virtual environment (recommended)\npython -m venv venv\nsource venv/bin/activate\n\n# Install in development mode\npip install -e .\n\n# Install development dependencies\npip install pytest pytest-cov black flake8 mypy\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage report\npytest --cov=. --cov-report=html\n\n# Run specific test file\npytest tests/test_scanner.py\n\n# Run specific test\npytest tests/test_scanner.py::TestSystemScanner::test_scan_user_cache\n\n# Generate coverage report\npytest --cov=. --cov-report=term-missing\n```\n\n**Current Test Stats:**\n- ✅ 87 tests passing\n- 📊 41% overall coverage\n- 🎯 Core modules: 52-87% coverage\n\n### Code Quality\n\n```bash\n# Format code with Black\nblack . --line-length 100\n\n# Check linting with flake8\nflake8 . --max-line-length=100\n\n# Type checking with mypy\nmypy . --ignore-missing-imports\n\n# Run all quality checks\nmake lint\n```\n\n### Project Commands\n\n```bash\n# Available make commands\nmake install        # Install package\nmake install-dev    # Install with dev dependencies\nmake test          # Run tests\nmake coverage      # Generate coverage report\nmake lint          # Run all linters\nmake clean         # Clean build artifacts\n```\n\n---\n\n## 📊 Performance\n\n### Optimization Strategies\n- **Multi-threading** - Parallel file scanning using ThreadPoolExecutor\n- **Batch Operations** - Group operations by directory for efficiency\n- **Memory Efficiency** - Stream large files instead of loading into RAM\n- **Smart Caching** - Cache file metadata to avoid redundant I/O\n- **Progress Tracking** - Real-time updates without blocking operations\n\n### Benchmarks (Typical macOS System)\n- **Scan Speed**: ~500-1000 files/second\n- **Memory Usage**: 50-100 MB during scan\n- **Clean Speed**: ~200-400 files/second\n- **Thread Count**: Configurable (default: 4 workers)\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n### Contribution Process\n\n1. **Fork the Repository**\n   ```bash\n   # Click \"Fork\" on GitHub\n   git clone https://github.com/YOUR_USERNAME/MacCleanCLI.git\n   ```\n\n2. **Create Feature Branch**\n   ```bash\n   git checkout -b feature/amazing-feature\n   ```\n\n3. **Make Changes**\n   - Write clean, documented code\n   - Follow existing code style\n   - Add tests for new features\n   - Update documentation\n\n4. **Run Tests**\n   ```bash\n   pytest\n   black . --check\n   flake8 .\n   ```\n\n5. **Commit Changes**\n   ```bash\n   git add .\n   git commit -m \"Add amazing feature\"\n   ```\n\n6. **Push and Create PR**\n   ```bash\n   git push origin feature/amazing-feature\n   # Open Pull Request on GitHub\n   ```\n\n### Contribution Guidelines\n\n- ✅ Follow PEP 8 style guide\n- ✅ Write meaningful commit messages\n- ✅ Add tests for new features\n- ✅ Update documentation\n- ✅ Keep PRs focused and atomic\n- ✅ Respond to review feedback\n\n### Areas for Contribution\n\n- 🐛 Bug fixes and error handling\n- ✨ New cleaning categories\n- 🎨 UI improvements\n- 📝 Documentation enhancements\n- 🧪 Test coverage expansion\n- ⚡ Performance optimizations\n- 🌍 Localization/translations\n\n---\n\n## 📄 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n**TL;DR**: You can freely use, modify, and distribute this software with attribution.\n\n---\n\n## 🙏 Acknowledgments\n\n### Built With\n- **[Rich](https://github.com/Textualize/rich)** - Beautiful terminal formatting and UI components\n- **[psutil](https://github.com/giampaolo/psutil)** - Cross-platform system and process utilities\n- **[pytest](https://github.com/pytest-dev/pytest)** - Testing framework\n\n### Inspiration\n- macOS maintenance utilities\n- CleanMyMac concepts\n- Unix philosophy of doing one thing well\n\n### Special Thanks\n- All contributors and issue reporters\n- The Python and open-source community\n- macOS power users providing feedback\n\n---\n\n## 📞 Support \u0026 Community\n\n### Get Help\n- 📖 **Documentation**: [QUICKSTART.md](QUICKSTART.md) • [TROUBLESHOOTING.md](TROUBLESHOOTING.md)\n- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/QDenka/MacCleanCLI/issues)\n- 💬 **Discussions**: [GitHub Discussions](https://github.com/QDenka/MacCleanCLI/discussions)\n- 📧 **Contact**: denis@kaban.dev\n\n### Stay Updated\n- ⭐ Star this repo to show support\n- 👁️ Watch for updates and releases\n- 🔔 Enable notifications for new versions\n\n---\n\n## ⚠️ Disclaimer\n\n**Use at Your Own Risk**\n\nThis software is provided \"as-is\" without warranty of any kind. While extensive safety measures are in place, always:\n\n1. ✅ **Backup Important Data** - Use Time Machine or other backup solutions\n2. ✅ **Review Before Cleaning** - Check what will be deleted\n3. ✅ **Start with Scan Only** - Test before actual cleaning\n4. ✅ **Enable Backup Mode** - Use the built-in backup feature\n\nThe authors are not responsible for data loss or system issues. Always maintain regular backups of your system.\n\n---\n\n## 📈 Project Stats\n\n![GitHub last commit](https://img.shields.io/github/last-commit/QDenka/MacCleanCLI?style=flat-square)\n![GitHub commit activity](https://img.shields.io/github/commit-activity/m/QDenka/MacCleanCLI?style=flat-square)\n![GitHub code size](https://img.shields.io/github/languages/code-size/QDenka/MacCleanCLI?style=flat-square)\n\n**Made with ❤️ for macOS users**\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**If this project helped you, consider giving it a ⭐!**\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqdenka%2Fmaccleancli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqdenka%2Fmaccleancli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqdenka%2Fmaccleancli/lists"}