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#

bash

clawhub run disk-sweeper scan --paths ~/

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

Features#

FeatureDescriptionSmart ScanningRecursive with streaming, parallel, auto-skip no-permission dirsMulti-dimension AnalysisBy type, directory, extension, age, top-N large filesDuplicate DetectionSHA-256 content hash (size-grouped → head hash → full hash)Chinese App CacheWeChat/DingTalk/QQ/Baidu/WPS/Netease music cache recognitionSystem Cache AnalysismacOS caches, Xcode, Docker, node_modules, npm/yarn, HomebrewSafety Grading🟢SAFE / 🟡CLEANABLE / 🟠CAUTION / 🔴PROTECTED with rationaleCleanup ModesPreview (default), Interactive, Auto-Safe, CustomUndo SupportMoves 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#

bash

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#

bash

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#

bash

clawhub run disk-sweeper clean --mode preview

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

bash

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

✅ Removed 127 files, freed 5.8 GB

Prompt 4: Cache Analysis#

bash

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#

bash

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

First-Success Path#

Goal: Valuable disk analysis within 5 seconds of installation.

text

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#

text

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#

CodeScenarioActionE001Invalid scan pathExit, list invalid pathsE002Out of memory (large scan)Process in batchesE003Hash calculation failureSkip file, continueE004File locked during cleanupSkip, log to reportE005Trash unavailable (headless)Fallback to direct delete (with confirm)E006Write permission deniedError + output to stdoutE007User 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