codex-stats 0.2.0

Local AI usage observability CLI for Codex sessions.

codex-stats

Local AI usage observability CLI for Codex sessions.

What it does

codex-stats reads local Codex state from ~/.codex and shows:

• session totals from state_5.sqlite
• request counts from rollout JSONL files
• model and project breakdown from local session metadata
• estimated cost from a local pricing table

Install

pip install .

After publish:

pipx install codex-stats

For local development:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip setuptools
python -m pip install -e .

Usage

codex-stats
codex-stats today
codex-stats week
codex-stats month
codex-stats session
codex-stats models
codex-stats project
codex-stats session --id <session_id>
codex-stats --json

From the repo without installing:

PYTHONPATH=src python3 -m codex_stats

Notes

• This tool does not intercept Codex API traffic.
• Costs are estimates, not authoritative billing values.
• The current MVP relies on local file formats that may evolve with Codex CLI versions.

Release

Recommended publish flow:

1. Create the GitHub repository vivek378521/codex-stats.
2. Create a PyPI project named codex-stats.
3. Configure PyPI Trusted Publishing for the GitHub repository.
4. Push a version tag and publish a GitHub release.
5. The release workflow will build and upload the package to PyPI.