pi-openai-codex-usage

English | 简体中文

Unofficial. Not affiliated with OpenAI. Reads the same ChatGPT usage endpoint the official Codex client uses (/backend-api/wham/usage). It is not a documented public API and may change without notice. The package may stop working at any time.

ChatGPT Codex subscription usage in the pi coding agent footer, with a full /codex-usage report.

codex 5h ████████░ 43% · 7d █████████░ 12% ↻5h 12m

What it shows

While an openai-codex model is active, the footer shows the active bucket (the limit the server meters for the model in use, e.g. codex or spark), one 8-cell bar per window (up to two), the remaining percent, and the nearest reset countdown. Stale data is marked. Multi-bucket plans, weekly-only plans, credits, earned reset credits (including the consume action), plan type and spend control are all visible in the /codex-usage report.

Install

pi install npm:pi-openai-codex-usage

Or from git:

pi install git:github.com/frederick-wang/pi-openai-codex-usage

Requires a Pi /login for OpenAI Codex (ChatGPT Plus/Pro subscription OAuth). Never reads the Codex CLI's own auth file.

Commands

• /codex-usage — full report overlay (all buckets, credits, reset credits, plan, spend control, freshness).
• /codex-usage --json — stable machine-readable snapshot (English keys only). TUI shows it in the overlay; print mode writes it to stdout; other modes refuse.
• /codex-usage --refresh — bypass the throttle and fetch immediately.

Reset credits can be consumed from the report: the flow verifies the account identity, asks for confirmation against the option's title/description/expiry, and explains the outcome (this is the only operation in the extension that changes server state).

Auth & privacy

• Credentials come from Pi's own openai-codex auth; the extension never refreshes or writes them, never reads ~/.codex/auth.json.
• The account id exists in memory only (account-switch detection); it is never logged, persisted, or exported.
• Snapshots persisted to ~/.pi/agent/pi-openai-codex-usage-snapshots.jsonl contain no tokens, no raw headers, no account id.
• No telemetry; no network other than the usage endpoints.

Configuration

• PI_OPENAI_CODEX_USAGE_LANG=zh|en — UI language (default: locale, then English).

Notes

• Window labels are derived from the server-reported durations (5h, 7d, …) and can change; they are never hardcoded.
• The usage endpoint is fetched on activation, after settled runs, every 5 minutes while active, and on command — not on a fixed busy poll.
• Where a window is absent from the server response it renders as n/a, never as a fake zero.