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

[gignac-cha]

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).