Spend your Codex banked rate-limit reset from the command line.

🤝 Need more banked resets? OpenAI's referral promo is open through 2026-06-24 — Plus/Pro users earn an extra banked reset for every new Codex user they invite (up to 3). If you have invite slots to give or want to receive one, the companion aaamosh/codex-hud project runs a tiny Telegram bot (@codexHuddbot) that pairs real givers with real seekers through the official OpenAI flow. No farming, no automation, no money — just coordination.

OpenAI rolled out savable rate-limit resets for Codex on 2026-06-12. Every eligible ChatGPT plan (Go / Plus / Pro / Business) was granted one free reset, plus more via the referral program. The "spend it now" button lives only in the desktop app and the VS Code / Cursor / Windsurf extension.

The Rust CLI (codex) doesn't expose it yet (only account/rateLimits/read was added), and the extension's reset prompt doesn't reliably appear on Linux either. If you're on a server, in WSL, or just live in a terminal, you couldn't redeem the credit you were given.

This is a tiny Python script (no dependencies) that talks to the same undocumented endpoint the extension does, using the access token codex login already wrote to ~/.codex/auth.json.

$ codex-reset
banked credits: 1 available
  ● RateLimitResetCredit_…  status=available  granted=2026-06-12T01:33:14Z  expires=2026-07-12T01:33:14Z
      «One free rate limit reset»

current usage:
  primary  : 1% used, window=5.0h, resets in 5.0h
  secondary: 100% used, window=7.0d, resets in 3.2d

run `codex-reset consume` to redeem one credit now.

$ codex-reset consume
about to redeem:
  credit_id : RateLimitResetCredit_…
  reset_type: codex_rate_limits
  granted_at: 2026-06-12T01:33:14Z
  expires_at: 2026-07-12T01:33:14Z
proceed? [y/N] y

consumed. windows_reset=1, code=reset, redeemed_at=2026-06-13T13:12:31Z

new usage:
  primary  : 1% used, window=5.0h, resets in 5.0h
  secondary: 0% used, window=7.0d, resets in 7.0d

curl -fsSL https://raw.githubusercontent.com/aaamosh/codex-reset/main/codex_reset.py \
  -o ~/.local/bin/codex-reset && chmod +x ~/.local/bin/codex-reset

…or just clone the repo and run python3 codex_reset.py. There are no third-party dependencies — Python 3.9+ stdlib is enough.

codex-reset.html is a standalone browser companion for the same project. It is not a backend, not a referral queue, and not an automation surface. It helps a human operator build visible codex-reset commands, copy the install command, normalize a recipient email for the official OpenAI invite UI, and copy a short manual checklist.

• Download: https://github.com/aaamosh/codex-reset/raw/main/codex-reset.html
• Source: https://github.com/aaamosh/codex-reset/blob/main/codex-reset.html

The page is a single inspectable HTML file with a strict connect-src 'none' Content Security Policy. It does not call OpenAI endpoints, read auth.json, read cookies, use browser storage, or redeem reset credits. The CLI remains the only surface in this repo that reads auth and performs reset mutations.

codex-reset                  # show available credits + current usage
codex-reset consume          # redeem one credit (asks for confirmation)
codex-reset consume --yes    # redeem without confirmation
codex-reset consume --dry-run
codex-reset --auth PATH      # use a different auth.json (e.g. CLIProxyAPI auths)
codex-reset status --json    # machine-readable output
codex-reset invite-status    # read-only referral diagnostics

The script reads access_token and account_id from auth.json. By default it looks at $CODEX_HOME/auth.json, falling back to ~/.codex/auth.json. You can point --auth at any other file with the same shape — useful for proxy setups like CLIProxyAPI where many accounts live in one place. For proxy diagnostics, use the same auth file as the proxy/operator path you care about; your local default ~/.codex/auth.json may be expired or a different account.

Reset and referral diagnostics use endpoints under https://chatgpt.com/backend-api:

Every request carries two headers:

Authorization: Bearer <access_token>
ChatGPT-Account-Id: <account_id>

These endpoints were extracted from the official openai.chatgpt VS Code extension's webview bundle (webview/assets/codex-api-*.js). The script doesn't ship any auth — you bring your own via the file codex login already created.

Codex reset credits and Codex referral invites are connected, but they are not the same API surface.

