Clawdscan

ClawdScan — Session Health Analyzer

🔍 Diagnose bloat, find zombies, reclaim disk space ClawdScan is a zero-dependency Python CLI that analyzes Clawdbot/OpenClaw session JSONL files to identify bloated sessions, zombies, stale files, and provides actionable cleanup recommendations.

Features

Session Health Analysis - Detect bloated sessions, high message counts, disk usage patterns Zombie Detection - Find sessions created but never used Stale Session Identification - Identify sessions inactive for configurable periods Tool Usage Analytics - Track which tools are being used and how frequently Model Usage Patterns - Monitor model switching and usage trends Disk Space Management - Breakdown of storage usage by agent and session Automatic Cleanup - Safe archive and deletion of problematic sessions Trend Tracking - Historical analysis of session health over time Heartbeat Integration - Automated monitoring and alerts

As Clawdbot Skill

clawdbot skill install clawdscan

Standalone

chmod +x clawdscan.py ./clawdscan.py --help

Quick Start

# Full health scan clawdscan scan # Top 10 largest sessions clawdscan top -n 10 # Clean up zombie sessions clawdscan clean --zombies --execute # View recent trends clawdscan history --days 7

scan - Full Health Scan

Comprehensive analysis of all Clawdbot sessions. clawdscan scan [--json output.json] # Examples clawdscan scan # Console output clawdscan scan --json report.json # Save as JSON Output includes: Total sessions and disk usage Bloated sessions (>1MB or >300 messages) Zombie sessions (created but unused) Stale sessions (inactive >7 days) Top sessions by size and messages Cleanup recommendations

top - Top Sessions

Show largest sessions by size or message count. clawdscan top [-n COUNT] [--sort {size|messages}] # Examples clawdscan top # Top 15 by size clawdscan top -n 20 # Top 20 by size clawdscan top --sort messages # Top 15 by message count clawdscan top -n 10 --sort messages # Top 10 by messages

inspect - Deep Session Analysis

Detailed analysis of a specific session. clawdscan inspect <session-id> # Example clawdscan inspect chhotu-agent-20240109 Shows: Session metadata (created, last activity, size) Message count breakdown by type Tool usage within the session Model usage patterns Large messages or potential issues

tools - Tool Usage Analytics

Aggregate statistics across all sessions. clawdscan tools Analysis includes: Most frequently used tools Tool usage by agent Average tool call frequency Tools that may be causing bloat

models - Model Usage Patterns

Track model usage and switching patterns. clawdscan models Shows: Model usage distribution Model switching frequency Cost implications (if token data available) Model preference by agent

disk - Storage Analysis

Breakdown of disk usage by agent and session type. clawdscan disk Provides: Total storage usage Usage by agent Largest directories Growth trends Cleanup potential

clean - Session Cleanup

Safe cleanup of problematic sessions with preview mode. clawdscan clean [--zombies] [--stale-days N] [--execute] # Examples clawdscan clean --zombies # Preview zombie cleanup clawdscan clean --zombies --execute # Execute zombie cleanup clawdscan clean --stale-days 28 # Preview cleanup of 28+ day old sessions clawdscan clean --stale-days 28 --execute # Execute stale cleanup Safety features: Preview mode by default (no destructive actions) Backup creation before deletion Confirmation prompts for large cleanups Detailed logs of all actions

history - Trend Analysis (New)

View session health trends over time. clawdscan history [--days N] # Examples clawdscan history # Last 30 days clawdscan history --days 7 # Last week clawdscan history --days 90 # Last 3 months Tracks: Session count over time Storage growth trends Bloat accumulation patterns Cleanup effectiveness

Environment Variables

CLAWDBOT_DIR - Override default Clawdbot directory NO_COLOR - Disable colored output

Thresholds (customizable in skill.json)

Bloat Size: 1 MB (sessions larger than this) Bloat Messages: 300 messages Stale Threshold: 7 days without activity Zombie Threshold: 48 hours created but unused

Heartbeat Integration

• ClawdScan can run automatically as part of Clawdbot's heartbeat system:
• ### In HEARTBEAT.md
• Check session health every 6 hours
• Alert if >5 bloated sessions found
• Alert if total usage >100MB
• Auto-cleanup zombies (if enabled)

Heartbeat Configuration

{ "heartbeat": { "enabled": true, "interval": "6h", "auto_cleanup": false, "alert_thresholds": { "bloated_sessions": 5, "total_size": "100MB" } } }

Scan Output

🔍 ClawdScan v0.1.0 — Clawdbot Session Health Analysis ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📊 Overview Total Sessions: 42 Total Size: 23.4 MB Agents: main(38), dj(4) ⚠️ Issues Found 🔥 Bloated: 3 sessions (>1MB or >300 msgs) 💀 Zombies: 2 sessions (created but unused) 🗓️ Stale: 7 sessions (inactive >7 days) 🔝 Top Sessions by Size 1. main-20240108-143022 4.2 MB (1,247 msgs) 2. main-20240107-091534 2.8 MB (892 msgs) 3. dj-20240105-220145 1.9 MB (734 msgs) 💡 Recommendations • Archive 2 zombie sessions → save 145 KB • Clean 7 stale sessions → save 3.2 MB • Consider shorter session lifetimes

History Output

📈 Session Health Trends (Last 30 Days) Week 1 (Jan 1-7): 12 sessions, 8.4 MB Week 2 (Jan 8-14): 18 sessions, 15.7 MB 📈 +87% growth Week 3 (Jan 15-21): 22 sessions, 19.3 MB 📈 +23% growth Week 4 (Jan 22-28): 28 sessions, 23.4 MB 📈 +21% growth 🔥 Bloat Trend: 0 → 1 → 2 → 3 sessions 💀 Zombie Trend: 1 → 1 → 2 → 2 sessions 💡 Growth Rate: +38% sessions/week, +44% storage/week

Common Issues

"No sessions found" Check --dir parameter points to correct Clawdbot directory Verify sessions exist in agents/*/sessions/ "Permission denied" Ensure read access to ~/.clawdbot directory Check file ownership and permissions "JSON parsing error" Some session files may be corrupted Use --verbose flag for detailed error info

Debug Mode

clawdscan scan --verbose --debug

Cron Job

# Daily health check at 2 AM 0 2 * * * /usr/local/bin/clawdscan scan --json /var/log/clawdscan.json

Shell Script

#!/bin/bash # Weekly cleanup script clawdscan clean --zombies --execute clawdscan clean --stale-days 14 --execute clawdscan scan --json /var/log/weekly-scan.json

Python Integration

import subprocess import json # Run scan and get JSON output result = subprocess.run(['clawdscan', 'scan', '--json', '/tmp/scan.json']) with open('/tmp/scan.json') as f: data = json.load(f) # Process results if data['bloated_sessions'] > 5: notify_admin("ClawdBot cleanup needed")

Adding New Commands

Add command handler to clawdscan.py Update skill.json tools array Add documentation to SKILL.md Update --help text

Contributing

Follow existing code style Add tests for new features Update documentation Ensure backward compatibility

License

MIT License - see LICENSE file for details.

Support

GitHub Issues: Report bugs or request features Documentation: This file and clawdscan.py --help