ContextClaw Plugin Usage

Manage and analyze OpenClaw sessions by checking usage, pruning old sessions, cleaning orphaned files, and viewing stats via CLI or dashboard.

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:

bash

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

Quick Start

Check if ContextClaw is installed and running:

bash

openclaw contextclaw status

Commands

Analyze Sessions

Get comprehensive analysis of all sessions:

bash

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):

bash

# 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:

bash

# Dry run
openclaw contextclaw clean-orphaned

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

Dashboard

Open the visual session management dashboard:

bash

openclaw contextclaw dashboard

This opens http://localhost:18797

Quick Stats

Show brief status and statistics:

bash

openclaw contextclaw status

Configuration

Reconfigure port or OpenClaw home:

bash

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:

bash

openclaw contextclaw analyze

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

User asks: "Clean up old sessions"

Response:

bash

# 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:

bash

openclaw contextclaw analyze

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

bash

openclaw contextclaw dashboard

User asks: "Remove orphaned session files"

Response:

bash

# 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:

bash

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

If port is in use:

bash

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

text

📊 Session Analysis

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

Prune Command

text

🧹 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