codex-stats

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

Data Sources

Each source is detected automatically and skipped when no data is present:

Tool	Location	Notes
Codex	`~/.codex`	`state_5.sqlite` + rollout JSONL files
OpenCode	`~/.local/share/opencode/opencode.db`	recorded cost + tokens per session
Claude Code	`~/.claude/projects/*/.jsonl`	per-project transcripts
Hermes	`~/.hermes/state.db`	recorded cost + tokens per session

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)

Install

pipx install codex-stats

Or with pip:

python3 -m pip install codex-stats

Command Reference

codex-stats Generate a standalone dashboard HTML file and open it in the default browser.
codex-stats --output codex-stats-dashboard.html Write the dashboard HTML to a fixed path.
codex-stats --output codex-stats-dashboard.html --no-open Write the dashboard HTML without opening the browser.
codex-stats --source codex --source opencode Restrict the dashboard to the given tool scopes (repeat the flag to pick multiple).
codex-stats export codex-stats-export.json Export normalized local stats to JSON.
codex-stats export codex-stats-export.json --since 30d Export 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, and All Time inside the active tool
print the active tool and window to PDF
download shareable JPG cards for summary, cost, focus, and project share

How It Works

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.

Notes

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 Nd limits snapshots to a rolling window before sharing.

Roadmap

The current priority list lives in docs/roadmap.md.

Shareable Assets

The dashboard exports JPG cards with names like:

These sample assets were generated from the current renderer so the docs match what the dashboard actually downloads.

Development

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

Metadata

Release files for codex-stats 1.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for codex-stats 1.7.0
File	Size	Uploaded
codex_stats-1.7.0.tar.gz	64.3 kB	Sep 20, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for codex-stats 1.7.0
File	Interpreter	ABI	Platform	Reset
codex_stats-1.7.0-py3-none-any.whl 59.1 kB Sep 20, 2026	Python 3	none	any	Details

Total release size: 123.4 kB

Release files / codex_stats-1.7.0.tar.gz

Download URL	codex_stats-1.7.0.tar.gz
Size	64.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`d93324e0722c9b498917e146fa45c4ab5a5750d2e4f9f17adccbd9d8be4111f3`
BLAKE2b-256 checksum How to use checksums	`9b0cfb98108861c9f17d97fef152dc1378c146737c77c9388f5eddb4be2319bb`
Upload date	Sep 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/vivek378521/codex-stats
Publishing commit: github.com/vivek378521/codex-stats/tree/a7b2a361729c27c0a994e34e82b72c8de0024c13

Workflow

Publishing configuration: github.com/vivek378521/codex-stats/blob/a7b2a361729c27c0a994e34e82b72c8de0024c13/.github/workflows/publish.yml
Publishing logs: github.com/vivek378521/codex-stats/actions/runs/35498677215/attempts/1

Artifact

Subject: codex_stats-1.7.0.tar.gz
SHA-256 checksum: d93324e0722c9b498917e146fa45c4ab5a5750d2e4f9f17adccbd9d8be4111f3 Verifying attestations

Release files / codex_stats-1.7.0-py3-none-any.whl

Download URL	codex_stats-1.7.0-py3-none-any.whl
Size	59.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d43ac954b9e3183e7bb529049cf205e2bb899002f9379f51265920a4eff603e5`
BLAKE2b-256 checksum How to use checksums	`dae6be6be596bce71dcef3622f7770bdcd103ecc4f303b2ca267db8c11013250`
Upload date	Sep 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/vivek378521/codex-stats
Publishing commit: github.com/vivek378521/codex-stats/tree/a7b2a361729c27c0a994e34e82b72c8de0024c13

Workflow

Publishing configuration: github.com/vivek378521/codex-stats/blob/a7b2a361729c27c0a994e34e82b72c8de0024c13/.github/workflows/publish.yml
Publishing logs: github.com/vivek378521/codex-stats/actions/runs/35498677215/attempts/1

Artifact

Subject: codex_stats-1.7.0-py3-none-any.whl
SHA-256 checksum: d43ac954b9e3183e7bb529049cf205e2bb899002f9379f51265920a4eff603e5 Verifying attestations