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.
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
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/directoriesmemory/directoryMEMORY.md,SOUL.md,USER.md,AGENTS.mdprojects/directory contentsskills/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
--executeto see what would be deleted - Check the trash — Files go to system trash, not permanent delete
- Exclude patterns — Use
--excludefor files that look like cruft but aren't - 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+
trashcommand (macOS:brew install trash, Linux:trash-cli)
- Downloads
- 1.7kAll time
- Security audit
- Review
- Last updated
- 6mo ago
- Current version
- v1.0.0
- License
- MIT-0
