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

Commands

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):

| Category | Patterns | Safe? |

|----------|----------|-------|

| Temp downloads | `*.skill` in root | ✅ |

| Generated images | `*.png`, `*.jpg` in root | ✅ |

| macOS cruft | `.DS_Store` | ✅ |

| Logs | `*.log` | ✅ |

| Temp files | `*.tmp`, `*.bak`, `*~` | ✅ |

| Node modules | `node_modules/` in root | ✅ |

| Python venvs | `.venv*/`, `venv/` (except known) | ⚠️ |

| Duplicate repos | Same remote as projects/* | ⚠️ |

What's Protected

Never deleted, regardless of patterns:

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

1. **Always preview first** — Run without `--execute` to see what would be deleted

2. **Check the trash** — Files go to system trash, not permanent delete

3. **Exclude patterns** — Use `--exclude` for files that look like cruft but aren't

4. **Backup first** — For large cleanups, consider a backup

Examples

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