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

## Installation

### As Clawdbot Skill
```bash
clawdbot skill install clawdscan
```

### Standalone
```bash
chmod +x clawdscan.py
./clawdscan.py --help
```

## Quick Start

```bash
# 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
```

## Commands

### `scan` - Full Health Scan
Comprehensive analysis of all Clawdbot sessions.

```bash
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.

```bash
clawdscan top [-n COUNT] [--sort {size|messages}]

# Exam...

<p align="center">
  <img src="assets/logo.png" alt="clawdscan logo" width="200" />
</p>

<p align="center">[![ClawHub](https://img.shields.io/badge/ClawHub-clawdscan-teal)](https://clawhub.ai/skills/clawdscan)</p>
<p align="center">**Install via ClawHub:** `clawhub install clawdscan`</p>

# ClawdScan - Clawdbot Session Health Analyzer 🔍

A comprehensive diagnostic tool for Clawdbot sessions. Analyze JSONL session files to identify performance issues, bloated sessions, zombie processes, and get 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

## Quick Start

```bash
# Install as Clawdbot skill
clawdbot skill install clawdscan

# Or run standalone
chmod +x clawdscan.py
./clawdscan.py scan
```

## Example 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 s...