@andre-barbosa/pi-codex-usage

A pi package that shows your OpenAI Codex (ChatGPT plan) usage limits in the top-right of pi's footer whenever a Codex subscription model is selected — including the built-in openai-codex provider and cloned providers from pi-codex-multi — and hands the footer back to pi when you switch to any other provider.

Codex 5h 72% left (2h 13m) · week 44% left (5d 15h)

Percentages are colored by how much you have left (green / yellow / red). Snapshots older than 15 minutes are marked · stale — plan usage shifts whenever any of your sessions consumes quota, so old numbers can quietly become wrong.

Install

From npm

pi install npm:@andre-barbosa/pi-codex-usage

From git

pi install git:github.com/AndreB10/pi-codex-usage
# pinned tag:
pi install git:github.com/AndreB10/pi-codex-usage@v0.1.0

From a local checkout (development)

Add the extension entry to ~/.pi/agent/settings.json:

{
	"extensions": ["/absolute/path/to/pi-codex-usage/src"]
}

Then start pi and run /reload after making changes.

Managing

pi list                            # show installed packages
pi update --all                    # update pi + packages
pi update npm:pi-codex-usage       # just this one
pi remove npm:pi-codex-usage       # uninstall

Requirements

• Signed in via /login → OpenAI Codex (ChatGPT subscription auth), or via the selected cloned provider (for example /login codex-work with pi-codex-multi). API-key openai models have no plan windows and are ignored.
• No runtime dependencies. Node >= 23.6 is only needed to run the test suite locally; pi's own runtime handles the extension.

What it shows

• Primary window (usually 5 hours) and secondary window (usually weekly), labeled from the window duration the backend reports rather than hardcoded assumptions — on some plans the weekly window arrives in the primary slot.
• Additional limit buckets (e.g. model-specific limits like codex_spark) when present.
• Per-window reset countdowns, plus plan type, credits, data age, and the last error in /codex-usage.
• Placeholder buckets reported by the backend (0% used, no duration, no reset time) are hidden instead of rendering as noise like 1m 100% left.

Commands

Command	Description
/codex-usage	Open a detail panel with per-window bars, reset times, plan, credits
/codex-usage refresh	Force a fresh fetch, then show the panel

Display

The usage renders right-aligned on the footer's top line:

~/projects/x (main)     Codex 5h 72% left (2h 13m) · week 44% left (5d 15h)
↑1.2k ↓340 R980 CH95.2% $0.012 (sub) 18.3%/272k        gpt-5.6-sol • xhigh

While a Codex model is active, the extension owns the footer and reproduces everything from pi's built-in one: pwd/branch/session name, token + cache + cost stats, context %, model / thinking level, and other extensions' statuses. Switching to a non-Codex model restores the built-in footer automatically. Because it owns the footer, another extension calling setFooter would replace it (and vice versa).

Token/cost stats are recomputed on every render pass like the built-in footer; idle-time usage refreshes trigger an explicit re-render nudge.

How it gets data

Two sources, used together:

1. Usage endpoint — GET <baseUrl>/wham/usage (or /api/codex/usage on non-ChatGPT hosts), the same endpoint the official Codex CLI uses (see rate_limit_resets.rs).
2. Response headers — Codex responses carry x-codex-*-used-percent style headers, parsed exactly like rate_limits.rs in the official client. These are read opportunistically on every response so data stays fresh between endpoint fetches.

Authentication uses your existing pi OAuth credentials resolved through ctx.modelRegistry.getProviderAuth() for the active provider id; tokens are refreshed by pi and never logged or persisted by this extension. Usage snapshots and refresh throttles are kept separately per provider, so switching between pi-codex-multi accounts never displays or reuses another account's limits.

Refresh triggers: session start, switching to a Codex model, and after each settled agent run — throttled to at most one fetch per 30 seconds. There is no background polling loop, so after 15 minutes idle the footer marks the numbers stale.

Troubleshooting

Symptom	Likely cause / fix
Footer looks unchanged	A non-Codex model is selected, another extension replaced the footer, or you're not signed in via /login <selected-provider>.
Shows · stale	Last snapshot is >15 min old (idle period). Send a message or run /codex-usage refresh.
Numbers look wrong	Check /codex-usage for last error: and updated Ns ago via …; compare with /status in the official Codex CLI.
No footer in scripts / RPC	Non-TUI modes have no footer; only /codex-usage works there.

Notes & limitations

• The usage endpoint is internal and undocumented; if OpenAI changes it, header parsing keeps working as a fallback.
• Values are "percent of window used" as reported by the backend; this extension displays the complement ("left").
• Errors never surface as popups during normal use — check /codex-usage for the last error.

Development

npm install        # optional: types + editor support
npm test           # unit tests over parsing/formatting/client (no network)
npm run typecheck  # requires devDependencies installed

Run a single suite: node --test test/parse.test.ts

Layout:

src/
├── index.ts    # extension entry: events, footer, detail panel, command
├── client.ts   # endpoint URL building, JWT account-id extraction, fetch
├── parse.ts    # pure parsers: wham payload, x-codex-* headers, merge
├── format.ts   # pure formatting: labels, bars, colors, status groups
├── provider.ts # built-in + cloned Codex model recognition
└── types.ts    # shared snapshot/window types
test/
├── fixtures/   # sample wham/usage payload
└── *.test.ts   # node:test suites

License

MIT