codex-stats is a local analytics tool for coding agents.
It reads local session data from every coding assistant installed on the machine and surfaces:
- a browser dashboard with an Overview tab for every tool combined, plus one tab per tool (Codex, OpenCode, Claude Code, Hermes)
- day, week, month, and all-time windows inside every tab
- model and project breakdowns
- recent session history
- estimated token-based cost (or each tool's own recorded cost when available)
- per-tool cost overrides and a stacked per-tool token trend on the Overview
- anomaly-aware usage insights and recommendations
- export for cross-device snapshots
- shareable JPG cards and browser PDF export from the dashboard
Each source is detected automatically and skipped when no data is present:
Use these environment variables to point at non-default locations (also used for test isolation):
-
CODEX_HOME(Codex),CODEX_STATS_OPENCODE_HOME(OpenCode),CODEX_STATS_CLAUDE_PROJECTS_DIR(Claude),CODEX_STATS_HERMES_HOME(Hermes)
pipx install codex-statsOr with pip:
python3 -m pip install codex-stats-
codex-statsGenerate a standalone dashboard HTML file and open it in the default browser.
-
codex-stats --output codex-stats-dashboard.htmlWrite the dashboard HTML to a fixed path.
-
codex-stats --output codex-stats-dashboard.html --no-openWrite the dashboard HTML without opening the browser.
-
codex-stats --source codex --source opencodeRestrict the dashboard to the given tool scopes (repeat the flag to pick multiple).
-
codex-stats export codex-stats-export.jsonExport normalized local stats to JSON.
-
codex-stats export codex-stats-export.json --since 30dExport only a rolling window of recent sessions.
Inside the dashboard, use the action bar to:
- switch tools with the Overview / Codex / OpenCode / Claude Code / Hermes tab row
- switch between Day,Week,Month, andAll Timeinside the active tool
- print the active tool and window to PDF
- download shareable JPG cards for summary, cost, focus, and project share
codex-stats does not proxy or intercept API traffic. It reads local artifacts:
Codex state_5.sqlite and rollout files, the OpenCode database, Claude Code project
transcripts, and the Hermes database, then normalizes everything into one session model.
-
Costs are estimates by default. When a tool records its own cost (OpenCode, Hermes), that value wins for the session. Per-tool rates can be set in ~/.config/codex-stats/config.toml:[pricing.source_usd_per_1k_tokens] codex = 0.01 opencode = 0.01 claude = 0.015 hermes = 0.008
-
Output depends on local file formats remaining compatible.
-
export --since Ndlimits snapshots to a rolling window before sharing.
The current priority list lives in docs/roadmap.md.
The dashboard exports JPG cards with names like:
- docs/assets/codex-stats-week-summary-card.jpg
- docs/assets/codex-stats-week-cost-card.jpg
- docs/assets/codex-stats-week-focus-card.jpg
- docs/assets/codex-stats-week-projects-card.jpg
These sample assets were generated from the current renderer so the docs match what the dashboard actually downloads.
For local development from the repo:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip setuptools
python -m pip install -e .Run without installing:
PYTHONPATH=src python3 -m codex_stats