reset-guardian

Check your Codex banked reset credits and expiry dates from the terminal.

npx reset-guardian

Example output:

Reset Guardian

2 reset credits available
Next expiry: Jun 26, 2026, 10:00 UTC (in 2d 1h)

ID                            Status     Timing        Expires
RateLimitResetCredit_8f***0f  available  expires soon  Jun 26, 2026, 10:00 UTC
RateLimitResetCredit_8e***ef  available  later         Jul 20, 2026, 10:00 UTC

What It Shows

reset-guardian reports:

• how many Codex banked reset credits are available
• when the next reset credit expires
• each available reset credit returned by Codex, sorted by expiry

It does not report 5-hour or weekly usage. It does not redeem resets.

Requirements

• Node.js 20.19 or newer
• Codex signed in with ChatGPT subscription auth
• A readable Codex auth file at ~/.codex/auth.json or CODEX_HOME/auth.json

Codex can also store credentials in an OS credential store. This first version does not read keychain-backed credentials directly. If no auth file is available, sign in with Codex again or pass --auth-file.

Options

reset-guardian [options]

• --json prints machine-readable JSON.
• --all includes non-available reset-credit rows returned by Codex.
• --auth-file <path> reads a specific Codex auth.json.
• --codex-home <path> reads <path>/auth.json.
• --full-id shows full reset-credit ids in human output.
• --no-color disables ANSI color in human output.
• -h, --help prints help.

JSON Output

npx reset-guardian --json

{
  "availableCount": 2,
  "nextExpiry": "2026-06-26T10:00:00.000Z",
  "credits": [
    {
      "id": "credit-1",
      "status": "available",
      "urgency": "expires_soon",
      "expiresAt": "2026-06-26T10:00:00.000Z",
      "grantedAt": null
    }
  ]
}

Privacy

reset-guardian is read-only.

Human output masks long reset-credit ids by default so screenshots are easier to share. JSON output keeps full ids for scripts.

It reads your local Codex auth file and sends the saved bearer token only to:

GET https://chatgpt.com/backend-api/wham/rate-limit-reset-credits

It also sends the active account id in the ChatGPT-Account-Id header when the id is available from Codex auth. It does not store tokens, write to auth files, redeem resets, or send analytics.

See PRIVACY.md for the full privacy notes.

Limitations

• This is unofficial and not affiliated with OpenAI.
• The Codex endpoints it uses are internal and may change without notice.
• Usage and reset-credit fields may differ by Codex plan, account type, region, or app version.

Exit Codes

• 0: reset-credit data was fetched and printed.
• 1: auth, network, endpoint, or parsing failure.

For 401 or 403 responses, open Codex and sign in again.

Development

pnpm install
pnpm test
pnpm run typecheck
pnpm run build
pnpm run pack:check

Tests use injected fetch/auth dependencies and checked-in response shapes. They do not call internal Codex endpoints.

Acknowledgements

This tool was inspired by jordan-edai/codex-reset-watcher, which mapped the Codex reset-credit endpoint and auth shape this CLI uses.