Metadata-Version: 2.4
Name: codex-stats
Version: 0.1.0
Summary: Local AI usage observability CLI for Codex sessions.
Author: Vivek
License: MIT
Project-URL: Homepage, https://github.com/vivek378521/codex-stats
Project-URL: Repository, https://github.com/vivek378521/codex-stats
Project-URL: Issues, https://github.com/vivek378521/codex-stats/issues
Keywords: codex,cli,analytics,sqlite,usage
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install .
```

After publish:

```bash
pipx install codex-stats
```

For local development:

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

## Usage

```bash
codex-stats
codex-stats today
codex-stats session
codex-stats session --id <session_id>
codex-stats --json
```

From the repo without installing:

```bash
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.
