ContextClaw Plugin Usage

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

Security Scan

The instructions, required actions, and resource access described by the skill are consistent with its stated purpose of managing OpenClaw sessions; nothing requested appears unrelated or excessive.

Purpose & Capability

The name/description (session management, pruning, stats) matches the runtime instructions: analyze/prune/clean-orphaned/dashboard commands operating on OpenClaw sessions. Declared prerequisites (install the ContextClaw plugin) and referenced artifacts (sessions .jsonl files under ~/.openclaw/agents/main/sessions/) are coherent with the stated purpose.

Instruction Scope

SKILL.md only describes running the ContextClaw/OpenClaw CLI and opening a local dashboard, and explicitly documents which files it reads (~/.openclaw/.../sessions/). It also documents deletion operations (prune/clean-orphaned) and safety practices (dry-run, keep main/cron sessions). The instructions do not attempt to read unrelated system locations or exfiltrate data to remote endpoints.

Install Mechanism

The skill is instruction-only (no install spec), but requires the user to install an npm package globally (@rmruss2022/contextclaw) and register the plugin with openclaw. That is a reasonable requirement for this functionality, but installing arbitrary npm packages and running plugin installers executes third-party code on the host—users should verify the package and repo before installing. The lack of an automated install spec is not a security problem but is worth noting.

Credentials

No environment variables, credentials, or unrelated config paths are requested. The only filesystem access described is to the sessions directory under the user's OpenClaw home, which is appropriate for session management.

Persistence & Privilege

The skill does not request always:true or other elevated/intrusive privileges. It runs as an invoked plugin/CLI and advises dry-run/default protection for key session types (main/cron). Nothing in the instructions indicates it modifies other skills' configurations or requires permanent system-wide changes.

Assessment

This skill appears to do what it claims — manage and prune local OpenClaw session files. Before installing: (1) verify the referenced GitHub repo and npm package (@rmruss2022/contextclaw) look legitimate and review their source if possible, since npm global installs run third-party code; (2) always run analyze and the prune/clean-orphaned commands in dry-run mode first and back up your session directory if you are worried; (3) confirm the dashboard binds only to localhost and choose a different port if you have concerns about local network exposure.

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