disk-cleaner

What this skill does

# Disk Cleaner Skill - Complete Feature Guide for All Agents

## 🚨 IMPORTANT: Emoji Usage Policy

### For Script Output (Cross-Platform Safety)
- **NEVER use emoji in script output** - All scripts use ASCII-safe characters
- Scripts use: `[OK]`, `[X]`, `[!]`, `[*]`, `[i]`, `[DIR]`, `[FILE]`, `[PKG]`, `[x]`
- This ensures compatibility with Windows GBK and other non-UTF-8 consoles
- **DO NOT modify script output to add emoji** - This will break cross-platform compatibility

### For Agent-to-Human Communication (Recommended)
- **SHOULD use emoji when reporting results to humans** - Makes output more readable
- Use these emoji in your final reports to users:
  - `✅` (Success) - Completed operations, successful scans
  - `❌` (Error) - Failed operations, critical errors
  - `⚠️` (Warning) - Warnings, issues that need attention
  - `🔍` (Scanning) - Search/scan operations
  - `📊` (Statistics) - Analysis results, statistics
  - `📁` (Directory) - Directory-related information
  - `📦` (Package) - Package/module information
  - `🎉` (Success) - Celebratory messages for successful completion
  - `🚨` (Critical) - Critical warnings
  - `💡` (Tip) - Suggestions, recommendations
  - `📋` (List) - Checklists, summaries
  - `🔧` (Tool) - Tools, utilities
  - `🌐` (Global) - Cross-platform, universal features
  - `🛡️` (Safety) - Safety-related information
  - `⚡` (Performance) - Performance improvements
  - `📝` (Document) - Documentation
  - `🎓` (Learning) - Educational content
  - `📞` (Support) - Help, support information
  - `📈` (Growth) - Improvements, gains
  - `🎯` (Target) - Goals, objectives
  - `🚀` (Launch) - Quick start, fast operations
  - `🛠️` (Tools) - Tool-related features

**Example:**
```
Script output (ASCII):    [OK] Scan completed: 50,000 files in 30 seconds
Your report to human:     ✅ Scan completed successfully! Found 50,000 files in 30 seconds
```

---

## 📦 COMPLETE FEATURE LIST (READ THIS FIRST!)

### 🚨 CRITICAL: Progressive Scanning (MANDATORY for Large Disks)
- ✅ **Quick Sample Mode**: 1-second estimation of disk size and scan time
- ✅ **Progressive Scan Mode**: Get partial results in 30 seconds for large disks
- ✅ **Smart Time Limits**: Prevent users from waiting hours
- ✅ **Real-time Feedback**: Progress updates every 2 seconds
- ✅ **Interruptible**: Ctrl+C to get partial results

### 🔧 Intelligent Bootstrap (Auto-Detection & Import)
- ✅ **Auto Location Detection**: Searches 20+ common skill package locations
- ✅ **Environment Variable Support**: DISK_CLEANER_SKILL_PATH override
- ✅ **Auto Module Import**: Automatically imports diskcleaner modules
- ✅ **Fallback Mechanisms**: Works even if some features unavailable
- ✅ **Cross-Platform Python Detection**: Tries both 'python' and 'python3'

### 🌐 Universal Compatibility
- ✅ **All AI IDEs**: Cursor, Windsurf, Continue, Aider, Claude Code, etc.
- ✅ **All Platforms**: Windows, macOS, Linux (including Windows GBK console)
- ✅ **All Installation Levels**: Global, project, user level
- ✅ **No Configuration Needed**: Works out of the box
- ✅ **Cross-Platform Encoding**: All scripts use ASCII-safe output (v2.0+)

### 🛡️ Safety & Reliability
- ✅ **Diagnostic Tool**: check_skill.py - verifies all functionality
- ✅ **Safe Encoding**: All scripts use ASCII characters (no emoji in output)
- ✅ **Safe Defaults**: --dry-run for cleaning, smart limits for scanning
- ✅ **Protected Paths**: Never deletes system directories or executables
- ✅ **Error Handling**: Graceful degradation on errors
- ✅ **GBK/UTF-8 Compatible**: Works on Windows GBK, UTF-8, and all other encodings

### ⚡ Performance Optimizations (ALL INCLUDED)
- ✅ **QuickProfiler**: Fast sampling to estimate scan characteristics
- ✅ **ConcurrentScanner**: Multi-threaded I/O for 3-5x speedup
- ✅ **os.scandir() Optimization**: 3-5x faster than Path.glob
- ✅ **IncrementalCache**: Cache scan results for faster repeat scans
- ✅ **Memory Monitoring**: Auto-adapts based to available memory
- ✅ **Early Stopping**: Configurable file/time limits
- ✅ **Enhanced Cache Detection**: 26+ cache paths (was 8) - 225% improvement

