Workspace Cleaner

Workspace Cleaner

Safe, automated cleanup for OpenClaw workspaces. Finds temp files, duplicates, and cruft while protecting important data.

Quick Start

# Preview what would be deleted (safe - no changes) python3 {{SKILL_DIR}}/scripts/cleanup.py # Actually clean up (uses trash for recovery) python3 {{SKILL_DIR}}/scripts/cleanup.py --execute # Custom workspace path python3 {{SKILL_DIR}}/scripts/cleanup.py --workspace /path/to/workspace

Features

Dry-run by default — Always previews before deleting Uses trash — Files go to system trash, recoverable Size-aware — Shows sizes, can filter by threshold Age filtering — Target files older than N days Customizable patterns — Edit config to match your workflow JSON output — Machine-readable for automation Safe defaults — Never touches .git, memory/, core configs

Preview (Default)

python3 {{SKILL_DIR}}/scripts/cleanup.py Shows what would be deleted with sizes. Makes no changes.

Execute Cleanup

python3 {{SKILL_DIR}}/scripts/cleanup.py --execute Moves items to trash. Recoverable via system trash.

Filter by Size

# Only show items larger than 100MB python3 {{SKILL_DIR}}/scripts/cleanup.py --min-size 100

Filter by Age

# Only show items older than 30 days python3 {{SKILL_DIR}}/scripts/cleanup.py --min-age 30

JSON Output

# For automation/parsing python3 {{SKILL_DIR}}/scripts/cleanup.py --json

Custom Config

# Use custom patterns file python3 {{SKILL_DIR}}/scripts/cleanup.py --config /path/to/patterns.json

What Gets Cleaned

Default patterns (customizable via config): CategoryPatternsSafe?Temp downloads*.skill in root✅Generated images*.png, *.jpg in root✅macOS cruft.DS_Store✅Logs*.log✅Temp files*.tmp, *.bak, *~✅Node modulesnode_modules/ in root✅Python venvs.venv*/, venv/ (except known)⚠️Duplicate reposSame remote as projects/*⚠️

What's Protected

Never deleted, regardless of patterns: .git/ directories memory/ directory MEMORY.md, SOUL.md, USER.md, AGENTS.md projects/ directory contents skills/ directory contents Files modified in last 24 hours (unless --include-recent)

Configuration

Edit {{SKILL_DIR}}/config/patterns.json to customize: { "temp_extensions": [".tmp", ".bak", ".log", ".skill"], "temp_patterns": ["*~", "#*#"], "image_extensions": [".png", ".jpg", ".jpeg", ".gif"], "protected_dirs": ["memory", "skills", "projects", ".git"], "protected_files": ["MEMORY.md", "SOUL.md", "USER.md", "AGENTS.md"], "known_venvs": [".venv-skill-scanner"] }

HEARTBEAT Integration

• Add to your HEARTBEAT.md for periodic cleanup checks:
• ## Weekly Cleanup Check
• Run workspace cleaner in preview mode
• Alert if >500MB of cruft found
• Auto-clean items >30 days old and <10MB

Safety Notes

Always preview first — Run without --execute to see what would be deleted Check the trash — Files go to system trash, not permanent delete Exclude patterns — Use --exclude for files that look like cruft but aren't Backup first — For large cleanups, consider a backup

Regular Maintenance

# Weekly cleanup of obvious cruft python3 {{SKILL_DIR}}/scripts/cleanup.py --min-age 7 --execute

Find Space Hogs

# What's taking up space? python3 {{SKILL_DIR}}/scripts/cleanup.py --min-size 50 --json | jq '.items | sort_by(.size_mb) | reverse'

Pre-Commit Cleanup

# Clean before committing python3 {{SKILL_DIR}}/scripts/cleanup.py --execute && git status

Requirements

Python 3.8+ trash command (macOS: brew install trash, Linux: trash-cli)