codex-reset-watcher-linux

A Linux command-line tool for checking Codex rate-limit windows and banked reset credits — a port of the read-only logic from jordan-edai/codex-reset-watcher (a macOS menu-bar app) to a Bun/TypeScript CLI that runs anywhere.

It reads your existing local Codex login from ~/.codex/auth.json, calls the same internal Codex endpoints the app uses, and prints:

• current 5-hour usage remaining
• current weekly usage remaining
• active account label from the current Codex login
• banked reset credits and expiry dates
• expiry urgency warnings as reset credits get closer to lapsing
• a reset-use nudge based on remaining 5h/weekly capacity, reset timing, reset-credit expiry, and reset credits in the bank

Read-only. It does not redeem resets, reset usage, modify your account, or send analytics.

Requirements

• Bun installed
• A Codex login saved at ~/.codex/auth.json (created by signing in with the Codex CLI or Desktop)
• No API key required

Install

git clone https://github.com/thewindmom/codex-reset-watcher-linux.git
cd codex-reset-watcher-linux
bun run src/cli.ts

Usage

$ bun run src/cli.ts

Sample output (synthetic — not real account data)

Codex Reset Watcher  account: demo@example.com   plan: Pro
Last checked 2:14 PM

Usage
  5-hour limit       50% remaining                    resets in 5m  (2:19 PM)
  Weekly limit       60% remaining                    resets in 2d 7h  (Wednesday)

Banked reset credits (2 available)
  #1  Full reset (Weekly + 5 hr)    Available      expires Feb 15
  #2  Full reset (Weekly + 5 hr)    Expires soon   expires Feb 18

Nudge: Hold that reset
       Plenty of weekly runway and the next refresh is close. Let the reset stay banked.
       60% weekly left

Options

Flag	Description
--json	Emit raw JSON from both endpoints instead of formatted text
--watch	Re-check every 5 minutes until interrupted
--no-nudge	Omit the nudge line

What it calls

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

Headers replicate the macOS app exactly: Authorization: Bearer <token>, originator: Codex Desktop, OAI-Product-Sku: CODEX, Accept: application/json, and ChatGPT-Account-Id (resolved from the JWT, not a static field). The account id is decoded from the id_token JWT payload's https://api.openai.com/auth.chatgpt_account_id claim, falling back to the access_token JWT, then to the account_id field in auth.json — exactly as upstream does.

These endpoints are internal and can change without notice.

Environment

• CODEX_HOME — override the .codex directory (defaults to ~/.codex).

Privacy

Your bearer token is read from auth.json at runtime and sent only to chatgpt.com. It is never printed, logged, or stored anywhere else. Response data is displayed on stdout and discarded unless you redirect it yourself.

Limitations

• Unofficial, not affiliated with OpenAI.
• The endpoints are internal and may change without notice.
• Usage and reset-credit fields may differ by Codex plan, account type, region, or app version.
• This is a faithful port of the macOS app's logic; it inherits the same endpoint assumptions.

Credits

Nudge logic, urgency levels, header set, and JWT-based account-id resolution are ported from jordan-edai/codex-reset-watcher (MIT). This project is independent and not maintained by that project's author.

License

MIT. See LICENSE and NOTICE for attribution details.