🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί ContextClaw Plugin Usage
πŸ¦€ ClawHub

ContextClaw Plugin Usage

by @rmruss2022

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

Versionv1.0.0
Downloads1,170
#data#legal#productivity
TERMINAL
clawhub install contextclaw-usage

πŸ“– About This Skill

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

    ⚑ When to Use

    TriggerAction
    - 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

    πŸ’‘ Examples

    Check if ContextClaw is installed and running: 

    openclaw contextclaw status

    βš™οΈ Configuration

    Reconfigure port or OpenClaw home: 

    openclaw contextclaw setup

    πŸ“‹ Tips & 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