ContextClaw Plugin Usage

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