codex-stats

codex-stats is a local analytics tool for Codex usage.

It reads your local Codex state from ~/.codex and surfaces:

  • a browser dashboard with day, week, month, and all-time tabs
  • model and project breakdowns
  • recent session history
  • estimated token-based cost
  • anomaly-aware usage insights and recommendations
  • export for cross-device snapshots
  • shareable JPG cards and browser PDF export from the dashboard

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 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 between Day, Week, Month, and All Time
  • print the active tab to PDF
  • download shareable JPG cards for summary, cost, focus, and project share

How It Works

codex-stats does not proxy or intercept Codex API traffic.

It reads local Codex artifacts, including:

  • state_5.sqlite for session metadata
  • rollout JSONL files for request and token snapshots

Notes

  • Costs are estimates, not billing values.
  • Output depends on local Codex 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

Project links

Data verified by PyPI on Apr 25, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for peculiarvivek from gravatar.com peculiarvivek

Credits

Author: Vivek

GitHub Statistics

Data verified by PyPI on Apr 25, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.11

Provides Extra

dev

Tags

codex cli analytics sqlite usage

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

codex_stats-1.6.2.tar.gz (54.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

codex_stats-1.6.2-py3-none-any.whl (51.0 kB view details)

Uploaded Python 3

File details

Details for the file codex_stats-1.6.2.tar.gz.

File metadata

  • Download URL: codex_stats-1.6.2.tar.gz
  • Upload date:
  • Size: 54.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for codex_stats-1.6.2.tar.gz
Algorithm Hash digest
SHA256 e5527eb89dd3c938804f7829dc993b76bbac49a82d18b3e7162f07997558e738
MD5 c188d4970dd0ce0537ef641664b9eabf
BLAKE2b-256 7119d5e4eae4c8206f69646253b75c205c51048b9f7e91d4a7c22c979d0ad2ce

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_stats-1.6.2.tar.gz:

Publisher: publish.yml on vivek378521/codex-stats

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codex_stats-1.6.2-py3-none-any.whl.

File metadata

  • Download URL: codex_stats-1.6.2-py3-none-any.whl
  • Upload date:
  • Size: 51.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for codex_stats-1.6.2-py3-none-any.whl
Algorithm Hash digest
SHA256 a5156bb1c458f6489b6625198891ad078eccb4d26e81adf27d21a13cd047b7fa
MD5 b71cfe230728c65576c9dab5b2117b2d
BLAKE2b-256 348fba9da8963c3c22cb3315fe3c880da2d4e5289d812caca7e8e8173efb7ac7

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_stats-1.6.2-py3-none-any.whl:

Publisher: publish.yml on vivek378521/codex-stats

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.6.2 This release

2 files

1.6.1

2 files

1.6.0

2 files

1.5.9

2 files

1.5.8

2 files

1.5.6

2 files

1.5.5

2 files

1.5.4

2 files

1.5.3

2 files

1.5.1

2 files

1.5.0

2 files

1.4.3

2 files

1.4.2

2 files

1.4.1

2 files

1.3.0

2 files

1.1.0

2 files

1.0.1

2 files

1.0.0

2 files

0.3.0

2 files

0.2.0

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page