Codex Usage

Codex Usage is a local command-line tool for people who want a clear view of their Codex reset credits, rate-limit windows, local usage 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, and what the OpenAI Admin API reports for organisation API usage and costs. You can export the same 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
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

In an interactive terminal, running the script without arguments opens the menu. In non-interactive use, the same entry point prints the all report.

./codex_usage.py

The menu starts with a quick summary, then offers the report choices and settings:

1) Show everything (resets + local + online)
2) Show reset credits only
3) Show local usage only (no network calls)
4) Show online usage/profile (GET only)
5) Show OpenAI API usage/costs (Admin key)
6) Export report
7) Settings (top=10, days=30, warn_days=7)
8) Refresh quick summary
q) Quit

Reports are written for normal reading first. Each major section starts with a short explanation, then shows the main values in labelled tables. Endpoint paths, response shapes and filtered raw fields are collected under Technical details near the bottom, so they are available when you need to verify where a value came from without dominating the main report.

You can also call each report directly. Every command supports -h and --help, and subcommands have their own help:

./codex_usage.py --help
./codex_usage.py local-usage --help
./codex_usage.py export --help

Show everything:

./codex_usage.py all

Show reset credits:

./codex_usage.py resets
./codex_usage.py resets --warn-days 14

Show local usage without network calls:

./codex_usage.py local-usage
./codex_usage.py local-usage --top 20 --days 60

Show read-only online usage/profile data:

./codex_usage.py online-usage
./codex_usage.py online-usage --top 3

Show optional OpenAI API organisation usage and costs:

export OPENAI_ADMIN_KEY="your-admin-key"
./codex_usage.py api-usage
./codex_usage.py api-usage --days 30 --top 10 --json
./codex_usage.py api-usage --group-by model --group-by project_id
./codex_usage.py api-usage --no-costs

api-usage calls the OpenAI Admin API, not the Codex or ChatGPT backend endpoints. It reads OPENAI_ADMIN_KEY from the environment only; there is no CLI flag for the key.

Set the Admin key only when you use api-usage. For a single run, prefix the command:

OPENAI_ADMIN_KEY="your-admin-key" ./codex_usage.py api-usage

That short form can be saved in shell history. To avoid putting the key on the command line, enter it into the current terminal session without echoing it, run the report, then remove it from the session:

printf "OPENAI_ADMIN_KEY: "
read -rs OPENAI_ADMIN_KEY
printf "\n"
export OPENAI_ADMIN_KEY
./codex_usage.py api-usage
unset OPENAI_ADMIN_KEY

For the current terminal session, the script only needs OPENAI_ADMIN_KEY to be exported before it starts. For regular use, load the value from your operating system's secret manager before you start the script, or export it from your shell profile, such as ~/.zshrc or ~/.bashrc. If you store it in a shell profile, treat that file as a credential. Do not put the key in this repository, screenshots, issues, commits, report exports, or <Codex home>/auth.json.

For copy/paste-friendly output, scripted checks or logs, disable terminal colour:

./codex_usage.py local-usage --top 1 --days 1 --no-colour
./codex_usage.py online-usage --top 3 --no-colour
./codex_usage.py resets --no-colour

For automation, print machine-readable JSON instead of prose and tables:

./codex_usage.py all --json
./codex_usage.py resets --json
./codex_usage.py local-usage --json
./codex_usage.py online-usage --json
./codex_usage.py api-usage --json

Screenshots

Command Reference

Shared display switches:

api-usage also supports: