Disk Cleaner v2.1 - Intelligent Cross-Platform Disk Management

A comprehensive cross-platform disk space monitoring, analysis, and intelligent cleaning toolkit. Features advanced 3D file classification, duplicate detection, automated scheduling, and platform-specific optimization.

⚡ Quick Install

Option 1: Install as Agent Skill (Recommended)

Install directly from CLI:

npx add-skill gccszs/disk-cleaner

OR

npx skills add gccszs/disk-cleaner

This will install the skill with all necessary files. The .skill package contains only the essential components:

✅ Core modules (diskcleaner/)
✅ Executable scripts (scripts/)
✅ Skill definition (SKILL.md)
✅ Reference documentation (references/)

Note: The skill package excludes tests, CI/CD configs, and development files for a clean, minimal installation.

Option 2: Clone Repository

For development or standalone use:

git clone https://github.com/gccszs/disk-cleaner.git
cd disk-cleaner

See Usage section for how to run the scripts.

✨ v2.1 New Features

🚀 Critical Cross-Platform Encoding Fix

✅ ASCII-Safe Output - All scripts use ASCII characters for 100% cross-platform compatibility
🌐 Universal Console Support - Works on Windows GBK, Linux UTF-8, macOS UTF-8, and any other encoding
🛡️ No Encoding Errors - Eliminates UnicodeEncodeError on all platforms
📝 Smart Emoji Policy - Scripts use ASCII, Agents can use emojis when reporting to users

⚡ Progressive Scanning for Large Disks

🔍 Quick Sample Mode - Estimate disk size and scan time in just 1 second
📊 Progressive Scan Mode - Get partial results in 30 seconds for large disks (500GB+)
⏱️ Smart Time Limits - Prevent users from waiting hours for full scans
🔄 Real-Time Feedback - Progress updates every 2 seconds
⏸️ Interruptible - Press Ctrl+C to get partial results anytime

🤖 Intelligent Bootstrap System

📍 Auto Location Detection - Automatically searches 20+ common skill package locations
🔧 Environment Variable Support - Override with DISK_CLEANER_SKILL_PATH
📦 Auto Module Import - Automatically imports diskcleaner modules with fallbacks
🌍 Cross-Platform Python Detection - Tries both python and python3
🛠️ Diagnostic Tool - check_skill.py verifies all functionality

🎯 Advanced Performance Optimizations

⚡ 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 on available memory
⏹️ Early Stopping - Configurable file/time limits

🔧 Core v2.0 Features

🤖 Intelligent 3D Classification - Files categorized by type, risk level, and age
🔍 Adaptive Duplicate Detection - Fast/accurate strategies with automatic optimization
⚡ Incremental Scanning - Cache-based performance optimization for repeated scans
🔒 Process-Aware Safety - File lock detection and process termination
💻 Platform-Specific Optimization - Windows Update, APT, Homebrew cache detection
⏰ Automated Scheduling - Timer-based cleanup tasks
🎯 Interactive Cleanup UI - 5 view modes with visual feedback
🛡️ Enhanced Safety - Protected paths, 'YES' confirmation, backup & logging

Features

Core Capabilities

Disk Space Analysis: Identify large files and directories consuming disk space
Smart Cleanup: AI-powered suggestions based on file patterns and usage
Duplicate Detection: Find and remove duplicate files to reclaim space
Safe Junk Cleaning: Remove temporary files, caches, logs with built-in safety mechanisms
Disk Monitoring: Real-time monitoring with configurable alert thresholds
Cross-Platform: Full support for Windows, Linux, and macOS
Zero Dependencies: Pure Python standard library implementation

Advanced Features

3D File Classification: Type × Risk × Age matrix for smart decisions
Incremental Scanning: Only scan changed files for 10x faster subsequent scans
File Lock Detection: Prevents deletion of locked files on all platforms
Platform-Specific Cleanup: Windows Update, Linux package caches, macOS Xcode derived data
Automated Scheduling: Set up recurring cleanup tasks with custom intervals
Interactive Selection: Choose exactly what to clean with detailed previews

Quick Start

Prerequisites

Python 3.7 or higher (no external dependencies required - uses only standard library).

Basic Usage

# Quick sample mode (1 second) - NEW v2.0
python skills/disk-cleaner/scripts/analyze_disk.py --sample

# Progressive scanning for large disks - NEW v2.0
python skills/disk-cleaner/scripts/analyze_progressive.py --max-seconds 30

