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

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

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