diskclean

AI-assisted disk space scanner and cleaner. Like DaisyDisk, but open-source and AI-powered.

Scans your home directory for reclaimable space: node_modules, build caches, package manager caches, old downloads, Docker, Xcode DerivedData, Python venvs, and more. Intelligently suggests or auto-cleans safe items with strict guardrails.

Install

As a Claude Code / OpenClaw skill

npx skills add 0xj7r/diskclean

Manual

curl -o diskclean.sh https://raw.githubusercontent.com/0xj7r/diskclean/main/diskclean.sh
chmod +x diskclean.sh

Usage

# Scan your home directory
./diskclean.sh scan

# Preview what would be cleaned (dry run)
./diskclean.sh clean --dry

# Actually clean safe-tier items
./diskclean.sh clean --confirm

# View last scan
./diskclean.sh report

# View history
./diskclean.sh history

How It Works

Two-Tier Safety Model

Safe tier: Items on a strict whitelist that are older than an age gate. These are regenerable artifacts that can be auto-deleted:

Category	Age Gate	Example
node_modules (with package.json)	7 days	~/project/node_modules
__pycache__, .pytest_cache	7 days	~/project/__pycache__
Build outputs (build/, dist/, .next/)	7 days	~/project/.next
npm/yarn/pnpm cache	14 days	~/.npm/_cacache
pip cache	14 days	~/Library/Caches/pip
Go module + build cache	14 days	~/go/pkg/mod/cache
Homebrew cache	14 days	~/Library/Caches/Homebrew
Xcode DerivedData	7 days	~/Library/Developer/Xcode/DerivedData
macOS logs (>50MB)	30 days	~/Library/Logs

Suggest tier: Everything else. Shown in the report but never auto-deleted:

• Python virtual environments
• Docker images/volumes
• Large downloads (>100MB)
• Installer archives (.dmg, .pkg, .zip)
• Trash

Guardrails

• Only operates under $HOME
• Never touches .git directories, source code, documents, or photos
• node_modules only deleted if package.json exists alongside
• Dry-run is the default; --confirm required to delete
• All deletions logged to ~/.openclaw/diskclean/deletion-log.jsonl

Output Format

Scan results are JSON, making them easy to parse programmatically or feed to an AI agent:

{
  "scan_date": "2026-03-28T12:43:12Z",
  "total_reclaimable_mb": 160563,
  "safe_tier_mb": 119315,
  "suggest_tier_mb": 41248,
  "items": [
    {
      "path": "~/.npm/_cacache",
      "category": "npm_yarn_pnpm_cache",
      "size_mb": 15790,
      "age_days": 192,
      "tier": "safe"
    }
  ]
}

Requirements

• macOS or Linux
• python3 (for JSON report assembly)
• Standard POSIX tools (find, du, stat, rm)

License

MIT