Disk Cleaner Skill v2.0

High-performance cross-platform disk management toolkit with advanced optimization features for monitoring, analyzing, and cleaning disk space safely.

🚀 What’s New in v2.0

Performance Enhancements

• 3-5x faster scanning with os.scandir() optimization
• Concurrent multi-threaded scanning for I/O-bound operations
• Intelligent sampling with QuickProfiler (estimates in 0.5-1s instead of full scan)
• Memory-adaptive processing with automatic memory monitoring
• Optimized duplicate detection with parallel hashing and caching

Reliability Improvements

• 244 comprehensive tests across all platforms
• Cross-platform compatibility verified on Windows, macOS, Linux
• Python 3.8-3.12 support with full test coverage
• Robust error handling for permission issues and edge cases
• Graceful degradation when scanning protected directories

Quick Start

Analyze Disk Space

# Analyze current drive (C:\ on Windows, / on Unix)
python skills/disk-cleaner/scripts/analyze_disk.py

# Analyze specific path
python skills/disk-cleaner/scripts/analyze_disk.py --path "D:\Projects"

# Get top 50 largest items
python skills/disk-cleaner/scripts/analyze_disk.py --top 50

# Output as JSON
python skills/disk-cleaner/scripts/analyze_disk.py --json

# Save report
python skills/disk-cleaner/scripts/analyze_disk.py --output disk_report.json

Clean Junk Files

# Dry run (default - safe simulation)
python skills/disk-cleaner/scripts/clean_disk.py --dry-run

# Actually clean files (use --force)
python skills/disk-cleaner/scripts/clean_disk.py --force

# Clean specific category
python skills/disk-cleaner/scripts/clean_disk.py --temp       # Clean temp files only
python skills/disk-cleaner/scripts/clean_disk.py --cache      # Clean cache only
python skills/disk-cleaner/scripts/clean_disk.py --logs       # Clean logs only
python skills/disk-cleaner/scripts/clean_disk.py --recycle    # Clean recycle bin only
python skills/disk-cleaner/scripts/clean_disk.py --downloads 90  # Clean downloads older than 90 days

Monitor Disk Usage

# Check current status
python skills/disk-cleaner/scripts/monitor_disk.py

# Continuous monitoring (every 60 seconds)
python skills/disk-cleaner/scripts/monitor_disk.py --watch

# Custom thresholds
python skills/disk-cleaner/scripts/monitor_disk.py --warning 70 --critical 85

# Alert mode (CI/CD friendly)
python skills/disk-cleaner/scripts/monitor_disk.py --alerts-only

# Custom monitoring interval
python skills/disk-cleaner/scripts/monitor_disk.py --watch --interval 300

Performance Features

High-Speed Scanning

The scanner uses advanced optimizations for rapid directory traversal:

• os.scandir() optimization: 3-5x faster than Path.glob/iterdir()
• Bounded queue processing: Efficient concurrent scanning
• Adaptive worker threads: CPU count × 4 for I/O-bound operations
• Smart path exclusion: Skip system directories automatically

Intelligent Sampling (QuickProfiler)

For large directories, use sampling to get instant estimates:

from diskcleaner.optimization.scan import QuickProfiler

profiler = QuickProfiler(sample_time=1.0)  # 1 second sampling
profile = profiler.profile(path)  # Returns: estimated file count, size, depth, time

# Example output for 442K files:
# - Estimated: 450,000 files (within 2%)
# - Estimated scan time: 14 seconds
# - Actual scan time: 14 seconds

Memory Management

Automatic memory monitoring prevents system overload:

from diskcleaner.optimization.memory import MemoryMonitor

monitor = MemoryMonitor(threshold_mb=1000)
if monitor.should_pause():
    # Reduce concurrency
    workers = monitor.get_optimal_workers(current_workers)

Script Reference

analyze_disk.py

Main disk analysis tool that identifies space consumption patterns.

Key capabilities:

• High-speed scanning with os.scandir() (3-5x faster)
• Scan large directories (100K+ files) in seconds
• Cross-platform path exclusion (Windows/macOS/Linux)
• Detailed statistics and reports

Common use cases:

"Analyze my C drive and show what's taking up space"
"What are the largest directories in my home folder?"
"Show me temp files taking up space"
"Scan this 400GB directory quickly"

clean_disk.py

Safe junk file removal with multiple safety mechanisms.

Safety features:

• Protected paths (never deletes system directories)
• Protected extensions (never deletes executables)
• Dry-run mode by default
• Detailed logging of all operations
• Handles empty categories gracefully

Categories cleaned:

• temp: Temporary files (%TEMP%, /tmp, etc.)
• cache: Application and browser caches
• logs: Log files (older than 30 days default)
• recycle: Recycle bin / trash
• downloads: Old download files (configurable age)

Important: Always run with --dry-run first to preview changes.

monitor_disk.py

Continuous or one-shot disk usage monitoring.

Features:

• Multi-drive monitoring (all mount points)
• Configurable warning/critical thresholds
• Continuous monitoring mode with alerts
• JSON output for automation
• Non-zero exit codes for CI/CD integration

Exit codes:

• 0: All drives OK
• 1: Warning threshold exceeded
• 2: Critical threshold exceeded

Platform-Specific Information

See temp_locations.md for:

• Complete list of temporary file locations by platform
• Browser cache locations
• Development tool caches
• Safety guidelines for each platform

Platform-specific optimizations:

• Windows: Excludes C:\Windows, C:\Program Files, etc.
• macOS: Excludes /System, /Library, /private/var/vm (VM swap)
• Linux: Excludes /proc, /sys, /dev, /run

When to read this file:

• User asks about specific platform cleanup locations
• Need to understand what gets cleaned on each OS
• Customizing cleanup for specific applications

Safety Rules

The scripts implement multiple safety layers:

1. Protected Paths: System directories never touched
2. Protected Extensions: Executables and system files protected
3. Dry Run Default: Must use --force for actual deletion
4. Age Filters: Logs cleaned only after 30+ days
5. Error Handling: Permission errors don’t stop execution
6. Graceful Degradation: Handles edge cases (empty categories, missing paths)

Protected extensions:

.exe, .dll, .sys, .drv, .bat, .cmd, .ps1, .sh, .bash, .zsh,
.app, .dmg, .pkg, .deb, .rpm, .msi, .iso, .vhd, .vhdx

Typical Workflows

Workflow 1: Investigate and Clean

When user says “My C drive is full”:

1. Analyze current state: python skills/disk-cleaner/scripts/analyze_disk.py
2. Preview cleanup: python skills/disk-cleaner/scripts/clean_disk.py --dry-run
3. Review report, confirm with user
4. Execute cleanup: python skills/disk-cleaner/scripts/clean_disk.py --force
5. Verify results: python skills/disk-cleaner/scripts/analyze_disk.py

Workflow 2: Continuous Monitoring

For proactive disk management:

1. Start monitor: python skills/disk-cleaner/scripts/monitor_disk.py --watch --interval 300
2. Set appropriate thresholds: --warning 70 --critical 85
3. Monitor alerts and take action when needed

Workflow 3: Large-Scale Analysis (NEW)

For analyzing large directories (100K+ files):

# Use intelligent sampling for quick estimates
python skills/disk-cleaner/scripts/analyze_disk.py --path "D:\Large\Project" --sample

# Full scan if needed
python skills/disk-cleaner/scripts/analyze_disk.py --path "D:\Large\Project" --full

# Performance: Can scan 442K files in ~14 seconds

Workflow 4: One-Time Deep Clean

For thorough cleanup:

# Preview all cleaning
python skills/disk-cleaner/scripts/clean_disk.py --dry-run

# If satisfied, execute
python skills/disk-cleaner/scripts/clean_disk.py --force

# Analyze results
python skills/disk-cleaner/scripts/analyze_disk.py

Output Formats

Interactive Mode (Default)

Human-readable console output with:

• Visual progress bars
• Emoji indicators for status
• Formatted tables

JSON Mode

Machine-readable output for:

• Automation pipelines
• Log aggregation
• Further processing

Use --json flag with any script.

Report Files

Save detailed reports with --output report.json for:

• Historical tracking
• Comparison over time
• Audit trails

Advanced Usage

Python API

For integration with other tools:

from diskcleaner.core import DirectoryScanner, SmartCleanupEngine

# Scan directory
scanner = DirectoryScanner("/path/to/scan")
files = scanner.scan()

# Analyze and get recommendations
engine = SmartCleanupEngine("/path/to/scan")
report = engine.analyze()

# Clean with safety checks
results = engine.clean(
    categories=["temp", "cache", "logs"],
    dry_run=True  # Set False to actually delete
)

Performance Optimization

For maximum performance on large directories:

from diskcleaner.optimization.scan import ConcurrentScanner, QuickProfiler

# Quick profiling first
profiler = QuickProfiler(sample_time=1.0)
profile = profiler.profile(large_path)

print(f"Estimated: {profile.file_count:,} files")
print(f"Estimated time: {profile.estimated_time:.1f}s")

# Full concurrent scan if needed
if profile.file_count < 100000:
    scanner = ConcurrentScanner()
    result = scanner.scan(large_path)

Testing

Comprehensive test suite ensures reliability:

• 244 tests covering all functionality
• Cross-platform: Windows, macOS, Linux
• All Python versions: 3.8, 3.9, 3.10, 3.11, 3.12
• Performance benchmarks: Validate optimization improvements
• Integration tests: End-to-end workflows

Run tests:

# Run all tests
pytest tests/

# Run specific test category
pytest tests/test_optimization.py
pytest tests/benchmarks/

# With coverage
pytest tests/ --cov=diskcleaner --cov-report=html

Troubleshooting

Permission Errors

The scanner handles permission errors gracefully. Protected directories are automatically skipped on each platform:

• Windows: C:\Windows, C:\Program Files
• macOS: /System, /Library, /private/var/vm
• Linux: /proc, /sys, /dev

Performance Issues

If scanning seems slow:

1. Check if path is network drive (slower than local)
2. Verify anti-virus isn’t scanning every file access
3. Use --sample flag for quick estimates on large directories

Empty Results

If no files found:

1. Check path exists and is accessible
2. Verify files aren’t all protected (system directories)
3. Run with higher verbosity to see what’s being scanned

Contributing

To modify or extend the toolkit:

1. Optimization modules: diskcleaner/optimization/

   • scan.py: ConcurrentScanner, QuickProfiler
   • hash.py: AdaptiveHasher, DuplicateFinder
   • delete.py: BatchDeleter, AsyncDeleter
   • memory.py: MemoryMonitor
   • profiler.py: PerformanceProfiler

2. Core modules: diskcleaner/core/

   • scanner.py: DirectoryScanner with os.scandir()
   • smart_cleanup.py: SmartCleanupEngine
   • Other core components

3. Platform-specific: diskcleaner/platforms/

   • Windows, macOS, Linux implementations

4. Tests: tests/

   • Unit tests for all components
   • Performance benchmarks
   • Cross-platform tests

5. Scripts: scripts/

   • User-facing CLI tools

Always run tests after changes:

pytest tests/ -v
pre-commit run --all-files

License

MIT License – See LICENSE file for details.