Disk Sweeper

MCP Tools

Intelligent disk space analysis and cleanup tool with safety grading, duplicate detection, and Chinese app cache recognition.

Install

openclaw skills install disk-sweeper

Disk Cleaner (disk-sweeper)

Smart disk space analysis and cleanup. Scans directories, analyzes file usage by type/size/age, detects duplicates, identifies Chinese application caches, and generates safety-graded cleanup recommendations.

Key differentiator: System-critical path protection (never touches /System, /bin, etc.) and deep recognition of Chinese app caches (WeChat, DingTalk, QQ, etc.).

Quick Start

clawhub run disk-sweeper scan --paths ~/

Produces a comprehensive disk analysis report with type distribution, top files, and safety-graded cleanup suggestions.

Features

Feature	Description
Smart Scanning	Recursive with streaming, parallel, auto-skip no-permission dirs
Multi-dimension Analysis	By type, directory, extension, age, top-N large files
Duplicate Detection	SHA-256 content hash (size-grouped → head hash → full hash)
Chinese App Cache	WeChat/DingTalk/QQ/Baidu/WPS/Netease music cache recognition
System Cache Analysis	macOS caches, Xcode, Docker, node_modules, npm/yarn, Homebrew
Safety Grading	🟢SAFE / 🟡CLEANABLE / 🟠CAUTION / 🔴PROTECTED with rationale
Cleanup Modes	Preview (default), Interactive, Auto-Safe, Custom
Undo Support	Moves to trash instead of permanent delete

Safety Protection

The following paths are permanently excluded and cannot be overridden:

/System/*, /bin/*, /sbin/*, /usr/bin/*, /etc/*, /dev/*, /proc/*, /core/*
Symbolic links crossing into system directories

Sample Prompts

Prompt 1: Quick Scan

clawhub run disk-sweeper scan --paths ~/

Expected output: 📊 Disk analysis report with:

💾 Total usage: 156.4 GB | Free: 89.2 GB
📁 By type: Video 48GB, Images 32GB, Apps 25GB, Cache 18GB...
🔍 Top 10 largest files
🧹 Cleanable: ~12.5 GB

Prompt 2: Duplicate Detection

clawhub run disk-sweeper analyze --detect-duplicates --paths ~/Documents ~/Pictures

Expected output: 🔁 38 duplicate groups, wasting 8.3 GB

Group 1: 3 copies of 2025-archive.zip (1.2 GB each)
Suggested: disk-sweeper dedupe --group 1

Prompt 3: Safe Cleanup Preview

clawhub run disk-sweeper clean --mode preview

Expected output: All 🟢SAFE cleanup items previewed, then:

clawhub run disk-sweeper clean --mode auto-safe --confirm

✅ Removed 127 files, freed 5.8 GB

Prompt 4: Cache Analysis

clawhub run disk-sweeper analyze --detect-caches

Expected output: Cache breakdown by app with safety ratings:

WeChat: 12.3 GB ⚠️ CAUTION (chat attachments)
Docker: 8.7 GB 🟡 CLEANABLE (unused images)
Xcode: 15.2 GB 🟡 CLEANABLE (DerivedData)
npm: 2.1 GB 🟢 SAFE (reconstructable)

Prompt 5: Scheduled Weekly Scan

clawhub run disk-sweeper scan --summary-only --output-format json

First-Success Path

Goal: Valuable disk analysis within 5 seconds of installation.

Step 1: clawhub install disk-sweeper
Step 2: clawhub run disk-sweeper scan
Step 3: Internal pipeline:
  a. scanner.py streams from ~ (real-time progress)
  b. analyzer.py aggregates by type/directory
  c. safety.py grades every item
  d. formatter.py renders Markdown report
Step 4: User sees disk overview + top files + cleanup suggestions
Step 5: User finds a removable 8GB old file → first value

Key Metrics: 100K files scanned in < 5s, zero params sufficient, > 95% chance of valuable discovery.

Architecture

disk-sweeper/
├── SKILL.md
├── scripts/
│   ├── scanner.py         # Filesystem scanner (streaming + progress)
│   ├── analyzer.py        # Space analysis engine
│   ├── duplicates.py      # Duplicate file detection (SHA-256)
│   ├── caches.py          # App cache recognition
│   ├── safety.py          # Safety grading + protection list
│   ├── cleaner.py         # Cleanup executor (trash/delete/undo)
│   ├── formatter.py       # Report formatting
│   └── progress.py        # Progress bar + status output
└── references/
    ├── protected-paths.json   # System path protection list
    ├── cache-patterns.json    # App cache patterns
    └── file-types.json        # Extension → file type mapping

Error Handling

Code	Scenario	Action
E001	Invalid scan path	Exit, list invalid paths
E002	Out of memory (large scan)	Process in batches
E003	Hash calculation failure	Skip file, continue
E004	File locked during cleanup	Skip, log to report
E005	Trash unavailable (headless)	Fallback to direct delete (with confirm)
E006	Write permission denied	Error + output to stdout
E007	User interrupt (SIGINT)	Graceful exit, log completed ops

Security

Hardcoded protected paths: /System, /bin, /sbin, /usr/bin, /etc — user cannot override
Transparent safety rating: Every cleanup item labeled with grade and reason
Preview by default: Cleanup only previews, requires explicit --confirm
Trash by default: use_trash: true moves to trash, not permanent delete
Zero network: Entire process is offline
No content reading: Only filename/size/hash, never file content
No symlink traversal: Won't follow symlinks outside scanned scope