Usage Visualizer

Advanced usage statistics and high-fidelity visual reporting for OpenClaw. 100% local processing. Audit-verified privacy (No credentials stored).

Security Scan

The skill appears to do what it claims—locally parse OpenClaw/Clawdbot session logs and render local reports—without requesting unrelated credentials or unusual privileges, though there are a few minor inconsistencies to be aware of.

Purpose & Capability

Name/description match the code and runtime requirements: the scripts parse local OpenClaw/Clawdbot session JSONL files, compute token/cost metrics, persist to a local SQLite DB, and render PNG reports using a headless Chromium via html2image. Required binaries (python3, chromium) and the OPENCLAW_WORKSPACE env var are used by the code.

Instruction Scope

SKILL.md runtime instructions are narrowly scoped to syncing session logs, generating reports, and delivering images via the agent message tool. The scripts read filesystem session logs (under ~/.openclaw and ~/.clawdbot) and a local SQLite DB; they do not contain code that transmits data over the network or access unrelated system credentials.

Install Mechanism

This is an instruction-and-script skill with a pip install step (pip3 install -r requirements.txt). Installing will fetch dependencies from PyPI (network access during install). The runtime claims '100% local' and 'No External Calls', which is true at runtime, but the install step itself will contact PyPI. Also html2image or its dependencies can sometimes pull or require a local browser binary; the skill requires chromium to be present but some html-rendering libraries may attempt downloads if not found. This is expected for this functionality but worth noting.

Credentials

Only OPENCLAW_WORKSPACE is requested and is used as the workspace/storage path. No credentials or unrelated secrets are required. The code reads user session log files (which may contain metadata about sessions) but only extracts usage/token counts and model names in the shown logic; it does not request API keys or other external credentials.

Persistence & Privilege

The skill creates a local SQLite database and other report files under the workspace (default ~/.llm-cost-monitor or OPENCLAW_WORKSPACE). It does not request always:true and does not modify other skills' configurations. This level of persistence and file creation is appropriate for the described functionality.

Assessment

This skill is internally consistent with its stated purpose and appears to only read local OpenClaw/Clawdbot session logs, store aggregates in a local SQLite DB, and render images via a headless browser. Before installing, consider: 1) The install step invokes pip and will download packages from PyPI (network activity during install). 2) The rendering dependency (html2image) requires Chromium; ensure you trust/verify the Chromium binary and/or the system package source. 3) The skill reads files under ~/.openclaw and ~/.clawdbot—confirm you are comfortable with local session logs being parsed and stored in the skill's workspace. 4) The skill's package.json references a GitHub repo but the registry source is 'unknown'—if provenance matters, manually review the upstream repository for additional context. If any of those points are unacceptable, review the code locally (it is included) before running, or run it in a restricted environment.

Usage Visualizer is a high-fidelity analytics engine for OpenClaw that transforms raw session logs into professional, actionable visual reports.

🚀 Quick Start

# Generate today's visual report
python3 scripts/run_usage_report.py --mode image --period today

📈 Usage Guide

Visual Reports

The visualizer syncs logs first, then generates the report image.

• python3 scripts/run_usage_report.py --mode image --period today
• python3 scripts/run_usage_report.py --mode image --period week --json

Text Summaries

• python3 scripts/run_usage_report.py --mode text --period today --json

🛡 Delivery Protocol (MANDATORY FOR AGENTS)

1. Image Delivery: Extract image_path from JSON and send as attachment using message tool's filePath. NEVER send the local path as a string.
2. Verification: Verify the file exists and is a valid PNG before sending.
3. No Network: This skill is 100% local. It has zero network dependencies.

📄 License

MIT