Codex Reset Tracker

Unofficial Python CLI for checking OpenAI Codex / ChatGPT Codex usage reset credits, rate limit reset times, and current usage status.

Codex sometimes grants reset credits that quietly expire if you don't use them. Codex Reset Tracker reads your existing Codex login, calls the same backend the Codex client uses, and prints a clean terminal report, so you always know how much of your 5h and weekly limits is left, when each window resets, and which credit expires first. It uses only the Python standard library.

Example

Codex Reset Tracker
Plan: Pro
Available resets: 3
Usage credits: 0

Usage remaining:
- 5h: 89% remaining, resets 11:54 AM
- Weekly: 78% remaining, resets Jul 2 7:41 AM
- GPT-5.3-Codex-Spark 5h: 100% remaining, resets 3:26 PM
- GPT-5.3-Codex-Spark Weekly: 98% remaining, resets Jul 1 8:43 AM

Available reset credits:
1. Full reset (Weekly + 5 hr) [available]
   granted: 2026-06-11 21:22:48 EDT
   expires: 2026-07-11 21:22:48 EDT
   time left: 14.5 days
2. Full reset (Weekly + 5 hr) [available]
   granted: 2026-06-17 20:30:44 EDT
   expires: 2026-07-17 20:30:44 EDT
   time left: 20.4 days
3. Full reset (Weekly + 5 hr) [available]
   granted: 2026-06-26 19:38:35 EDT
   expires: 2026-07-26 19:38:35 EDT
   time left: 29.4 days

Quick start

You need Codex installed and logged in. Then:

git clone https://github.com/AyalX/codex-reset-tracker.git
cd codex-reset-tracker
python codex_reset_tracker.py

That's it. No pip install, no dependencies. Prefer a real command on your PATH? See Install.

Features

• Remaining 5h and weekly usage at a glance, with the exact reset time for each window
• Every available reset credit listed with its grant date, expiry date, and days left
• Credits sorted by earliest expiry, with a flag on any that are expiring soon
• Redeemed and expired credits hidden by default, shown as compact counts
• Your Codex plan and usage credit balance, when the API returns them
• Reads your Codex login automatically from ~/.codex/auth.json
• Text or JSON output, so you can pipe it into scripts or a status bar
• Runs on macOS, Linux, and Windows
• No dependencies beyond the Python 3.9+ standard library
• Read-only: it never changes your account, and your token only goes to the Codex backend

Install

Run it straight from the clone (shown above), or install it as a codex-reset-tracker command:

python -m pip install -e .
codex-reset-tracker

Usage

# Default report, in your local timezone
codex-reset-tracker

# Use UTC, or any IANA timezone
codex-reset-tracker --timezone UTC
codex-reset-tracker --timezone America/Vancouver

# Machine-readable JSON
codex-reset-tracker --json

Options

--auth-json PATH       Path to Codex auth.json
--credits-json PATH    Use a saved /wham/rate-limit-reset-credits response
--usage-json PATH      Use a saved /wham/usage response
--timezone NAME        local, UTC, or an IANA timezone
--warn-days DAYS       Mark available credits expiring within this many days (default: 3)
--timeout SECONDS      Network timeout (default: 30)
--json                 Print normalized JSON

Reading the report

Line	Meaning
Plan	Your Codex plan, when /wham/usage returns plan_type
Available resets	Number of reset credits Codex says you have
Usage credits	Credit balance, shown only when the API returns one (separate from reset credits)
Usage remaining	Current rate limit windows: label (5h, Weekly), percent remaining (100 - used_percent), and reset time

The reset list shows your available credits, earliest expiry first. Redeemed or expired credits are hidden so old history doesn't clutter the report. If any exist, the tracker prints compact counts (e.g. Hidden credits: redeemed 1).

Authentication

The tool reads the same local login file Codex already created:

macOS / Linux:  ~/.codex/auth.json
Windows:        C:\Users\you\.codex\auth.json

If your auth file lives elsewhere:

codex-reset-tracker --auth-json /path/to/auth.json

You can also pass a token directly via environment variables:

# macOS / Linux
CODEX_BEARER_TOKEN="..." codex-reset-tracker

# Windows PowerShell
$env:CODEX_BEARER_TOKEN = "..."; codex-reset-tracker

If your account needs an account id, add CODEX_ACCOUNT_ID="...".

How it works

The tracker calls the two read-only Codex backend endpoints the desktop client uses:

GET /wham/rate-limit-reset-credits
GET /wham/usage

It never calls the reset-consume endpoint, so it can't change your account or spend a credit.

Privacy: your token is read locally and sent only to the Codex backend in those two requests. The tool stores nothing, decodes no account identity, and never prints raw API payloads.

Troubleshooting

Message	Fix
Not logged in	Open Codex and log in, then rerun. Or set CODEX_BEARER_TOKEN.
HTTP 401 / HTTP 403	Your local auth expired. Sign in to Codex again and rerun.
No credits listed	The API returned zero reset credits for your account. That's normal if you have none.

Development

python -m py_compile codex_reset_tracker.py

No dependencies, no build step. Issues and pull requests welcome.

Disclaimer

This is an unofficial, community-built tool. It is not affiliated with, endorsed by, or supported by OpenAI. Codex backend endpoints are undocumented and may change at any time.

License

MIT © AyalX

---

If you find it useful, a ⭐ helps others come across it.