← Back to Skills Marketplace
ContextClaw Plugin Usage
by
rmruss2022
· GitHub ↗
· v1.0.0
663
Downloads
0
Stars
0
Active Installs
1
Versions
Install in OpenClaw
/install contextclaw-usage
Description
Manage and analyze OpenClaw sessions by checking usage, pruning old sessions, cleaning orphaned files, and viewing stats via CLI or dashboard.
README (SKILL.md)
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:
.jsonlfile 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
- Analyze regularly - Weekly or monthly:
openclaw contextclaw analyze - Always dry-run first - Preview before deleting
- Adjust age threshold - 30 days is default, adjust as needed
- Review orphaned - Check before cleaning
- 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
.jsonlfiles 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
Usage Guidance
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.
Capability Analysis
Type: OpenClaw Skill
Name: contextclaw-usage
Version: 1.0.0
The skill instructs the agent to install an external npm package globally (`@rmruss2022/contextclaw`), which introduces a supply chain risk. Additionally, the skill provides commands with the capability to delete user session files, a high-risk operation, even though the `SKILL.md` instructions emphasize safety features like dry runs and user confirmation. There is no evidence of malicious intent such as data exfiltration, backdoor installation, or harmful prompt injection against the agent, but the inherent risky capabilities warrant a 'suspicious' classification.
Capability Assessment
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.
How to Use
- Make sure OpenClaw is installed (local or Docker)
- Run the install command in chat:
/install contextclaw-usage - After installation, invoke the skill by name or use
/contextclaw-usage - Provide required inputs per the skill's parameter spec and get structured output
Version History
v1.0.0
Initial release: Skill for using ContextClaw plugin
Metadata
Frequently Asked Questions
What is ContextClaw Plugin Usage?
Manage and analyze OpenClaw sessions by checking usage, pruning old sessions, cleaning orphaned files, and viewing stats via CLI or dashboard. It is an AI Agent Skill for Claude Code / OpenClaw, with 663 downloads so far.
How do I install ContextClaw Plugin Usage?
Run "/install contextclaw-usage" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.
Is ContextClaw Plugin Usage free?
Yes, ContextClaw Plugin Usage is completely free (open-source). You can download, install and use it at no cost.
Which platforms does ContextClaw Plugin Usage support?
ContextClaw Plugin Usage is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).
Who created ContextClaw Plugin Usage?
It is built and maintained by rmruss2022 (@rmruss2022); the current version is v1.0.0.
More Skills