# Verify skill package - NEW v2.0
python skills/disk-cleaner/scripts/check_skill.py

# Analyze disk space (with smart defaults)
python skills/disk-cleaner/scripts/analyze_disk.py

# Smart cleanup with duplicate detection (NEW v2.1)
python -c "from diskcleaner.core import SmartCleanupEngine; engine = SmartCleanupEngine('.'); print(engine.get_summary(engine.analyze()))"

# Preview cleanup (dry-run mode)
python skills/disk-cleaner/scripts/clean_disk.py --dry-run

# Monitor disk usage
python skills/disk-cleaner/scripts/monitor_disk.py

# Continuous monitoring
python skills/disk-cleaner/scripts/monitor_disk.py --watch

v2.1 Advanced Usage

# Quick sample (estimate scan time) - NEW v2.0
python skills/disk-cleaner/scripts/analyze_disk.py --sample --json

# Progressive scanning (30-second limit) - NEW v2.0
python skills/disk-cleaner/scripts/analyze_progressive.py --max-seconds 30

# Progressive scanning (file limit) - NEW v2.0
python skills/disk-cleaner/scripts/analyze_progressive.py --max-files 50000

# Schedule automated cleanup (NEW v2.0)
python skills/disk-cleaner/scripts/scheduler.py add "Daily Cleanup" /tmp 24h --type smart
python skills/disk-cleaner/scripts/scheduler.py run  # Run due tasks

# Platform-specific cleanup suggestions
python -c "from diskcleaner.platforms import WindowsPlatform; import pprint; pprint.pprint(WindowsPlatform.get_system_maintenance_items())"

Usage Examples

Example 1: Smart Cleanup with Duplicate Detection

from diskcleaner.core import SmartCleanupEngine

# Initialize engine
engine = SmartCleanupEngine("/path/to/clean", cache_enabled=True)

# Analyze directory
report = engine.analyze(
    include_duplicates=True,
    safety_check=True
)

# Get summary
print(engine.get_summary(report))

# Interactive cleanup (if you want)
from diskcleaner.core import InteractiveCleanupUI
ui = InteractiveCleanupUI(report)
ui.display_menu()  # Shows 5 view options

Example 2: Automated Scheduling

# Add daily cleanup task
python skills/disk-cleaner/scripts/scheduler.py add "Daily Temp Cleanup" /tmp 24h --type temp

# List all scheduled tasks
python skills/disk-cleaner/scripts/scheduler.py list

# Run due tasks (dry-run by default)
python skills/disk-cleaner/scripts/scheduler.py run

# Run with actual deletion
python skills/disk-cleaner/scripts/scheduler.py run --force

Example 3: Platform-Specific Cleanup

from diskcleaner.platforms import WindowsPlatform, LinuxPlatform, MacOSPlatform
import platform

if platform.system() == "Windows":
    platform_impl = WindowsPlatform()
elif platform.system() == "Linux":
    platform_impl = LinuxPlatform()
else:
    platform_impl = MacOSPlatform()

# Get platform-specific cleanup suggestions
items = platform_impl.get_system_maintenance_items()
for key, item in items.items():
    print(f"{item['name']}: {item['description']}")
    print(f"  Risk: {item['risk']}, Size: {item['size_hint']}")

Installation

Quick Install (Recommended)

Install directly from GitHub using Vercel's add-skill CLI:

npx add-skill gccszs/disk-cleaner -g

Replace gccszs with your actual GitHub username.

As a Claude Code Skill (Manual)

Download disk-cleaner.skill from the Releases page

Install via Claude Code:

/skill install path/to/disk-cleaner.skill

Standalone Usage

# Clone the repository
git clone https://github.com/gccszs/disk-cleaner.git
cd disk-cleaner

# Scripts are ready to use (no dependencies needed)
python skills/disk-cleaner/scripts/analyze_disk.py

Usage Examples

Disk Space Analysis

# 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 for automation
python skills/disk-cleaner/scripts/analyze_disk.py --json

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

Cleaning Junk Files

IMPORTANT: Always run with --dry-run first to preview changes!

# Preview cleanup (recommended first step)
python skills/disk-cleaner/scripts/clean_disk.py --dry-run

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

# Clean specific categories
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

Disk Monitoring

# 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 - exit codes based on status)
python skills/disk-cleaner/scripts/monitor_disk.py --alerts-only

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

