swarm-janitor
This skill cleans orphaned OpenClaw subagent sessions, archives transcripts to SuperMemory/local/S3, and frees disk space. It includes python3 scripts/swarm_janitor.py execution examples and references the SUPERMEMORY_API_KEY env var and supermemory/s3 archive destinations.
Swarm Janitor
Enterprise-grade cleanup tool for OpenClaw subagent management.
What It Does
Automatically identifies and cleans up orphaned subagent sessions while preserving important work through SuperMemory archival.
Core Functions
- Scan: Analyze session directory for orphaned/abandoned subagents
- Archive: Save transcripts to SuperMemory before deletion
- Clean: Safely remove orphaned sessions freeing disk space
- Report: Generate detailed cleanup reports
Safety First
This skill implements multiple safety layers:
- ✅ Never deletes active sessions — checks process status
- ✅ Dry-run mode — preview changes before executing
- ✅ SuperMemory backup — transcripts archived before deletion
- ✅ Configurable retention — customize age thresholds
- ✅ Detailed logging — full audit trail of all actions
Quick Start
# Preview what would be cleaned (dry-run)
python3 scripts/swarm_janitor.py --dry-run
# Archive old sessions to SuperMemory, then clean
python3 scripts/swarm_janitor.py --archive --clean
# Custom retention (7 days instead of default 3)
python3 scripts/swarm_janitor.py --retention-days 7 --clean
Installation
-
Copy this skill to your OpenClaw workspace:
cp -r skills/swarm-janitor ~/.openclaw/workspace/skills/ -
Configure retention policy (optional):
# Edit config to customize nano references/config.yaml -
Run first scan:
python3 ~/.openclaw/workspace/skills/swarm-janitor/scripts/swarm_janitor.py --dry-run
Usage Patterns
Daily Maintenance (Cron)
# Run daily at 3 AM, archive sessions older than 3 days
0 3 * * * python3 ~/.openclaw/workspace/skills/swarm-janitor/scripts/swarm_janitor.py --archive --clean --retention-days 3 >> /var/log/swarm-janitor.log 2>&1
Manual Cleanup
# See what would be deleted
python3 scripts/swarm_janitor.py --dry-run --verbose
# Archive transcripts to SuperMemory
python3 scripts/swarm_janitor.py --archive
# Clean without archiving (not recommended)
python3 scripts/swarm_janitor.py --clean --no-archive
# Full report
python3 scripts/swarm_janitor.py --report --output json
Emergency Cleanup
# Aggressive cleanup with 1-day retention
python3 scripts/swarm_janitor.py --clean --retention-days 1 --force
Configuration
See references/config.yaml for:
- Retention policies
- Archive destinations
- Safety thresholds
- Logging options
How It Works
- Discovery: Scans
~/.openclaw/agents/main/sessions/ - Analysis: Determines session age, activity status, size
- Classification: Identifies orphaned vs active sessions
- Archival: Saves transcripts to SuperMemory (if enabled)
- Cleanup: Safely removes orphaned session files
- Reporting: Generates summary of actions taken
Safety Mechanisms
| Check | Description |
|---|---|
| Process Check | Verifies no active process owns the session |
| Age Verification | Only processes sessions older than threshold |
| Size Limits | Warns on unusually large deletions |
| Dry-Run Default | Preview mode is default — explicit action required |
| Backup First | Archives to SuperMemory before any deletion |
Troubleshooting
Q: It says "permission denied" A: Ensure you have write access to the sessions directory
Q: Sessions not being detected A: Check the path in config.yaml matches your OpenClaw installation
Q: SuperMemory archive failing A: Verify SuperMemory skill is configured with valid API key
Enterprise Features
- Audit Logging: All actions logged with timestamps
- Configurable Policies: YAML-based configuration
- Metrics Export: JSON/CSV output for monitoring
- Dry-Run Mode: Test changes before applying
- Retention Policies: Age-based and count-based rules
License
MIT - Created by OpenClawdad (Redclay) for the OpenClaw community.