feat: add codex-reset tool to view and redeem banked rate-limit reset credits

[xuli500177]

Feature Request: codex-reset tool

Problem

OpenAI introduced banked rate-limit resets for Codex on 2026-06-12. Every eligible ChatGPT plan (Plus/Pro/Business) was granted at least one free reset, plus up to 3 more via referrals. However, the redemption UI exists only in:

• Codex Desktop App (Windows/macOS only)
• VS Code / Cursor / Windsurf extension
• Codex CLI v0.142.0+ /usage TUI

Linux CLI users who rely on this plugin have no way to view or redeem their banked resets without switching to another tool. The plugin already has codex-limits to view quota but cannot act on available resets.

Proposed Solution

Add a new codex-reset tool that can:

1. List available banked rate-limit reset credits with expiry dates and current usage
2. Redeem one reset credit (with confirmation prompt)
3. Support --json and --dry-run flags

Technical Analysis

The plugin already has most of the infrastructure needed:

What exists	Where
CODEX_BASE_URL = "https://chatgpt.com/backend-api"	lib/constants.ts
createCodexHeaders() for auth headers	lib/request/fetch-helpers.ts
fetchCodexUsage() calling GET /wham/usage	lib/codex-usage.ts
Tool factory pattern (createCodexLimitsTool(ctx))	lib/tools/codex-limits.ts
Tool registration via createToolRegistry()	lib/tools/index.ts

New API endpoints needed:

Endpoint	Method	Purpose
/wham/rate-limit-reset-credits	GET	List banked credits and statuses
/wham/rate-limit-reset-credits/consume	POST	Redeem one credit (body: credit_id, redeem_request_id)

These use the same auth headers (Authorization: Bearer, ChatGPT-Account-Id) as the existing /wham/usage call.

Reference Implementation

The community script aaamosh/codex-reset demonstrates the full API interaction in ~300 lines of Python (MIT license). The plugin's TypeScript implementation would follow the same API contract.

Proposed Interface

codex-reset                          # show available credits + usage
codex-reset consume                  # redeem one credit (with confirmation)
codex-reset consume --yes            # skip confirmation
codex-reset consume --dry-run        # preview without redeeming
codex-reset format="json"            # machine-readable output

Output example (text mode)

banked credits: 2 available
  - RateLimitResetCredit_xxx  status=available  granted=2026-06-12  expires=2026-07-12
      "One free rate limit reset"

current usage:
  5h limit: 12% left (resets 14:30)
  Weekly limit: 73% left (resets Jul 18 23:12)

Why this belongs in the plugin

The plugin already manages ChatGPT OAuth tokens, queries /wham/usage for quota visibility, and provides 21 codex-* tools for account management. Adding reset redemption completes the quota management story without requiring users to switch to a separate tool or the Codex Desktop App.

[coderabbitai]

🔗 Related PRs

#70 - feat(codex-limits): add codex-limits tool and deduplicate accounts by refreshToken [closed]
#92 - add json ops output and routing visibility [merged]
#146 - [codex] add OpenCode TUI prompt status [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[aic0d3r]

yes please add this