diskclean

AI-assisted disk space scanner and cleaner. Finds reclaimable space (node_modules, build caches, package caches, downloads, Docker, Xcode, logs) and intellig...

Security Scan

The skill is internally consistent with its stated purpose (disk scanning and cleaning), requests only python3, and its instructions and script align — but the script is truncated in the provided copy, and the tool allows destructive actions (rm -rf) so the user should review deletion behavior and run dry-runs first.

Purpose & Capability

Name and description match the provided assets: a bash script that scans $HOME for reclaimable items and uses a single python3 invocation to aggregate results. Declared requirement (python3) is reasonable for the python3-based aggregation step. Optional use of docker/go/homebrew is consistent with scanning those ecosystems.

Instruction Scope

SKILL.md stays within the disk-cleaning scope and includes explicit guardrails (never delete outside $HOME, dry-run required, don't delete .git, log deletions). However the instructions also tell the agent it may delete suggest-tier items with rm -rf after confirming paths under $HOME — that gives the agent the ability to run destructive shell commands. The provided diskclean.sh mostly emits scan items; the file is truncated in the submission so the actual deletion implementation and path-safety checks for the 'clean --confirm' subcommand could not be fully verified.

Install Mechanism

No install spec; instruction-only approach with a single bundled shell script is low-risk from an install standpoint. The script is intended to be copied into PATH or run in-place; there is no remote download or archive extraction declared.

Credentials

No credentials or unrelated environment variables are requested. The script reads HOME and writes to ~/.openclaw/diskclean for reports/logs, which is proportionate to its purpose.

Persistence & Privilege

always:false and default autonomous invocation is used. The skill stores its own scan reports and deletion log under the user's home (~/.openclaw/diskclean), which is expected behavior and does not modify other skills or system-wide settings.

Assessment

This skill appears to do what it says, but it can perform destructive deletions. Before installing or running: 1) Inspect the rest of diskclean.sh (the provided copy is truncated) to confirm how the 'clean --confirm' path-checks and delete operations are implemented (ensure they enforce $HOME and avoid shell globbing surprises). 2) Always run scans and 'clean --dry' first and review the generated JSON in ~/.openclaw/diskclean/scans/. 3) Back up important data before first use. 4) Be cautious about following SKILL.md guidance to run manual 'rm -rf' — prefer using the script's vetted delete command only after reviewing its code. 5) If you plan to symlink the script into /usr/local/bin, verify the file contents locally and avoid installing from untrusted sources.

Disk Cleaner - AI-Assisted Disk Space Management

You have access to diskclean.sh, a disk scanning and cleaning tool. Install it by copying diskclean.sh to a location on your PATH, or run it directly from this skill's directory.

Setup

# Make executable (if not already)
chmod +x diskclean.sh

# Optional: symlink to PATH
ln -sf "$(pwd)/diskclean.sh" /usr/local/bin/diskclean

Commands

# Full scan:returns JSON with all reclaimable items
./diskclean.sh scan

# Preview safe-tier auto-deletions (dry run, default)
./diskclean.sh clean --dry

# Execute safe-tier deletions
./diskclean.sh clean --confirm

# Show last scan results
./diskclean.sh report

# Show scan history over time
./diskclean.sh history

How to Use This Skill

When the user asks to scan or clean disk space:

1. Run a scan first: Always start with diskclean.sh scan
2. Summarize findings conversationally: Group items by category, show top offenders by size, report total reclaimable space
3. Explain the tiers clearly:
   • Safe tier (auto-deletable): Items matching a strict whitelist AND older than the age gate (7-14 days). These are regenerable artifacts like node_modules, __pycache__, build caches, package manager caches.
   • Suggest tier (needs approval): Everything else:Docker, downloads, venvs, trash. Present these as recommendations and ask the user what they want to do.
4. For safe-tier cleanup: Run diskclean.sh clean --dry first to show what would be deleted, then diskclean.sh clean --confirm only after user approves
5. For suggest-tier items: Present them individually or grouped by category. If the user approves specific items, delete them manually with rm -rf (after confirming the path is under $HOME)

Presentation Format

When presenting scan results, use this structure:

## Disk Scan Results

**Total reclaimable: X.X GB**
- Safe tier (auto-cleanable): X.X GB
- Needs your review: X.X GB

### Safe to Auto-Clean
| Category | Size | Age | Path |
|----------|------|-----|------|
| ... | ... | ... | ... |

### Needs Your Review
| Category | Size | Age | Path |
|----------|------|-----|------|
| ... | ... | ... | ... |

Safety Rules

• Never delete anything outside $HOME
• Never delete .git directories
• Never delete source code, documents, photos, or config files
• Never run clean --confirm without showing the user clean --dry output first
• Never delete suggest-tier items without explicit user approval per item or category
• Always verify a path exists before attempting deletion

How It Works

Tiered Safety Model

Safe tier = whitelisted category + age gate met. Auto-deletable with --confirm.

Suggest tier = everything else. Requires explicit user approval.

Categories Scanned

Category	What	Safe Tier	Age Gate
node_modules	Node.js dependencies (with package.json sibling)	Yes	7 days
python_cache	__pycache__, .pytest_cache	Yes	7 days
python_venv	.venv/, venv/	No	:
build_output	build/, dist/, .next/, target/	Yes	7 days
go_cache	Go module + build cache	Yes	14 days
homebrew_cache	Homebrew download cache	Yes	14 days
npm_yarn_pnpm_cache	npm/yarn/pnpm caches	Yes	14 days
pip_cache	pip download cache	Yes	14 days
xcode_derived	Xcode DerivedData	Yes	7 days
docker	Docker images, volumes, build cache	No	:
large_download	Files >100MB in Downloads	No	:
installer_archive	.dmg/.pkg/.zip/.iso in Downloads	No	:
logs	macOS logs (>50MB)	Yes	30 days
crash_reports	Diagnostic reports (>10MB)	Yes	30 days
ds_store	.DS_Store files	Yes	0 days
trash	~/.Trash contents	No	:

Guardrails

• Only scans under $HOME (plus /tmp user files)
• node_modules only deleted if a package.json exists alongside (proof it's regenerable)
• Dry-run is the default:must pass --confirm to actually delete
• Every deletion is logged to ~/.openclaw/diskclean/deletion-log.jsonl
• All scan reports stored in ~/.openclaw/diskclean/scans/

Data Storage

• Scan reports: ~/.openclaw/diskclean/scans/scan-YYYYMMDD-HHMMSS.json
• Latest scan: ~/.openclaw/diskclean/latest-scan.json
• Deletion log: ~/.openclaw/diskclean/deletion-log.jsonl