Codex Usage

Local token usage reports and dashboard for Codex.

codex-usage scans your local Codex session logs, stores token usage in a SQLite database, and exposes simple CLI reports plus a local dashboard.

It is inspired by claude-usage, but targets Codex's local JSONL session format.

This is an unofficial community tool. It is not affiliated with OpenAI.

Features

• Scan local Codex session JSONL files from ~/.codex/sessions
• Track input, cached input, output, reasoning output, and total tokens
• Group usage by day, model, project, and thread
• Read thread metadata from ~/.codex/state_5.sqlite when available
• Store derived data in ~/.codex/usage.db
• Run everything locally with Python's standard library
• Avoid double-counting repeated token_count events by using positive deltas from Codex's cumulative thread totals

Requirements

• macOS or Linux
• Python 3.9+
• A local Codex installation that writes session files under ~/.codex

No third-party Python packages are required.

Installation

git clone https://github.com/Yves-alain/Codex-Usage.git
cd Codex-Usage

Usage

Build or update the local usage database:

python3 cli.py scan

Print reports:

python3 cli.py today
python3 cli.py week
python3 cli.py stats

Start the dashboard:

python3 cli.py dashboard

The dashboard runs locally at:

http://localhost:8080

Keep the dashboard bound to localhost unless you explicitly want to expose it on your local network.

For safety, non-loopback hosts are refused by default. If you intentionally want to bind the dashboard to your network, you must opt in:

CODEX_USAGE_ALLOW_NETWORK=1 HOST=0.0.0.0 python3 cli.py dashboard

How It Works

Codex writes local JSONL session files. These files can contain token_count events with cumulative token counters for the current thread.

codex-usage:

1. Reads JSONL files from ~/.codex/sessions
2. Extracts token_count events
3. Uses positive deltas between cumulative totals to avoid counting repeated events twice
4. Enriches threads with metadata from ~/.codex/state_5.sqlite when available
5. Writes derived reporting data to ~/.codex/usage.db

The generated database is disposable. You can delete it and run scan again.

Commands

Command	Description
python3 cli.py scan	Scan local Codex sessions and update ~/.codex/usage.db
python3 cli.py today	Print today's token usage
python3 cli.py week	Print the last 7 days
python3 cli.py stats	Print all-time usage by model and project
python3 cli.py dashboard	Scan and start the local dashboard

Privacy

This tool reads local Codex metadata and token counters. It does not send data to any external service.

Do not commit your real ~/.codex directory or generated SQLite databases. The included .gitignore excludes common local database/session paths.

By default, the generated database is written to ~/.codex/usage.db.

The dashboard is local-only by default. It serves data from your generated SQLite database to your browser on localhost; it does not publish that data to GitHub or any remote service.

Cost Estimates

Codex usage is often tied to subscription or product limits, not direct API billing. This project reports local token usage. Any future cost estimate should be treated as indicative only, not as an official bill.

Development

Run the tests:

python3 -m unittest discover -s tests -v

The tests use small anonymized fixtures and never need your real Codex data.

Status

Early MVP. Codex's local file format may change, so the parser is intentionally small and tested against fixture JSONL files.

License

MIT