@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-usage

Then 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