openai / openai/codex-plugin-cc

Add `/codex:usage` command to show rate limits and usage

Open
#102 0 comments 0 reactions 0 assignees View on GitHub

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:

  1. Use an existing CLI subcommand — if codex usage --json or similar already exists and I missed it, the plugin can simply call it via runCommand("codex", ["usage", "--json"]), consistent with how it already calls codex login status.

  2. Add a CLI subcommand first — if no such subcommand exists yet, adding codex usage --json to the Codex CLI (openai/codex) would be the cleanest path. The plugin could then delegate to it without touching auth files directly.

  3. Read auth.json and call the API directly — as a fallback, the plugin can read ~/.codex/auth.json and 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 — add case "usage" handler and update printUsage()
  • Edit: lib/render.mjs — add renderUsageReport() function
  • Optional: --json flag 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.