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

1. Copy this skill to your OpenClaw workspace:

cp -r skills/swarm-janitor ~/.openclaw/workspace/skills/

1. Configure retention policy (optional):

# Edit config to customize
   nano references/config.yaml

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

1. Discovery: Scans ~/.openclaw/agents/main/sessions/
2. Analysis: Determines session age, activity status, size
3. Classification: Identifies orphaned vs active sessions
4. Archival: Saves transcripts to SuperMemory (if enabled)
5. Cleanup: Safely removes orphaned session files
6. 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.