### 🆕 v2.2+ New Features
- ✅ **Duplicate File Detection**: Find and remove duplicate files with adaptive strategies
- ✅ **Growth Trend Analysis**: Track disk usage over time, predict when disk will be full
- ✅ **Interactive Wizard**: Step-by-step guided cleanup with safety confirmations
- ✅ **File Organization**: Intelligent file archival and organization (4 strategies)
- ✅ **Enhanced Scan Limits**: 500K files (was 50K), 120s timeout (was 30s)
- ✅ **Deep Scan Mode**: `--deep-scan` for unlimited scanning
- ✅ **Windows Directory Support**: `--include-windows` for system directory scanning

### 📊 Available Scripts (13+ Total)
**Core Analysis:**
1. **analyze_disk.py** - Disk analysis with smart sampling (enhanced v2.2)
2. **analyze_progressive.py** - Progressive scanning for large disks
3. **find_duplicates.py** - Duplicate file detection (NEW v2.2)
4. **analyze_growth.py** - Growth trend analysis (NEW v2.2)

**Cleaning & Organization:**
5. **clean_disk.py** - Safe junk file cleaning (enhanced cache detection)
6. **interactive_wizard.py** - Interactive guided cleanup (NEW v2.2)
7. **organize_files.py** - File archival and organization (NEW v2.2)

**Monitoring & Diagnostics:**
8. **monitor_disk.py** - Disk usage monitoring
9. **check_skill.py** - Diagnostic tool

**Developer Tools:**
10. **skill_bootstrap.py** - Intelligent bootstrap module
11. **package_skill.py** - Package creation tool
12. **scheduler.py** - Automated scheduling

### 🚀 Multi-Agent Acceleration (CRITICAL FOR PERFORMANCE)

**🎯 KEY INSIGHT: Use Sub-Agents for Parallel Processing**

This is one of the MOST POWERFUL features of disk-cleaner when used by AI Agents!

#### Why Use Multiple Agents?

Single-threaded scanning:
```
Agent scans → [Dir1] → [Dir2] → [Dir3] → ... (sequential, slow)
```

Multi-Agent parallel scanning:
```
Main Agent
  ├─ Sub-Agent-1 scans → [Dir1, Dir2, Dir3] (parallel)
  ├─ Sub-Agent-2 scans → [Dir4, Dir5, Dir6] (parallel)
  └─ Sub-Agent-3 scans → [Dir7, Dir8, Dir9] (parallel)
Result: 3-10x faster! ⚡
```

#### When to Use Multi-Agent Mode?

✅ **ALWAYS use when:**
- Scanning multiple top-level directories (e.g., C:\, D:\, E:\)
- Cleaning multiple user profiles
- Processing large file sets (>100K files)
- Time-critical operations

❌ **Don't use when:**
- Single small directory (<10K files)
- Quick analysis (<30 seconds)
- Simple cleanup tasks

#### How to Implement Multi-Agent Scanning

**Option 1: Use Agent Tool (Recommended for Claude Code)**

```python
# Agent code that spawns sub-agents
from anthropic import Anthropic

def parallel_scan_directories(directories_list):
    """
    Scan multiple directories in parallel using sub-agents
    """
    # Split directories among sub-agents (3-5 agents optimal)
    chunks = split_list(directories_list, n_chunks=3)
    
    # Launch sub-agents in parallel
    agents = []
    for i, chunk in enumerate(chunks):
        agent = Anthropic().agent.create(
            name=f"scanner-{i}",
            instructions=f"""
            Scan these directories: {chunk}
            Use disk-cleaner with: --file-limit 50000 --time-limit 60
            Return results in JSON format
            """,
            model="claude-sonnet-4-20250514"  # Fast model
        )
        agents.append(agent)
    
    # Wait for all agents and collect results
    results = [agent.wait() for agent in agents]
    return merge_results(results)
```

**Option 2: Parallel Subprocess (Platform Independent)**

```python
import subprocess
from concurrent.futures import ThreadPoolExecutor, as_completed

def parallel_scan_subprocess(directories_list):
    """
    Scan multiple directories using parallel subprocess calls
    Works with ALL AI IDEs that support subprocess
    """
    def scan_directory(directory):
        """Scan a single directory"""
        cmd = [
            'python',
            'skills/disk-cleaner/scripts/analyze_dis