Disk Sweeper

SKILL.md

---
name: disk-sweeper
display_name: Disk Cleaner
description: Intelligent disk space analysis and cleanup tool with safety grading, duplicate detection, and Chinese app cache recognition.
author: harry
version: 1.0.0
license: MIT
type: skill
tags:
  - disk-cleanup
  - disk-analysis
  - system-tool
  - utility
model: deepseek
created_at: 2026-06-14
---

# 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

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

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