Codex Usage

Codex Usage is a local command-line tool for people who want a clear view of their Codex reset credits, model availability, rate-limit windows, local usage metadata, local setup health, one-file session metadata, read-only online usage/profile data and optional OpenAI API organisation usage.

The project is intentionally small: one Python file, no package install and no third-party Python dependencies. The core Codex reports do not need an OpenAI API key. The optional api-usage report uses OPENAI_ADMIN_KEY when you choose that report.

Use it to see how many reset credits are available, when they expire in your local timezone, whether visible rate-limit windows are close to their limit, what local Codex metadata says about sessions, models, days and token totals, whether the local setup is ready for each report, what one session JSONL file contains at a metadata level, and what the OpenAI Admin API reports for organisation API usage and costs. You can export the main reports as TXT, JSON or CSV files beside the script.

This is not an official OpenAI or Codex tool. It does not redeem credits, buy credits, change your Codex or ChatGPT account, change Codex settings, or upload local transcripts. The Codex online data comes from undocumented ChatGPT/Codex backend endpoints, so treat it as useful operational information rather than a contractual billing statement. The optional api-usage report uses documented OpenAI Admin API endpoints for API organisation usage and costs; it is not ChatGPT or Codex subscription billing.

Requirements

• Python 3.10 or newer.
• macOS, Linux or Windows.
• Local Codex state under your Codex home directory for local-usage.
• A Codex login at auth.json inside your Codex home directory and network access for resets, online-usage, all and menu quick summaries.
• OPENAI_ADMIN_KEY with suitable organisation permissions for the optional api-usage report.

No third-party Python packages are required. By default, Codex Usage reads Codex data from Path.home() / ".codex". Set CODEX_HOME to use a different Codex home directory.

The source layout is deliberately small:

.gitattributes
codex_usage.py
test_codex_usage.py
img/
LICENCE
README.md

Install And Run

Download or clone this repository, then open a terminal in the folder that contains codex_usage.py.

Make the script executable and start it:

chmod +x codex_usage.py
./codex_usage.py

If you prefer not to mark the file executable, run it through Python:

python3 codex_usage.py

On Windows, open PowerShell in the folder that contains codex_usage.py, then run the script with the Python launcher:

py -3 .\codex_usage.py
py -3 .\codex_usage.py local-usage

You can check the script syntax before running it:

python3 -m py_compile ./codex_usage.py

PowerShell equivalent:

py -3 -m py_compile .\codex_usage.py

The syntax check only verifies that Python can parse the script. It does not contact Codex and does not read your account data.

If your Codex data is not in the default user-profile .codex directory, set CODEX_HOME before running the script:

CODEX_HOME="/path/to/codex-home" ./codex_usage.py local-usage

PowerShell equivalent:

$env:CODEX_HOME = "C:\Users\you\.codex"
py -3 .\codex_usage.py local-usage

Use The Reports