Metadata-Version: 2.4
Name: codex-stats
Version: 1.0.1
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

`codex-stats` is a local analytics CLI for Codex usage.

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

- session summaries
- rolling usage totals across today, week, month, or the last `N` days
- model and project breakdowns
- project-specific drilldowns
- recent session history
- estimated token-based cost
- anomaly-aware usage insights and recommendations
- export and import for cross-device snapshots
- merged export snapshots for multi-device rollups
- shareable weekly and monthly reports

## Install

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

Or with `pip`:

```bash
python3 -m pip install codex-stats
```

## Command Reference

- `codex-stats`
  Show the default usage summary for today.
- `codex-stats today`
  Show today's usage summary explicitly.
- `codex-stats week`
  Show usage totals for the last 7 days.
- `codex-stats month`
  Show usage totals for the last 30 days.
- `codex-stats --days 14`
  Show a rolling summary for the last `N` days.
- `codex-stats session`
  Show the most recent session in detail.
- `codex-stats session --id <session_id>`
  Show one specific session by ID.
- `codex-stats models`
  Break usage down by model.
- `codex-stats project`
  Break usage down by project.
- `codex-stats project backend-api`
  Show a single project's summary across all available local data.
- `codex-stats project backend-api --days 30`
  Show a single project's summary for a rolling time window.
- `codex-stats daily`
  Show per-day usage with an ASCII trend graph.
- `codex-stats compare`
  Compare the last 7 days against the previous 7 days.
- `codex-stats compare today yesterday`
  Compare named time windows directly.
- `codex-stats history`
  Show recent session history.
- `codex-stats top`
  Show the largest sessions by token usage.
- `codex-stats top --project backend-api`
  Show the largest sessions for one project.
- `codex-stats costs`
  Show estimated cost totals and monthly projection.
- `codex-stats insights`
  Show anomaly-aware insights and recommended next steps.
- `codex-stats doctor`
  Validate local Codex data sources and config.
- `codex-stats doctor --strict`
  Return a non-zero exit code if any doctor check fails.
- `codex-stats init`
  Create a default config file under `~/.config/codex-stats/`.
- `codex-stats report weekly`
  Generate a weekly shareable report.
- `codex-stats report weekly --format markdown`
  Generate a weekly report in Markdown.
- `codex-stats report weekly --project backend-api`
  Generate a weekly report for one project.
- `codex-stats report weekly --format markdown --output weekly-report.md`
  Write a formatted report to a file.
- `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.
- `codex-stats import laptop.json desktop.json`
  Read one or more exported snapshots and summarize them.
- `codex-stats merge merged.json laptop.json desktop.json`
  Merge multiple exported snapshots into one deduplicated file.
- `codex-stats completions zsh`
  Print shell completion setup for your shell.
- `codex-stats --color always`
  Force ANSI color output.
- `codex-stats --json`
  Return machine-readable JSON output for supported commands.

## 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` and `import` let you move normalized snapshots between machines.
- `merge` lets you deduplicate and combine exported snapshots into one file.
- `export --since Nd` limits snapshots to a rolling window before sharing.
- `doctor --strict` is useful in scripts and CI because it returns a non-zero exit code on failed checks.
- `--color auto|always|never` controls ANSI styling.

## Pricing Config

Optional pricing config lives at `~/.config/codex-stats/config.toml`.

```toml
[pricing]
default_usd_per_1k_tokens = 0.01

[pricing.model_usd_per_1k_tokens]
gpt-5.4 = 0.02
gpt-5-mini = 0.005
```

To create the config file automatically:

```bash
codex-stats init
```

## Development

For local development from the repo:

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

Run without installing:

```bash
PYTHONPATH=src python3 -m codex_stats
```
