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

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, models and profile
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

Option 4 opens an online submenu without printing reports or making another network request:

1) Model availability
2) Main Codex limits
3) Additional limits
4) Daily usage
5) Credits and credit events
6) Profile statistics
7) Technical details
r) Refresh all online data
m) Main menu
q) Quit

Additional limits are extra quotas, not remaining messages. Choose a view to see its report. Technical details require a further endpoint selection, so only one endpoint’s metadata and filtered raw fields appear at a time. The existing top setting bounds model, additional-quota, daily, event and technical-field rows; use a smaller value in Settings for shorter reports.

The first view selection fetches one shared snapshot for the online submenu. Switching views or returning with b or Enter reuses that snapshot without network calls. Choose r to refresh all online data; the selected view stays open. Each screen shows the query time and flags unavailable endpoints. A failed refresh replaces old values with unavailable status; successful endpoints in that same refresh remain readable. Choose m to return directly to the main menu or q to quit. Leaving the online submenu discards its snapshot; reopening it starts with no data fetched.

The main menu’s quick summary always includes GPT-6 Astra, the number of additional limits when reported, and the last check time. This is a separate saved snapshot. Choose option 8 to refresh it; an unsuccessful refresh shows unavailable status instead of retaining old success values. The online submenu remains selectable without an Astra status or a valid Codex login, and local reports remain accessible.

Explanatory prose uses the terminal’s natural wrapping width. Paragraphs, lists and table formatting retain their line breaks. Direct online-usage, all and TXT exports still contain the complete report, including Technical details, without interactive prompts. JSON and CSV keep their existing structure.

Model Availability And Quotas

Available means OpenAI explicitly reports the model as available. Unavailable means it explicitly reports non-availability or a model block. Status unavailable means status data was absent, could not be interpreted or could not be fetched; it does not establish whether you have model access. Status unclear identifies conflicting availability and blocked-model signals. Refresh the report or check the model picker in Codex when status is unclear.

Astra appears first, followed by other models reported by the backend. --top limits model and additional-quota detail rows; Astra remains visible. Long values and narrow terminals use wrapped key–value records instead of truncated tables. All statuses remain readable without colour.

Quota periods come from the returned window duration, so a primary window can be weekly. If the duration is absent, the report uses Primary window or Secondary window. Remaining percentages are calculated only from valid consumption percentages for that same window. Unknown values appear as —, not zero or unlimited usage.

OpenAI does not report an exact remaining message count for Astra through the fields interpreted by this tool. Availability and quota percentages must not be read as a message count. Credit-based message estimates are not an Astra allowance.

The report shows alternative models only when the backend explicitly names a blocked model and alternatives. It does not switch models or confirm that a switch has occurred in Codex. A reserve quota’s model is shown separately and is not automatically an Astra alternative. Fields such as available_at and credits_would_enable remain under Technical details; the report does not infer a countdown or recommend buying credits from them.

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

Check local setup without network calls:

./codex_usage.py doctor
./codex_usage.py doctor --json

Inspect summary metadata from one local session JSONL file:

./codex_usage.py inspect-log ~/.codex/sessions/YYYY/MM/DD/session.jsonl
./codex_usage.py inspect-log ~/.codex/sessions/YYYY/MM/DD/session.jsonl --json

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