Scripts Reference

`analyze_disk.py`

Disk space analysis tool with progressive scanning support (v2.0+).

New in v2.0:

Quick Sample Mode (--sample): 1-second estimation of scan time
Smart Limits: Default 50,000 files, 30 seconds for large disks
Progressive Display: Real-time feedback during scanning
Auto-Sampling: Automatically suggests scan mode based on disk size

Capabilities:

Scan directories to find largest files and folders
Analyze temporary file locations
Calculate disk usage statistics
Generate detailed reports

`analyze_progressive.py` (NEW v2.0)

Progressive scanning tool specifically designed for large disks.

Features:

Quick Sample (--sample): 1-second estimation
Progressive Scan (--max-seconds): Get results in 30 seconds
File Limit (--max-files): Limit scan to specific file count
Real-Time Progress: Updates every 2 seconds
Interruptible: Press Ctrl+C for partial results

Usage:

# Quick sample
python skills/disk-cleaner/scripts/analyze_progressive.py --sample

# 30-second progressive scan
python skills/disk-cleaner/scripts/analyze_progressive.py --max-seconds 30

# Limit file count
python skills/disk-cleaner/scripts/analyze_progressive.py --max-files 50000

`check_skill.py` (NEW v2.0)

Diagnostic tool to verify skill package functionality.

Checks:

Python version and platform
File structure integrity
Module imports
File permissions
Script execution

Usage:

python skills/disk-cleaner/scripts/check_skill.py

`skill_bootstrap.py` (NEW v2.0)

Intelligent bootstrap module for automatic environment setup.

Features:

Auto-detects skill package location (20+ locations)
Automatically imports diskcleaner modules
Cross-platform encoding handling
Graceful fallbacks for errors

Usage:

from skill_bootstrap import import_diskcleaner_modules

success, modules = import_diskcleaner_modules()
if success:
    ProgressBar = modules['ProgressBar']
    DirectoryScanner = modules['DirectoryScanner']

`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

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)

`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 Support

Feature	Windows	Linux	macOS
Disk Analysis	✅	✅	✅
Progressive Scanning (NEW)	✅	✅	✅
Quick Sample Mode (NEW)	✅	✅	✅
Temp Cleaning	✅	✅	✅
Cache Cleaning	✅	✅	✅
Log Cleaning	✅	✅	✅
Recycle Bin	✅	✅	✅
Real-time Monitoring	✅	✅	✅
GBK Console Support (NEW)	✅	N/A	N/A
UTF-8 Console Support	✅	✅	✅

Windows-Specific Locations

%TEMP%, %TMP%, %LOCALAPPDATA%\Temp
C:\Windows\Temp, C:\Windows\Prefetch
C:\Windows\SoftwareDistribution\Download
Browser caches (Chrome, Edge, Firefox)
Development tool caches (npm, pip, Gradle, Maven)

Linux-Specific Locations

/tmp, /var/tmp, /var/cache
Package manager caches (apt, dnf, pacman)
Browser caches
Development tool caches

macOS-Specific Locations

/tmp, /private/tmp, /var/folders
~/Library/Caches, ~/Library/Logs
iOS device backups
Homebrew cache

Safety Features

Protected Paths

System directories are never touched:

Windows: C:\Windows, C:\Program Files, C:\ProgramData
Linux/macOS: /usr, /bin, /sbin, /System, /Library

Protected Extensions

Executables and system files are protected:

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

Use Cases

1. Free Up C Drive Space on Windows

# Analyze what's taking space
python skills/disk-cleaner/scripts/analyze_disk.py

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

# Execute cleanup
python skills/disk-cleaner/scripts/clean_disk.py --force

2. Automated Disk Monitoring

# Run in background with custom thresholds
python skills/disk-cleaner/scripts/monitor_disk.py --watch --warning 70 --critical 85 --interval 300

3. CI/CD Integration

# Check disk space in pipeline
python skills/disk-cleaner/scripts/monitor_disk.py --alerts-only --json

# Exit codes: 0=OK, 1=WARNING, 2=CRITICAL
if [ $? -ne 0 ]; then
  echo "Disk space issue detected!"
fi

Development

Project Structure