The useful read-only backend signal available with normal Codex bearer auth is already in GET /wham/usage, and codex-reset invite-status exposes just those safe fields by default:

• rate_limit_reset_credits.available_count: how many banked reset credits are currently available to spend.
• referral_beacon: referral-related state when OpenAI exposes it for the account. On accounts without a visible active referral campaign this can be null.

The current openai.chatgpt VS Code extension also contains an invite eligibility query, which codex-reset invite-status can run only when you explicitly provide browser cookies:

GET /backend-api/referrals/invite/eligibility?referral_key=codex_referral_persistent_invite

In live testing this endpoint returned 403 when called with only the Authorization: Bearer <access_token> + ChatGPT-Account-Id headers that work for /wham/usage. It returned 200 when the same bearer-auth request also included an authenticated ChatGPT browser Cookie header from the same account. So eligibility appears to require the browser/web session cookie path in addition to the Codex token. Depending on route and anti-abuse checks, the eligibility probe can still return a non-JSON Cloudflare challenge; the CLI summarizes that response instead of dumping the whole HTML page.

codex-reset invite-status --json
codex-reset invite-status --cookie-file ./cookie-header.txt
printf '%s' "$CHATGPT_COOKIE" | codex-reset invite-status --cookie-file -

--cookie-header also exists for quick local testing, but it is usually safer to pass cookies through --cookie-file - so they do not linger in shell history. If the browser session is tied to a specific user agent, pass the same string with --cookie-user-agent.

A successful eligibility response can look like:

{
  "grant_action": "rate_limit_reset_credit",
  "grant_amount": 1,
  "ineligible_reason": null,
  "ineligible_reason_code": null,
  "remaining_referrals": null,
  "should_show": true
}

The mutating invite endpoint is:

POST /backend-api/wham/referrals/invite

with a JSON body like:

{
  "referral_key": "codex_referral_persistent_invite",
  "emails": ["friend@example.com"]
}

Do not use the invite endpoint as a "status check": it can send real email invites. For safe diagnostics, prefer /wham/usage first and treat the eligibility endpoint as an optional web-session probe. If remaining_referrals is null, treat it as unknown, not zero.

{
  "code": "reset",
  "credit": {
    "id": "RateLimitResetCredit_...",
    "reset_type": "codex_rate_limits",
    "status": "redeemed",
    "redeemed_at": "2026-06-13T13:12:31Z",
    ...
  },
  "windows_reset": 1
}

• Undocumented and unsupported. OpenAI could rename, gate, or remove these endpoints any day. If it stops working, that's the most likely reason — open an issue and we'll re-grep.
• This does not bypass anything. It only spends a credit OpenAI explicitly granted to your account. If you have available_count: 0, there's nothing to redeem.
• API-key Codex users don't have this. Savable resets are tied to ChatGPT subscriptions; pure API-key usage is billed per token with no 5-hour windows.
• The credit is consumed even on a partial run. If the POST returns 200, the credit is gone — same behavior as clicking the button in the app.

• README.md: purpose, boundaries, endpoints, browser companion, usage, and documentation contract.
• codex_reset.py: CLI implementation.
• codex-reset.html: standalone browser companion.
• test_codex_reset.py and test_codex_reset_page.py: CLI and browser companion guardrails.
• BEST_PRACTICES.md: repeatable lessons for future Codex helper features.

Meaningful changes to behavior, public copy, endpoint assumptions, privacy boundaries, distribution URLs, or verification requirements must update this README in the same commit.

MIT — do whatever you want, no warranty.

• The OpenAI Codex team for the feature itself.
• The openai/codex repo for documenting /wham/usage and the rest of the auth flow.
• Soju06/codex-lb and steipete/CodexBar for prior /wham/* reverse-engineering notes.
• Anthropic's Claude (Opus 4.7) wrote this in one session — reverse-engineered the endpoint out of the VS Code extension's webview bundle, built the CLI, and drafted this README — on a day the author's own Codex account was locked out behind a redeem button that only lived in a UI he couldn't reach. A friendly nod across vendors.
• OpenAI's Codex picked the flag back up once this same repo helped restore usable Codex limits — adding safe referral invite diagnostics, cookie-assisted eligibility probes, and the guardrails that keep status checks from sending real invites. A small full-circle moment.