https://github.com/escoffier-labs/usage-tracker
Token usage and cost analytics for OpenClaw sessions with multi-model breakdown
https://github.com/escoffier-labs/usage-tracker
ai-tools analytics api-usage cost-tracking llm monitoring
Last synced: about 1 month ago
JSON representation
Token usage and cost analytics for OpenClaw sessions with multi-model breakdown
- Host: GitHub
- URL: https://github.com/escoffier-labs/usage-tracker
- Owner: escoffier-labs
- License: mit
- Created: 2026-05-23T19:52:36.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-10T12:49:51.000Z (about 1 month ago)
- Last Synced: 2026-06-10T13:20:49.207Z (about 1 month ago)
- Topics: ai-tools, analytics, api-usage, cost-tracking, llm, monitoring
- Language: HTML
- Size: 744 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
Usage Tracker
OpenClaw + Claude Code session cost analytics for API spend, OAuth subscription value, and model usage.
Machine-wide AI session cost analytics. Single static page plus a tiny Python exporter that reads OpenClaw session transcripts, Claude Code project transcripts, and Codex CLI rollouts, and writes a flat `data/usage.json` the page renders.
Splits real **API spend** from **OAuth subscription burn** (what your Codex Pro / Claude Max calls would have cost at API rates) so you can see what each session actually cost and whether your subscriptions are paying off.
## Quick start
```bash
git clone https://github.com/escoffier-labs/usage-tracker.git
cd usage-tracker
# Build data/usage.json from your OpenClaw + Claude Code sessions
python3 bin/export_usage.py --since 30d
# Serve the page
python3 -m http.server 5200
```
Open http://localhost:5200.
For an always-fresh dataset, install the opt-in user-systemd timer (5 minute refresh):
```bash
cp bin/usage-tracker-export.service ~/.config/systemd/user/
cp bin/usage-tracker-export.timer ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now usage-tracker-export.timer
```
(Edit the service file's `ExecStart` path to point at wherever you cloned this repo.)
## Billing classification
Each call is classified as `oauth` (subscription burn, billed flat) or `api` (real per-token spend):
- Calls served by a subscription backend are detected from the API id (`openai-chatgpt-responses`, `cli`, `google-gemini-cli`) regardless of provider.
- Providers in the OAuth set (`openai-codex`, `claude-cli`, `acpx`, `google-gemini-cli` by default) are `oauth`; everything else is `api`.
- Override per export with `--oauth-providers`. Example: if grok runs on a SuperGrok subscription via device-code OAuth, use `--oauth-providers openai-codex,claude-cli,acpx,google-gemini-cli,xai`.
- Claude Code records are always `oauth` (Claude Code transcripts carry token counts but no cost; the exporter estimates the API-equivalent cost from a built-in pricing table). Disable the source with `--no-claude-code` or point elsewhere with `--claude-projects PATH`.
- Codex CLI rollouts (`~/.codex/sessions`) are always `oauth` (ChatGPT subscription); per-call tokens come from `token_count` events and cost is estimated from the same pricing table. Disable with `--no-codex` or point elsewhere with `--codex-sessions PATH`.
- Models missing from the pricing table export with `costUsd: null`; the page counts them as "calls missing cost data" instead of silently pricing them at zero.
## Drag-and-drop fallback
If `data/usage.json` is missing (e.g., you opened the page on a different machine), drop one or more OpenClaw `*.trajectory.jsonl` files or a previously-exported `usage.json` onto the page. Records are parsed client-side and cached in localStorage.
## What it shows
- **API spend** versus **OAuth value extracted** for the period
- Per-agent breakdown (main, coder, codex-builder, claude-code, codex-cli, ...)
- Sessions table grouped by session id, with per-call drill-down
- Per-model bar chart, stacked by billing type
- Daily cost time series, stacked by billing type
- Subscription ROI: monthly subscription costs versus OAuth value extracted
- Five design variants to choose from
## Architecture
- `bin/export_usage.py` walks `~/.openclaw/agents/*/sessions/*.jsonl` (plain session transcripts; one per session), `~/.claude/projects/*/*.jsonl` (Claude Code), and `~/.codex/sessions/**/*.jsonl` (Codex CLI rollouts), extracts per-call usage, writes a flat array to `data/usage.json`. OpenClaw's `*.trajectory.jsonl` files are NOT used: they only exist for a fraction of runs and undercount usage by an order of magnitude.
- `index.html` fetches `data/usage.json` on load (drag-and-drop fallback), normalizes records into renderer-friendly aggregates, displays.
- No backend. localStorage caches the last load and your subscription settings.
## Development
```bash
python3 -m pytest tests/ # exporter tests
python3 -m http.server 5200 # page
```
## License
MIT