@sreetej510/pi-usage
A pi coding agent extension that reports provider
usage / rate-limit budgets — OpenAI Codex, Anthropic OAuth, and pi-auth-backed providers — via
/usage, with an optional live statusline widget.
What it does
- Queries the active model's provider usage endpoint (Codex app-server usage/rate-limit-reset APIs, or Anthropic's OAuth usage API) and renders remaining budget/reset windows.
- Caches results on disk (
~/.pi/agent/usage-cache.json) for a few minutes so multiple concurrent pi sessions don't hammer the provider APIs. - Can push a compact usage summary into the statusline, refreshed automatically with retry/backoff
on rate limits (
429). - Supports listing and consuming Codex "banked" rate-limit resets.
Commands
| Command | Effect |
|---|---|
/usage |
Show cached usage (fetches fresh data if the cache is stale) |
/usage --refresh |
Force a fresh fetch, bypassing the cache |
/usage --no-statusline |
Don't update the statusline widget |
/usage --clear-statusline |
Clear the usage statusline widget |
/usage --timeout <seconds> |
Set the query timeout |
/usage --raw |
Show raw usage API responses (debugging) |
/usage --list-banked-resets |
List available Codex banked resets and expiry dates |
/usage --consume-banked-reset <id> |
Consume a specific Codex banked reset |
Install
npm install -g @sreetej510/pi-usageThen add it to your pi settings.json:
{
"packages": ["npm:@sreetej510/pi-usage"]
}Or, for local development, point at the file directly:
{
"extensions": ["/absolute/path/to/pi-extensions/extensions/pi-usage/src/index.ts"]
}File layout
| File | Responsibility |
|---|---|
src/index.ts |
Extension entry point + session event wiring |
src/command.ts |
/usage command handler |
src/statusline.ts |
Statusline state, timers, background refresh |
src/footer.ts |
Custom footer with right-aligned usage status |
src/query.ts |
Top-level usage query orchestration |
src/codex-query.ts |
Codex pi-auth + app-server fallback queries |
src/anthropic-query.ts |
Anthropic OAuth usage queries |
src/codex-auth.ts |
Codex auth header resolution |
src/anthropic-auth.ts |
Anthropic auth header resolution |
src/codex-app-server.ts |
codex app-server RPC client |
src/codex-reset-credits.ts |
Banked reset list/consume/format |
src/normalize-codex.ts |
Codex backend + app-server payload normalization |
src/normalize-anthropic.ts |
Anthropic usage payload normalization |
src/format.ts |
Report/statusline formatting and display |
src/shared-cache.ts |
On-disk shared usage cache |
src/models.ts |
Provider/model matching helpers |
src/args.ts |
/usage argument parsing and completions |
src/constants.ts |
Shared constants |
src/types.ts |
Shared TypeScript types |
src/utils.ts |
Small parsing/formatting helpers |
src/errors.ts |
HTTP/rate-limit error helpers |
src/http.ts |
fetchWithTimeout wrapper |
Development
npm install
npm run --workspace @sreetej510/pi-usage check # biome + typecheck
npm run --workspace @sreetej510/pi-usage format