ContextClaw Plugin Usage

When to Use

Use this skill when the user asks about: - Session management or cleanup - Context usage or token consumption - Storage space used by sessions - Pruning old sessions - Cleaning up orphaned session files - Session analysis or statistics - Which sessions are taking up space - How many messages/tokens in sessions

Prerequisites

The ContextClaw plugin must be installed:

npm install -g @rmruss2022/contextclaw
openclaw plugins install @rmruss2022/contextclaw

Quick Start

Check if ContextClaw is installed and running:

openclaw contextclaw status

Commands

Analyze Sessions

Get comprehensive analysis of all sessions:

openclaw contextclaw analyze

This shows: - Total sessions, messages, tokens, storage size - Largest sessions (top 10) - Oldest sessions (top 10) - Orphaned sessions

Prune Old Sessions

Clean up sessions older than N days (default: 30):

# Dry run (preview only, safe)
openclaw contextclaw prune --days 30

# Live run (actually deletes)
openclaw contextclaw prune --days 30 --dryRun false

Safety features: - Dry run by default (previews before deleting) - Always keeps main agent sessions - Always keeps cron sessions - Shows confirmation before deleting

Clean Orphaned Sessions

Remove session files not referenced in sessions.json:

# Dry run
openclaw contextclaw clean-orphaned

# Live run
openclaw contextclaw clean-orphaned --dryRun false

Dashboard

Open the visual session management dashboard:

openclaw contextclaw dashboard

This opens http://localhost:18797

Quick Stats

Show brief status and statistics:

openclaw contextclaw status

Configuration

Reconfigure port or OpenClaw home:

openclaw contextclaw setup

Dashboard Features

The dashboard at http://localhost:18797 provides: - Session statistics - Total sessions, messages, tokens, storage - Multiple views - All, Largest, Oldest, Orphaned, Charts - Bar charts - Visual size distribution - Type breakdown - Sessions by agent type (main, cron, sub-agent) - Quick actions - Prune and clean from UI (preview only)

Example Usage

User asks: "How much storage are my sessions using?"

Response:

openclaw contextclaw analyze

Look at the "Total Size" metric in the summary table.

User asks: "Clean up old sessions"

Response:

# First preview what would be deleted
openclaw contextclaw prune --days 30

# If approved, run live:
openclaw contextclaw prune --days 30 --dryRun false

User asks: "Which sessions are taking up the most space?"

Response:

openclaw contextclaw analyze

Check the "Largest Sessions" table, or open the dashboard:

openclaw contextclaw dashboard

User asks: "Remove orphaned session files"

Response:

# Preview first
openclaw contextclaw clean-orphaned

# If user approves, run live:
openclaw contextclaw clean-orphaned --dryRun false

Session Types

ContextClaw categorizes sessions as: - main - Main agent session (protected from pruning) - cron - Cron job sessions (protected from pruning) - subagent - Spawned sub-agent sessions (can be pruned) - unknown - Unrecognized session types

Orphaned Sessions

A session is orphaned if: - .jsonl file exists in sessions directory - Session ID is NOT in sessions.json

Common causes: - Completed sub-agent removed from index - Manual file operations - Crashed sessions - Development/testing

Orphaned sessions are safe to delete.

Best Practices

1. Analyze regularly - Weekly or monthly: openclaw contextclaw analyze
2. Always dry-run first - Preview before deleting
3. Adjust age threshold - 30 days is default, adjust as needed
4. Review orphaned - Check before cleaning
5. Backup if worried - Though main/cron are protected

Troubleshooting

If dashboard won't load:

openclaw contextclaw status  # Check if running
openclaw contextclaw start   # Start if stopped

If port is in use:

openclaw contextclaw setup
# Choose a different port

Technical Details

• Port: 18797 (default, configurable)
• Analysis: Parses all .jsonl files in ~/.openclaw/agents/main/sessions/
• Token estimation: 1 token ≈ 4 characters (approximate)
• Storage: Read-only, no database

Example Output

Analyze Command

📊 Session Analysis

┌──────────────────┬────────┐
│ Metric           │ Value  │
├──────────────────┼────────┤
│ Total Sessions   │ 45     │
│ Total Messages   │ 3,842  │
│ Total Tokens     │ 156,234│
│ Total Size       │ 12.4 MB│
│ Orphaned         │ 8      │
└──────────────────┴────────┘

Prune Command

🧹 Session Pruning

⚠️  DRY RUN MODE - No files will be deleted

Sessions older than 30 days:
  ✓ Would delete: 12
  - Would keep: 33
  - Space freed: 4.2 MB

? Run prune in LIVE mode (actually delete files)? (y/N)

Repository

GitHub: https://github.com/rmruss2022/ContextClaw npm: @rmruss2022/contextclaw