disk-cleaner/
├── skills/                   # Skills marketplace directory
│   └── disk-cleaner/
│       ├── SKILL.md          # Complete skill guide (v2.0)
│       ├── ENCODING_FIX_SUMMARY.md    # Encoding fix documentation (NEW)
│       ├── PROGRESSIVE_SCAN_SUMMARY.md # Progressive scanning guide (NEW)
│       ├── UNIVERSAL_INSTALL.md       # Universal installation guide (NEW)
│       ├── NO_PYTHON_GUIDE.md         # Guide for users without Python (NEW)
│       ├── FIXES.md                  # v2.0 fixes list (NEW)
│       ├── AGENT_QUICK_REF.txt       # Agent quick reference (NEW)
│       ├── README.md         # Skill documentation
│       ├── diskcleaner.skill # Self-contained skill package (v2.0)
│       ├── scripts/          # Executable scripts
│       │   ├── analyze_disk.py       # Enhanced with progressive scanning
│       │   ├── analyze_progressive.py # NEW: Progressive scanning
│       │   ├── clean_disk.py          # Safe cleanup
│       │   ├── monitor_disk.py        # Disk monitoring
│       │   ├── scheduler.py           # Automated scheduling
│       │   ├── check_skill.py         # NEW: Diagnostic tool
│       │   ├── skill_bootstrap.py     # NEW: Intelligent bootstrap
│       │   └── package_skill.py       # Package creation tool
│       ├── diskcleaner/      # Core Python module (self-contained)
│       │   ├── core/         # Core functionality
│       │   ├── optimization/ # Performance optimizations (v2.0)
│       │   ├── platforms/    # Platform-specific code
│       │   └── config/       # Configuration
│       └── references/       # Reference documentation
│           └── temp_locations.md
├── tests/                    # Test suite (244 tests)
└── docs/                     # Additional documentation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This tool modifies files on your system. Always:

Review the dry-run output before actual cleaning
Backup important data before cleanup
Use at your own risk

The authors are not responsible for any data loss or system issues.

Acknowledgments

Built as a Claude Code Skill
Installable via Vercel's add-skill CLI
Cross-platform compatibility tested on Windows 10/11, Ubuntu 20.04+, macOS 12+

Name		Name	Last commit message	Last commit date
Latest commit History 97 Commits
.github/workflows		.github/workflows
diskcleaner		diskcleaner
docs		docs
examples		examples
scripts		scripts
skills/disk-cleaner		skills/disk-cleaner
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README_zh.md		README_zh.md
V2.1-DEVELOPMENT-SUMMARY.md		V2.1-DEVELOPMENT-SUMMARY.md
mypy.ini		mypy.ini
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
test_cache_detection.py		test_cache_detection.py
test_emergency_fixes.py		test_emergency_fixes.py
test_new_features.py		test_new_features.py

Folders and files

Latest commit

History

Repository files navigation

Disk Cleaner v2.1 - Intelligent Cross-Platform Disk Management

⚡ Quick Install

Option 1: Install as Agent Skill (Recommended)

Option 2: Clone Repository

✨ v2.1 New Features

🚀 Critical Cross-Platform Encoding Fix

⚡ Progressive Scanning for Large Disks

🤖 Intelligent Bootstrap System

🎯 Advanced Performance Optimizations

🔧 Core v2.0 Features

Features

Core Capabilities

Advanced Features

Quick Start

Prerequisites

Basic Usage

v2.1 Advanced Usage

Usage Examples

Example 1: Smart Cleanup with Duplicate Detection

Example 2: Automated Scheduling

Example 3: Platform-Specific Cleanup

Installation

Quick Install (Recommended)

As a Claude Code Skill (Manual)

Standalone Usage

Usage Examples

Disk Space Analysis

Cleaning Junk Files

Disk Monitoring

Scripts Reference

analyze_disk.py

analyze_progressive.py (NEW v2.0)

check_skill.py (NEW v2.0)

skill_bootstrap.py (NEW v2.0)

clean_disk.py

monitor_disk.py

Platform Support

Windows-Specific Locations

Linux-Specific Locations

macOS-Specific Locations

Safety Features

Protected Paths

Protected Extensions

Use Cases

1. Free Up C Drive Space on Windows

2. Automated Disk Monitoring

3. CI/CD Integration

Development

Project Structure

Contributing

License

Disclaimer

Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`analyze_disk.py`

`analyze_progressive.py` (NEW v2.0)

`check_skill.py` (NEW v2.0)

`skill_bootstrap.py` (NEW v2.0)

`clean_disk.py`

`monitor_disk.py`

Packages