@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 model (openai-codex provider) is selected — 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/<you>/pi-codex-usage
# pinned tag:
pi install git:github.com/<you>/[email protected]

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). 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(); tokens are refreshed by pi and never logged or persisted by this extension.

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. | | 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
└── types.ts    # shared snapshot/window types
test/
├── fixtures/   # sample wham/usage payload
└── *.test.ts   # node:test suites

License

MIT