Disk Cleaner

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:

1. clean_disk.py - Safe junk file cleaning (enhanced cache detection)
2. interactive_wizard.py - Interactive guided cleanup (NEW v2.2)
3. organize_files.py - File archival and organization (NEW v2.2)

Monitoring & Diagnostics:

1. monitor_disk.py - Disk usage monitoring
2. check_skill.py - Diagnostic tool

Developer Tools:

1. skill_bootstrap.py - Intelligent bootstrap module
2. package_skill.py - Package creation tool
3. scheduler.py - Automated scheduling

macOS QQ media cleanup

Use scripts/qq_cleanup_macos.zsh when QQ pictures or emojis consume excessive space on macOS and chat records must remain intact.

1. Audit QQ storage without changing files:

   scripts/qq_cleanup_macos.zsh audit

1. Preview pictures and emojis older than 90 days:

   scripts/qq_cleanup_macos.zsh clean --older-than-days 90 --categories Pic,Emoji

1. Report the preview and obtain explicit approval. Quit QQ, then repeat the approved command with --execute.

Never select nt_db, account roots, preferences, voice messages, videos, or received files. The script accepts only Pic and Emoji, defaults to preview, and refuses execution while QQ is running. Warn that removed local media might no longer be available in old conversations.

🚀 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)

# 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}