Swarm Janitor

Enterprise-grade OpenClaw skill for cleaning up orphaned subagent processes, archiving transcripts to SuperMemory, and freeing disk space without losing work. Features dry-run mode, configurable retention policies, and comprehensive safety checks.

Security Scan

The skill's stated purpose (clean orphaned subagent sessions and archive transcripts) is plausible, but the runtime instructions reference scripts and behaviors that are not included or declared (missing script files, undeclared environment usage, and filesystem paths), so you should verify the actual implementation before installing or running destructive operations.

Purpose & Capability

The skill's functionality (scanning ~/.openclaw/agents/... sessions, archiving to SuperMemory, and deleting orphaned sessions) is coherent with its name and description. However the SKILL.md repeatedly instructs running python3 scripts/swarm_janitor.py and other local scripts which are not present in the package (no scripts/ directory or code files included). That mismatch is a major coherence problem: the README assumes code that isn't bundled. The skill also references writing logs to /var/log and archiving destinations (local, s3, supermemory) that would require additional configuration/dependencies not declared.

Instruction Scope

The instructions instruct the agent/user to scan and remove files under ~/.openclaw/agents/main/sessions/, archive transcripts to SuperMemory, and optionally run cron jobs that write to /var/log. Those are powerful file-system operations and deletions. The SKILL.md also documents a SUPERMEMORY_API_KEY variable in config comments but the skill metadata does not declare or require that env var. Importantly, the instructions assume the existence of scripts that aren't provided—so the declared runtime behavior is unsupported by the packaged content. The instructions are specific enough to cause destructive actions (e.g., --clean --force) if the missing implementation were present.

Install Mechanism

There is no install spec and the skill is instruction-only, which reduces installation risk (nothing will be automatically downloaded or executed by the platform). However, because the SKILL.md tells users to copy files to ~/.openclaw and to run python scripts that aren't included, this points to incomplete packaging (the actual implementation may be expected to come from the referenced GitHub repo). You should not run the described commands until you obtain and inspect the real script sources from a trustworthy repository.

Credentials

Registry metadata declares no required environment variables, but references/config.yaml explicitly documents SUPERMEMORY_API_KEY and notes it is required for SuperMemory archival. The skill will need filesystem write access to ~/.openclaw paths and possibly /var/log for cron examples; those privileges are not declared. The omission of SUPERMEMORY_API_KEY and any S3 credentials (if S3 destination used) is a proportionality/information gap that could lead users to provide sensitive credentials without clear disclosure in metadata.

Persistence & Privilege

The skill does not request always: true and uses default autonomous-invocation settings (normal). It doesn't attempt to modify other skills or system-wide agent settings in the provided instructions. However, its recommended cron usage and writing to /var/log imply persistent scheduled invocation and possible need for elevated permissions; combine that operational persistence with the other concerns before enabling automated runs.

What to consider before installing

Do not run the shell/python commands shown in SKILL.md until you have the actual implementation to inspect. Specific steps to take before installing or enabling automation: - Verify origin: visit the claimed homepage (https://github.com/openclawdad/swarm-janitor) and confirm the repository contains the scripts (scripts/swarm_janitor.py) and matches the SKILL.md. - Inspect the code: review the actual Python scripts for exactly how they detect processes, determine 'orphaned' sessions, and delete files. Look for any network calls, unexpected endpoints, or credential exfiltration. - Confirm env and creds: SUPERMEMORY_API_KEY (and any S3 or other credentials) are referenced in config.yaml but not declared; understand where and how those values are used before supplying them. - Test safely: run any discovered script in a safe test environment or a copy of your sessions directory with dry-run enabled. Do not run --clean --force on production until you’ve confirmed behavior. - Check permissions: cron example writes to /var/log and may require root or elevated permissions; consider running under a restricted account and ensure proper backups exist. - If you cannot find the implementation repo or the scripts referenced, treat the package as incomplete/untrustworthy and do not enable automated deletions. Because the package is missing the executable scripts and has undeclared env and path implications, proceed cautiously; the inconsistencies could be benign (incomplete packaging) but could also hide risky operations if the missing code is later obtained from an untrusted source.

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/
   

2. Configure retention policy (optional):

   # Edit config to customize
   nano references/config.yaml
   

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