openai / openai/codex-plugin-cc
Add `/codex:usage` command to show rate limits and usage
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 33.3k
- Forks
- 2.3k
- PR merge metrics
- No merged PRs in 30d
Description
Problem
There is currently no way to check Codex rate limits and usage from within Claude Code. Users must switch to the Codex TUI and run /status to see how much of their 5h or weekly limit remains. This breaks the workflow when working inside Claude Code with the plugin.
Proposal
In the Codex TUI, /status shows both job status and rate limits together. In the plugin, /codex:status is already taken for job tracking, so this proposes a dedicated /codex:usage command for the rate limit portion:
# Codex Usage
Plan: Plus
Limits:
- 5h limit: 73% left (resets 1 Apr, 18:22)
- Weekly limit: 54% left (resets 5 Apr, 09:15)
- Code review Weekly limit: 91% left (resets 7 Apr, 14:30)
Implementation approach
The Codex CLI already fetches rate limit data internally via GET /api/codex/usage (see codex-rs/backend-client/src/client.rs:257-264). Three paths in order of preference:
-
Use an existing CLI subcommand — if
codex usage --jsonor similar already exists and I missed it, the plugin can simply call it viarunCommand("codex", ["usage", "--json"]), consistent with how it already callscodex login status. -
Add a CLI subcommand first — if no such subcommand exists yet, adding
codex usage --jsonto the Codex CLI (openai/codex) would be the cleanest path. The plugin could then delegate to it without touching auth files directly. -
Read
auth.jsonand call the API directly — as a fallback, the plugin can read~/.codex/auth.jsonand call the usage endpoint itself. This works today but breaks the plugin's established pattern of delegating all auth to the CLI binary. I have a working implementation of this approach ready as a PR.
Scope
- New file:
plugins/codex/commands/usage.md - Edit:
codex-companion.mjs— addcase "usage"handler and updateprintUsage() - Edit:
lib/render.mjs— addrenderUsageReport()function - Optional:
--jsonflag for structured output
Additional context
The rate limit API response includes:
plan_type(free, plus, pro, team, enterprise, etc.)rate_limit.primary_window/secondary_window(used_percent, limit_window_seconds, reset_at)credits(has_credits, unlimited, balance)code_review_rate_limit(separate limit for code reviews)
This issue was drafted with the assistance of Claude Code (Anthropic).
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with plugins/codex/commands/usage.md, codex-companion.mjs, and lib/render.mjs, then inspect the existing codex login status command and the referenced usage endpoint. Decide which listed data path is appropriate, implement the /codex:usage handler and report rendering, and verify that plan and rate-limit details are displayed, with structured output if included.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- api, cli
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100