agentCLAWHUBUnverified
Token Usage Tracker
Track, aggregate, and report OpenClaw token usage and costs across sessions.
OpenClaw
Rank
62
Safety
84
Downloads
1.5k
Updated
Oct 10, 2026
Version
2.5.1
Source
CLAWHUB
About
What it does, and when to use it.
Capability contract not published. No trust telemetry is available yet. 1.5K downloads reported by the source. Last updated 10/10/2026.
Avoid when
- Contract metadata is missing or unavailable for deterministic execution.
Risk flags: missing_or_unavailable_contract, trust_data_unavailable, schema_references_missing
Public facts
Every fact links back to the source it came from.
- Vendor
- Clawhubvendor · observed Oct 10, 2026
- Protocol compatibility
- OpenClawcompatibility · observed Oct 10, 2026
- Adoption signal
- 1.5K downloadsadoption · observed Oct 10, 2026
- Latest release
- 2.5.1release · observed Sep 18, 2026
- Handshake status
- UNKNOWNsecurity
Install and run
Setup complexity: low.
clawhub skill install s17dfmfy79et7b7hb5944pm7qd8a031j:token-usage- Install using `clawhub skill install s17dfmfy79et7b7hb5944pm7qd8a031j:token-usage` in an isolated environment before connecting it to live workloads.
- No published capability contract is available yet, so validate auth and request/response behavior manually.
- Review the upstream CLAWHUB listing at https://clawhub.ai/space-cadet/token-usage before using production credentials.
Contract: missing
curl -s "https://www.xpersona.co/api/v1/agents/clawhub-space-cadet-token-usage/snapshot"
Documentation
CLAWHUB
147,440 characters of source documentation, loaded on request.
Extracted files
5 files captured from the source.
SKILL.md
--- name: token-usage description: "Track, aggregate, and report OpenClaw token usage and costs across sessions." homepage: https://github.com/space-cadet/openclaw-tools/tree/main/skills/token-usage license: MIT version: "2.5.1" --- # Token Usage Tracker Parse OpenClaw and Codex session files to extract token usage, aggregate by date/model/session, and generate provider-aware cost reports. Works across OpenClaw storage eras — pre-9.x JSONL, 9.x SQLite, and transitional mixed storage. ## When to Use - User asks "how many tokens did I use today/this week" - User wants to know session costs or model breakdown - Budget monitoring and anomaly detection - Before/after optimization comparisons ## Workflow 1. **Locate sessions** — Find `.jsonl` files in OpenClaw agent sessions and nested Codex rollout sessions 2. **Parse usage** — Extract OpenClaw message usage or Codex `token_count` per-turn usage 3. **Aggregate** — Group by date, model, session ID 4. **Report** — Output summaries, trends, cost estimates ## Commands ### Time Period Selection | Flag | Description | Example | |------|-------------|---------| | `--today` | Current calendar day (local timezone) | `--today` | | `--yesterday` | Previous calendar day (local timezone) | `--yesterday` | | `--week` | Last 7 calendar days | `--week` | | `--days N` | Last N calendar days | `--days 3` | | `--hours N` | Rolling window: last N hours | `--hours 24` | | `--since TIME` | Start time (ISO, date, or relative) | `--since 24h`, `--since 2d`, `--since "2026-07-20T09:00:00"` | | `--until TIME` | End time (ISO, date, or relative) | `--until 1h` | | `--all` | All time | `--all` | **Relative time shorthand:** `1h` = 1 hour ago, `2d` = 2 days ago, `30m` = 30 minutes ago. ### Report by Model (with costs) ```bash # Past 24 hours, model breakdown with cost estimates python3 ~/.openclaw/skills/token-usage/scripts/parse.py --hours 24 --by-model --costs # Today so far python3 ~/.openclaw/skills/token-usage/scripts/parse.py --today --by-model --costs # Yesterday python3 ~/.openclaw/skills/token-usage/scripts/parse.py --yesterday --by-model --costs # Since a specific time python3 ~/.openclaw/skills/token-usage/scripts/parse.py --since "2026-07-20T09:00:00" --by-model --costs # Last 2 hours python3 ~/.openclaw/skills/token-usage/scripts/parse.py --since 2h --by-model --costs ``` ### Report by Cron Job (daily breakdown per job) ```bash python3 ~/.openclaw/skills/token-usage/scripts/parse.py --week --by-cron ``` ### All-time summary by model ```bash python3 ~/.openclaw/skills/token-usage/scripts/parse.py --all --by-model ``` ### Export to JSON for external dashboards ```bash python3 ~/.openclaw/skills/token-usage/scripts/parse.py --week --json > /tmp/token-report.json ``` ### Additional Output Options | Flag | Description | |------|-------------| | `--cache` | Include cache read/write columns in report | | `--session-detail` | Show per-session breakdown with models used | | `--json` | Output machine-readab
README.md
# Token Usage Tracker Parse OpenClaw and Codex session files to extract token usage, aggregate by date/model/session type, and generate cost reports across providers. Works across OpenClaw storage eras — pre-9.x JSONL, 9.x SQLite, and transitional mixed storage. ## When to Use - User asks "how many tokens did I use today/this week" - Budget monitoring and anomaly detection - Before/after optimization comparisons - Cron job: daily token report to Telegram ## Version-Aware Storage Detection The parser detects the installed OpenClaw version and storage backend automatically: ``` OpenClaw version : 2026.9.4 Storage backend : mixed (jsonl=5581, sqlite=1, zst_archives=22) ⚠️ Mixed storage: SQLite (9.x live) + loose JSONL files detected. ``` | OpenClaw Version | Storage | Behavior | |------------------|---------|----------| | pre-9.x (≤2026.6.x) | JSONL only | Reads `.jsonl` / `.jsonl.gz`; warns if SQLite DB found | | 9.x (≥2026.9.x) | SQLite primary | Reads `transcript_events`; merges with any JSONL | | transitional | mixed | Reads both; warns so you know to consolidate | | unknown | auto-detect | Reads whatever is present; warns | Version is detected by scanning all NVM node trees for `openclaw/package.json` and picking the newest — never shells out to `openclaw --version` (which can block on a live gateway lock). ## Architecture ``` scripts/ parse.py — Direct parser (primary; auto-detects version + storage) common.py — Session discovery, parsing, model normalization, cost estimation ingest.py — Incremental ingestion into SQLite (usage.db) report.py — Report generation from SQLite pricing.json — Model pricing table (user-editable) registry.json — Model metadata: availability, provider, context windows ``` `parse.py` is the primary tool. `ingest.py` + `report.py` remain available for advanced SQL querying and long-term retention. ## Data Sources | Source | Pattern | Classification | |--------|---------|----------------| | 9.x live transcripts | `openclaw-agent.sqlite → transcript_events` | `user` or `cron:<name>` | | Interactive sessions | `*.jsonl`, `*.jsonl.gz` | `user` or `cron:<name>` | | Zstd-compressed archives | `*.jsonl.deleted.*.zst` | `user` or `cron:<name>` | | Codex app-server rollouts | `codex-home/sessions/**/*.jsonl` | `background:codex` | ## Key Behaviors - **9.x SQLite backend** (T16): Live session transcripts moved into `openclaw-agent.sqlite`. The parser reads `transcript_events.event_json` via a snapshot-to-`/tmp` pattern (the live DB is in OpenClaw's protected state directory). macOS requires plain `sqlite3.connect()` — URI read-only mode (`file:...?mode=ro`) fails on temp files. - **Timestamp normalization** (T16): SQLite stores UTC timestamps with `Z` suffix; `--since` / `--until` boundaries are local IST. `_normalise_ts()` strips `Z` so string comparison works across both formats. - **Mtime pre-filter** (T16): `find_sessions(since=...)` only opens files modified within the time window.
_meta.json
{
"ownerId": "kn7655yrj27ngj2xpjkvhjm8kx8a1k4j",
"slug": "token-usage",
"version": "2.5.1",
"publishedAt": 1789752923119
}scripts/pricing.json
{
"kimi/k2.6": {
"input": 0.9,
"output": 3.75,
"cache_read": 0.15,
"cache_write": null,
"source": "moonshot-direct",
"updated": "2026-08-21T10:38:28.959886",
"openrouter_input": 0.95,
"openrouter_output": 4.0
},
"kimi/k2.7": {
"input": 0.9,
"output": 3.75,
"cache_read": 0.15,
"cache_write": null,
"source": "moonshot-direct",
"updated": "2026-08-21T10:38:28.959890"
},
"kimi/k2.7-code": {
"input": 0.9,
"output": 3.75,
"cache_read": 0.18,
"cache_write": null,
"source": "moonshot-direct",
"updated": "2026-08-21T10:38:28.959893",
"openrouter_input": 0.67,
"openrouter_output": 3.4
},
"kimi/k3": {
"input": 2.78,
"output": 13.89,
"cache_read": 0.28,
"cache_write": null,
"source": "moonshot-direct",
"updated": "2026-08-21T10:38:28.959895",
"openrouter_input": 3.0,
"openrouter_output": 15.0
},
"anthropic/claude-sonnet-4-5": {
"input": 3.0,
"output": 15.0,
"cache_read": 0.3,
"cache_write": 3.75,
"source": "fallback",
"updated": "2026-08-21T10:38:28.959900"
},
"stealth/ox-alpha": {
"input": 0.0,
"output": 0.0,
"cache_read": null,
"cache_write": null,
"source": "openrouter",
"updated": "2026-08-21T10:38:28.957371"
},
"tencent/hy-mt2-1.8b": {
"input": 0.044,
"output": 0.177,
"cache_read": null,
"cache_write": null,
"source": "openrouter",
"updated": "2026-08-21T10:38:28.957466"
},
"tencent/hy-mt2-30b-a3b": {
"input": 0.074,
"output": 0.295,
"cache_read": null,
"cache_write": null,
"source": "openrouter",
"updated": "2026-08-21T10:38:28.957471"
},
"~z-ai/glm-latest": {
"input": 1.4,
"output": 4.4,
"cache_read": null,
"cache_write": null,
"source": "openrouter",
"updated": "2026-08-21T10:38:28.957476"
},
"z-ai/glm-5.3": {
"input": 1.4,
"output": 4.4,
"cache_read": null,
"cache_write": null,
"source": "openrouter",
"updated": "2026-08-21T10:38:28.957480"
},
"qwen/qwen3.8-27b": {
"input": 0.45,
"output": 3.2,
"cache_read": null,
"cache_write": null,
"source": "openrouter",
"updated": "2026-08-21T10:38:28.957486"
},
"dots-studio/dots-3-note-preview:free": {
"input": 0.0,
"output": 0.0,
"cache_read": null,
"cache_write": null,
"source": "openrouter",
"updated": "2026-08-21T10:38:28.957490"
},
"google/gemini-3.7-flash": {
"input": 0.375,
"output": 1.875,
"cache_read": null,
"cache_write": null,
"source": "openrouter",
"updated": "2026-08-21T10:38:28.957495"
},
"google/gemini-3.7-flash:batch": {
"input": 0.1875,
"output": 0.9375,
"cache_read": null,
"cache_write": null,
"source": "openrouter",
"updated": "2026-08-21T10:38:28.957501"
},
"bytedance-seed/seed-2-1-turbo": {
"input": 0.5,
"output": 2.5,
"cache_read": null,
"cache_write": null,
scripts/registry.json
{
"updated": "2026-07-23T10:25:36.469018",
"models": {
"kimi/k2.6": {
"pricing": {
"input_per_million": 0.9,
"output_per_million": 3.75,
"cache_read_per_million": 0.15,
"cache_write_per_million": null
},
"alternative_pricing": {
"openrouter": {
"input_per_million": 0.684,
"output_per_million": 3.42
}
},
"availability": "available",
"provider": "kimi",
"last_pricing_update": "2026-07-23T10:25:36.462346",
"pricing_source": "moonshot-direct"
},
"kimi/k2.7": {
"pricing": {
"input_per_million": 0.9,
"output_per_million": 3.75,
"cache_read_per_million": 0.15,
"cache_write_per_million": null
},
"alternative_pricing": {},
"availability": "available",
"provider": "kimi",
"last_pricing_update": "2026-07-23T10:25:36.462352",
"pricing_source": "moonshot-direct"
},
"kimi/k2.7-code": {
"pricing": {
"input_per_million": 0.9,
"output_per_million": 3.75,
"cache_read_per_million": 0.18,
"cache_write_per_million": null
},
"alternative_pricing": {
"openrouter": {
"input_per_million": 0.82,
"output_per_million": 3.75
}
},
"availability": "available",
"provider": "kimi",
"last_pricing_update": "2026-07-23T10:25:36.462356",
"pricing_source": "moonshot-direct"
},
"kimi/k3": {
"pricing": {
"input_per_million": 2.78,
"output_per_million": 13.89,
"cache_read_per_million": 0.28,
"cache_write_per_million": null
},
"alternative_pricing": {
"openrouter": {
"input_per_million": 3.0,
"output_per_million": 15.0
}
},
"availability": "available",
"provider": "kimi",
"last_pricing_update": "2026-07-23T10:25:36.462360",
"pricing_source": "moonshot-direct"
},
"anthropic/claude-sonnet-4-5": {
"pricing": {
"input_per_million": 3.0,
"output_per_million": 15.0,
"cache_read_per_million": 0.3,
"cache_write_per_million": 3.75
},
"alternative_pricing": {},
"availability": "available",
"provider": "anthropic",
"last_pricing_update": "2026-07-23T10:25:36.462363",
"pricing_source": "fallback"
},
"openai/gpt-4o": {
"pricing": {
"input_per_million": 2.5,
"output_per_million": 10.0,
"cache_read_per_million": 1.25,
"cache_write_per_million": 0
},
"alternative_pricing": {
"openrouter": {
"input_per_million": 2.5,
"output_per_million": 10.0
}
},
"availability": "available",
"provider": "openai",
"last_pricing_update": "2026-07-23T10:25:36.462366",
"pricing_source": "fallback"
},
"openai/gpt-4o-mini": {
"pricing": {
"input_per_millioGithub ReposUpdated 17h agoRank 70
AionUi
Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!
MCPOPENCLAW
Github ReposUpdated 6mo agoRank 70
activepieces
AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents
OPENCLAW
Github ReposUpdated 6mo agoRank 70
cherry-studio
AI productivity studio with smart chat, autonomous agents, and 300+ assistants.
MCPOPENCLAW
Github ReposUpdated 7mo agoRank 70
CopilotKit
The Frontend for Agents & Generative UI. React + Angular
OPENCLAW
Machine-readable data
The same record, as JSON, for agents and crawlers.
{
"facts": [
{
"factKey": "vendor",
"category": "vendor",
"label": "Vendor",
"value": "Clawhub",
"href": "https://clawhub.ai/space-cadet/skills/token-usage",
"sourceUrl": "https://clawhub.ai/space-cadet/skills/token-usage",
"sourceType": "profile",
"confidence": "medium",
"observedAt": "2026-10-10T11:23:47.203Z",
"isPublic": true
},
{
"factKey": "protocols",
"category": "compatibility",
"label": "Protocol compatibility",
"value": "OpenClaw",
"href": "https://www.xpersona.co/api/v1/agents/clawhub-space-cadet-token-usage/contract",
"sourceUrl": "https://www.xpersona.co/api/v1/agents/clawhub-space-cadet-token-usage/contract",
"sourceType": "contract",
"confidence": "medium",
"observedAt": "2026-10-10T11:23:47.203Z",
"isPublic": true
},
{
"factKey": "traction",
"category": "adoption",
"label": "Adoption signal",
"value": "1.5K downloads",
"href": "https://clawhub.ai/space-cadet/token-usage",
"sourceUrl": "https://clawhub.ai/space-cadet/token-usage",
"sourceType": "profile",
"confidence": "medium",
"observedAt": "2026-10-10T11:23:47.203Z",
"isPublic": true
},
{
"factKey": "latest_release",
"category": "release",
"label": "Latest release",
"value": "2.5.1",
"href": "https://clawhub.ai/space-cadet/token-usage",
"sourceUrl": "https://clawhub.ai/space-cadet/token-usage",
"sourceType": "release",
"confidence": "medium",
"observedAt": "2026-09-18T17:35:23.119Z",
"isPublic": true
},
{
"factKey": "handshake_status",
"category": "security",
"label": "Handshake status",
"value": "UNKNOWN",
"href": "https://www.xpersona.co/api/v1/agents/clawhub-space-cadet-token-usage/trust",
"sourceUrl": "https://www.xpersona.co/api/v1/agents/clawhub-space-cadet-token-usage/trust",
"sourceType": "trust",
"confidence": "medium",
"observedAt": null,
"isPublic": true
}
],
"events": [
{
"eventType": "release",
"title": "Release 2.5.1",
"description": "Fix T16 regressions: IST timezone conversion restored, removed CLI flags restored, per-model cron pricing, version-gate tuple compare, SQLite double-count guard, real cache costs. Includes v2.5.0 9.x SQLite backend.",
"href": "https://clawhub.ai/space-cadet/token-usage",
"sourceUrl": "https://clawhub.ai/space-cadet/token-usage",
"sourceType": "release",
"confidence": "medium",
"observedAt": "2026-09-18T17:35:23.119Z",
"isPublic": true
}
]
}Record generated Oct 10, 2026.