@ipmanlk/pi-usage — Realtime Provider Usage for Pi

/usage dashboard + per-provider usage commands + realtime footer statusline, plus OpenAI Codex usage-limit reset redemption. No fast-mode coupling.

Features

• /usage — bordered TUI dashboard (pi-quotas style) showing every configured provider side by side: progress bars, used/remaining counts, reset times. Press r to refresh, q/Esc to close. /usage <provider> shows one provider in detail. Non-TUI fallback prints a text summary.
• Per-provider commands — /anthropic:usage, /codex:usage, /github:usage, /openrouter:usage, /synthetic:usage, /grok:usage, /zai:usage, /opencode-go:usage, /kimi:usage, /ollama:usage. Unlike the combined dashboard (which hides unconfigured providers), these surface raw auth/API errors for troubleshooting.
• Statusline — realtime quota headroom for the active provider in the Pi footer. Refreshes every 60s and on each turn / model change. Green → amber → red as usage climbs. Toggleable via /usage:settings (applies live).
• /codex:reset — redeem an earned OpenAI Codex usage-limit reset. Requires the current model to use OpenAI Codex, freshly matches the runtime account against the stored OAuth credential (fails closed on mismatch), asks for explicit confirmation (not cancellable after confirming), and redeems with a unique idempotency key. Codex reset availability is also shown in the dashboard wherever the count is known.
• Auto credential resolve (narumitw-style) — model-scoped runtime auth first (the same path pi uses for model calls — required for OAuth providers), then getApiKeyForProvider / getProviderAuth, then the stored /login credential as last resort (never shadowing live auth). Honours the versioned oauth:credential-source:v1 process-local protocol, and guards official origins for API-key providers (custom/proxy base URLs report "usage unavailable" instead of forwarding a possibly proxy-scoped key).
• Zero runtime dependencies — only peerDependencies on pi packages + Node builtins. Source ships as TS loaded via jiti; no bundler, no build step.

Install

pi install npm:@ipmanlk/pi-usage

Try without installing:

pi -e npm:@ipmanlk/pi-usage

Commands

Command	Description
/usage [provider]	Usage dashboard for all configured providers (or one)
/anthropic:usage, /codex:usage, …	Per-provider usage (shows raw errors)
/codex:reset	Redeem a Codex usage limit reset (Codex model required)
/usage:settings	Toggle statusline / dashboard / provider commands

Supported providers

Provider	Source
Anthropic	OAuth subscription usage (sk-ant-oat only; direct sk-ant-api keys report n/a)
OpenAI Codex	chatgpt.com/backend-api/wham/usage (+ ~/.codex/auth.json account id)
GitHub Copilot	api.github.com/copilot_internal/user (OAuth refresh → token exchange → direct → gh auth token fallback; Enterprise reports guidance without network calls)
OpenRouter	openrouter.ai/api/v1/key
Synthetic	api.synthetic.new/v2/quotas (SYNTHETIC_API_KEY fallback)
Grok (xAI)	CLI billing endpoint
Z.ai	Quota/limit endpoint
OpenCode Go	Dashboard scrape (OPENCODE_GO_WORKSPACE_ID + OPENCODE_GO_AUTH_COOKIE or config file)
Kimi Code	api.kimi.com/coding/v1/usages
Ollama Cloud	ollama.com/api/usage (OLLAMA_API_KEY fallback)

The dashboard hides providers with no configured credentials and silent not_applicable states. The statusline only ever shows the active provider. Severity colors use the same pace-projection model as the reference (warnings fire when burn rate would exhaust the window early, not just on absolute percentage).

Cache behavior

• Per-provider TTLs (60s; 5min for Anthropic/Copilot) with in-flight dedup.
• Cache keys are account-aware (SHA-256 of credential + account extras), so a credential rotation never reuses another account's report.
• Bounded at 32 entries with oldest-eviction; cleared on session shutdown.
• Failures are cached for the same TTL to avoid hammering providers; r (refresh) in the dashboard bypasses the cache.

Settings

/usage:settings writes to either:

• global: ~/.pi/agent/extensions/usage.json
• local: .pi/usage.json (project overrides global)

{
  "statusline": true,
  "dashboard": true,
  "providerCommands": true
}

The statusline toggles live; command visibility applies after /reload.

Security

• Credentials are only sent to hardcoded official provider endpoints.
• Origin guard for API-key providers: a custom/proxy model baseUrl disables usage for that provider instead of forwarding a possibly proxy-scoped key. OAuth-subscription providers are exempt by design (vendor-scoped token sent back to the same vendor; worst case is an auth error, never a third-party leak).
• Codex resets revalidate the model/account immediately before redeeming and abort without consuming on any mismatch; the consume call itself is non-cancellable by design.
• HTTP error bodies are reduced to short messages (no raw blobs in UI).
• Errors never include secret material; cache keys use SHA-256 fingerprints.
• 15s fetch timeouts with AbortSignal composed from timeout + caller (AbortSignal.any / linked controllers, listeners always cleaned up). Dashboard refetch cancels the superseded request (never cached); the statusline aborts replaced polls; reset dialogs dismiss on session shutdown while the confirmed consume itself stays non-cancellable by design.
• GitHub Copilot follows the reference chain: OAuth refresh → token exchange → direct → gh CLI fallback.
• No exec except the gh auth token Copilot fallback (5s timeout, stdio muted).

Acknowledgements

Provider endpoint + parsing semantics adapted from @latentminds/pi-quotas (MIT). Credential-source protocol, origin validation, and Codex reset endpoints/logic ported from @narumitw/pi-usage (MIT). Dashboard UX inspired by pi-quotas; statusline lifecycle likewise.

License

MIT