Workspace Cleaner

Automates safe cleanup of OpenClaw workspaces by previewing and moving temp files, logs, duplicates, and cruft to the system trash with customizable filtering.

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

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:

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

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

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