A private, local dashboard for understanding how your coding agents use tokens.
Tokenlog turns the usage metadata already recorded by Pi, Tau, Codex, and Claude Code into a single historical view. It collects normalized token events in SQLite and produces a polished, self-contained HTML dashboard—without uploading your data or reading conversation content.
Coding agents store usage in different formats and locations. That makes simple questions surprisingly difficult:
- How quickly is my usage growing?
- Which agents, providers, and models account for most tokens?
- How has my model or agent preference changed over time?
- Which projects receive the most agent activity?
- What did sessions actually cost when the client recorded a cost?
Tokenlog answers those questions from one local report. Daily history remains available in SQLite, so the dashboard becomes more useful over time instead of showing only the current session.
- One view across agents — Pi, Tau, Codex, and Claude Code normalized into comparable token buckets.
- Historical analysis — daily, weekly, monthly, cumulative, calendar, and weekday views.
- Provider-aware models — names such as
openai:gpt-5.5remain distinct from the same model served elsewhere. - Project visibility — compare activity using project directory basenames, never full paths in the report.
- Honest cost reporting — only costs explicitly recorded by session metadata; no guessed pricing.
- Portable output — a single interactive HTML file with no server, CDN, or runtime dependency.
- Local by design — no account, telemetry, network request, prompt storage, or response storage.
The report is organized into focused tabs:
| Tab | Included views |
|---|---|
| Overview | Agent summary, peak day, active streak, cache leverage, active-day average |
| Tokens | Daily volume, seven-day average, cumulative growth, switchable 2D/3D activity plot, token composition, weekday rhythm |
| Agents | Weekly/monthly agent mix, absolute volume, proportional share, overall share |
| Models | Provider-model ranking, per-agent filters, model adoption over time |
| Costs | Recorded-cost ranking and weekly/monthly history by model or agent |
| Projects | Project ranking, activity over time, agent-by-project matrix |
Requires Python 3.11 or newer. Tokenlog has no runtime dependencies outside the Python standard library.
git clone https://github.com/alejandro-ao/tokenlog.git
cd tokenlog
python3 -m venv .venv
. .venv/bin/activate
pip install -e .Collect local usage and generate the report:
tokenlog collect --timezone Europe/Berlin
tokenlog report --output token-usage-report.html
open token-usage-report.htmlUse any fixed IANA timezone appropriate for your daily boundaries. If omitted, Tokenlog detects the operating-system timezone.
After collecting new sessions, run the same two commands again. Collection transactionally rebuilds the snapshot, so deleted or rewritten sessions are reflected cleanly and a failed scan preserves the previous database.
# Rebuild the database from every supported agent
tokenlog collect --timezone Europe/Berlin
# Scan selected agents only
tokenlog collect --agents tau,codex --timezone Europe/Berlin
# Generate a dashboard from the existing database
tokenlog report --output token-usage-report.html
# Print daily aggregates
tokenlog daily
# Export normalized daily data
tokenlog export --format csv > usage.csv
tokenlog export --format json > usage.jsonUse another database with the global --db option:
tokenlog --db ./usage.sqlite3 collect --agents tau,codex
tokenlog --db ./usage.sqlite3 report --output report.htmlSet TOKENLOG_DATA_DIR to change the default data directory.
| Agent | Default session path |
|---|---|
| Pi | ~/.pi/agent/sessions/**/*.jsonl |
| Tau | ~/.tau/sessions/**/*.jsonl |
| Codex | ~/.codex/sessions/**/*.jsonl |
| Claude Code | ~/.claude/projects/**/*.jsonl and ~/.claude/transcripts/**/*.jsonl |
Session formats are not stable public APIs. The parsers currently account for Pi/Tau per-message usage, Claude streaming duplicates, and Codex cumulative token-count deltas.
Tokenlog reads only the fields needed for usage accounting. It does not store or embed:
- prompts or responses
- tool calls
- source code
- conversation content
- full project paths in the HTML report
The event database contains timestamps, local dates, agent/provider/model names, project basenames, token buckets, recorded costs, and source locations needed for rescanning and deduplication. Everything remains on disk. Tokenlog makes no network requests.
Default outputs:
- Database:
~/.local/share/tokenlog/usage.sqlite3 - Report:
./token-usage-report.html
Both local databases and generated reports are ignored by Git.
Reasoning tokens are retained as metadata but excluded from additive totals because Pi/Tau and Codex generally report reasoning as a subset of output. Codex cached input is subtracted from input and stored in the cache-read bucket. This avoids double counting and keeps agent totals comparable.
Costs appear only when a session format records them. Tokenlog does not fetch model prices or infer historical cost, so cost coverage may be narrower than token coverage.
python3 -m unittest discover -s tests -v
python3 -m compileall -q tokenlog tests