📊 pi-usage — Provider Usage for Pi

@narumitw/pi-usage is a native Pi coding agent extension that adds an interactive /usage command for reading usage from the account Pi is actually using and a /fast shortcut for supported OpenAI Codex models. It supports Codex ChatGPT subscription windows, GitHub Copilot allowances, and OpenRouter API-key spend limits without pretending those limits have the same semantics.

✨ Features

• Opens one interactive /usage menu with current state and next actions.
• Automatically queries the selected model provider and active runtime account.
• Supports OpenAI Codex subscription windows, resets, credits, and model-specific buckets.
• Toggles persistent Codex Fast routing through /fast or the contextual /usage action.
• Redeems earned Codex usage-limit resets for the active, matching Pi OAuth account with fresh availability, explicit confirmation, and idempotent retry.
• Supports GitHub Copilot AI Credits, legacy premium requests, Free chat quota, additional usage, percentage, and reset time.
• Supports OpenRouter per-key credit limits plus daily, weekly, monthly, and all-time spend.
• Provides explicit refresh, another-provider, and all-configured-provider actions.
• Runs manually requested all-provider queries with concurrency limited to two and preserves partial results.
• Labels only the selected model provider as Current; other results are Configured.
• Keeps the compact statusline scoped to the current provider and runtime account.
• Isolates its five-minute in-memory cache by provider and a process-salted credential fingerprint.
• Resolves runtime credentials through Pi; for Copilot only, reads Pi's stored OAuth credential through Pi's public credential API and verifies that it matches the active runtime account.

📦 Install

Requires Pi 0.81.0 or newer so the extension can validate the effective base URL attached to resolved provider auth before sending credentials to an official usage endpoint.

pi install npm:@narumitw/pi-usage

Try without installing permanently:

pi -e npm:@narumitw/pi-usage

Try this package locally from the repository root:

pi -e ./packages/pi-usage

The package declares dist/index.ts, so an unbuilt local checkout must run npm --workspace @narumitw/pi-usage run build before Pi loads the package directory.

just try usage runs that build automatically.

🚀 Usage

Run:

/usage

In TUI or RPC mode, the standard menu first queries the current model provider and presents its state with these actions:

Refresh current usage
Turn Fast mode on/off       # Supported current Codex models only
Redeem usage limit reset…   # Current Codex OAuth accounts only
View another configured provider…
View all configured providers…
Close

There are intentionally no /usage --refresh, /usage <provider>, or /usage --all argument paths. Cross-provider traffic requires an explicit interactive choice. Escape returns from provider selection and closes the root menu. Print and JSON modes reject /usage observably because they cannot host the interactive flow. The cancellable live-query progress view remains extension-owned because it streams provider work and supports in-flight abort rather than presenting a standard menu screen.

For the current OpenAI Codex provider, Redeem usage limit reset… checks fresh earned-reset details, lets you select a reset when details are available, and shows the exact reset before asking for confirmation. No, go back is the safe default and cancellation before confirmation sends no mutation. After confirmation, the reset operation cannot be cancelled from its progress view; session replacement or shutdown still aborts owned work. A transport failure offers Try again with the same redemption request ID so the backend can treat an uncertain retry idempotently. Successful, already-completed, not-needed, and no-credit outcomes are reported separately, then usage and the statusline are refreshed for the still-current account.

Codex Fast mode

Run bare /fast to toggle Fast for the active supported Codex model, or use Turn Fast mode on/off in /usage.

Fast is about 1.5× faster and uses more of your plan allowance. The preference defaults to Off and is saved as codexFastMode in Pi's user agent directory as pi-usage.json, normally ~/.pi/agent/pi-usage.json. The extension reloads this file at every session start and does not create it until the first successful toggle.

Fast currently applies only to official openai-codex-responses requests for gpt-5.4, gpt-5.5, gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna at https://chatgpt.com. It sends service_tier: "priority" while enabled and explicit service_tier: "default" otherwise. The statusline adds fast only while the preference is effective, for example codex fast 59% 5h. Unsupported models and custom or proxy origins are left unchanged.

/fast supports TUI and RPC mode, accepts no arguments, and rejects print or JSON mode before mutation. A toggle affects provider requests whose payload hook starts after the save; a request already sent is unchanged. Settings operations are serialized inside one Pi process, but separate Pi processes are not mutually locked. Unknown JSON fields are preserved, writes use a private temporary file plus rename, and a malformed or invalid file is never overwritten. Repair or remove an invalid file, then run /reload before trying the toggle again.

📋 Provider semantics

OpenAI Codex

• Provider ID: openai-codex
• Semantics: ChatGPT consumer subscription limits
• Source: the Codex usage and earned-reset endpoints using Pi's resolved runtime authorization
• Displayed data: returned duration-based windows, resets, credits, earned usage-limit resets, and additional model buckets
• Reset mutation: POST /wham/rate-limit-reset-credits/consume with a unique redemption request ID and, when available, the selected opaque credit ID
• Statusline examples: codex 59% 5h 61% wk, codex fast 59% 5h, or codex spark 100% 5h

The statusline selects a returned bucket that matches the current Codex model when one is available. Unlike pi-codex-usage, this successor intentionally has no Codex CLI fallback because the CLI may be logged into a different account than Pi's active runtime account.

Reset redemption is available only when Codex is the current provider and Pi's freshly resolved access token exactly matches its stored OpenAI Codex OAuth credential. pi-usage forwards only the bearer authorization and matching chatgpt-account-id to the official ChatGPT origin. API-key credentials, configured-but-not-current Codex accounts, account changes during the flow, and custom/proxy origins fail before mutation. Backend-provided titles and descriptions are sanitized for terminal display; opaque credit and account IDs are never shown or persisted by the extension.

GitHub Copilot

• Provider ID: github-copilot
• Semantics: the allowance reported for the active Copilot plan—AI credits for current usage-based billing, premium requests for legacy annual billing, or chat requests for Copilot Free's limited response shape
• Source: GitHub's undocumented GET /copilot_internal/user endpoint
• Displayed data: entitlement, remaining allowance, percentage, reset time, plan, and any additional usage beyond the included allowance
• Statusline examples: copilot credits 1200/1500 80%, copilot 245/300 82%, or copilot chat 40/50 80%

GitHub's quota endpoint requires the original GitHub OAuth token rather than the short-lived Copilot inference token exposed by runtime auth. pi-usage therefore supports Copilot accounts created through Pi's /login flow, reads that stored credential through Pi's public API, and uses it only when its short-lived access token matches the active runtime credential. API-key credentials, account mismatches, GitHub Enterprise accounts, and proxy/custom provider origins fail closed. The detailed report follows the endpoint's token_based_billing marker so AI credits are not mislabeled as legacy premium requests, and it reports overage without treating a negative included balance as a malformed response.

OpenRouter

• Provider ID: openrouter
• Semantics: API-key spend and per-key credit limits—not consumer subscription quota
• Source: OpenRouter's documented GET /api/v1/key endpoint using Pi's resolved inference API key
• Displayed data: key label when safely returned, optional per-key limit and remaining amount, reset period, and daily/weekly/monthly/all-time spend
• Statusline examples: openrouter $74.50 left or openrouter $25.50 used

The extension does not call OpenRouter's account-level /credits endpoint because that operation requires a separate management key. OpenRouter documents the distinction between credit and rate limits in its API limits guide.

OpenCode Go (Zen)

• Provider ID: opencode-go
• Semantics: OpenCode Zen plan usage windows—rolling, weekly, and monthly
• Source: GET {model base URL}/usage on the configured opencode.ai gateway using Pi's resolved inference API key
• Displayed data: used percentage and reset time for each window; rate-limited windows remain visible at their reported usage, while unknown statuses are reported as unavailable notes
• Statusline examples: zen 0% r 4% w 2% m

The usage endpoint is derived from the model's base URL (…/zen/go/v1/usage) and is only queried when the resolved origin is https://opencode.ai; other origins fail before sending the credential.

🧭 Current and configured accounts

Current means the provider and credential used by Pi's selected model. Configured means Pi reports runtime auth for another supported provider; it does not mean that provider is active.

The extension does not enumerate multiple accounts inside one provider and does not switch accounts. Account selection remains owned by Pi or an account-management extension. After the active runtime credential changes, the next command, turn, or scheduled refresh resolves auth again and cannot reuse another account's cached report.

📊 Statusline behavior

The usage status item is active only for the selected model provider. It refreshes every five minutes while the session remains on a supported provider and is cleared when the model changes to an unsupported provider.

Manual another-provider and all-provider queries never publish to the statusline. @narumitw/pi-statusline supplies the default 📊 icon; pi-usage publishes text-only values.

🔄 Migrating from pi-codex-usage

pi-codex-usage is deprecated and its source is archived under deprecated/. To migrate one installation:

pi remove npm:@narumitw/pi-codex-usage
pi install npm:@narumitw/pi-usage

Remove the deprecated package rather than loading both usage extensions together.

Behavior changes:

• Use /usage for usage management; /codex-status is no longer registered.
• Refresh and cross-provider operations are menu actions rather than flags.
• Codex CLI fallback is removed to preserve active-runtime-account correctness.
• The status key changes from codex-usage to usage.

🚧 Limitations

• Only providers with a meaningful usage source and verifiable Pi runtime auth are supported.
• GitHub Copilot quota and OpenAI Codex reset redemption use undocumented provider endpoints that may change without notice.
• Codex reset redemption requires a current ChatGPT OAuth login created through Pi; Codex API keys cannot redeem earned subscription resets.
• Credentials resolved for custom provider base URLs are never forwarded to the providers' official usage endpoints; effective auth origin validation requires Pi 0.81.0 or newer.
• Provider reports are snapshots and may themselves be delayed by the provider.
• OpenRouter successful inference responses do not expose proactive request-rate counters; /usage reports the documented per-key credit/spend fields instead.
• A provider may not return a safe human-readable account identity. In that case the provider and runtime credential state remain visible without exposing secrets.
• Immediate account-change events are not available from Pi; auth is re-resolved before commands, turns, and scheduled refreshes.
• Fast model support is intentionally conservative and may require an extension update when Codex adds or removes service tiers.
• Another later-loaded extension can replace the final provider payload, so arbitrary third-party payload-rewrite conflicts cannot be prevented.

🗂️ Package layout

packages/pi-usage/
├── dist/                  # Generated TypeScript runtime loaded by Jiti
├── scripts/
│   └── build-runtime.mjs  # Deterministic runtime builder and boundary validator
├── src/
│   ├── index.ts       # Pi package entrypoint and helper export barrel
│   ├── usage.ts       # Menu, cache, and usage lifecycle orchestration
│   ├── codex-fast.ts  # Fast eligibility, request tier, and cost correction
│   ├── codex-fast-runtime.ts # Fast command, persistence lifecycle, and request hooks
│   ├── settings.ts    # Validated user settings and atomic persistence
│   ├── usage-helpers.ts # Small orchestration helpers
│   ├── query.ts       # Runtime auth resolution and bounded provider queries
│   ├── codex-resets.ts # Codex reset auth, API contracts, and normalization
│   ├── format.ts      # Provider-aware notifications and statusline text
│   ├── core.ts        # Cache, concurrency, fingerprint, and redaction helpers
│   ├── providers/     # Codex, GitHub Copilot, and OpenRouter normalization adapters
│   └── types.ts       # Common presentation and adapter contracts
├── test/
├── README.md
├── LICENSE
├── tsconfig.json
└── package.json

index.ts is the Pi entrypoint and forwards the default factory from usage.ts while retaining the package's named helper exports; other source modules are internal.

The generated runtime is built from the authoritative src/index.ts graph and does not import back into src.

🔎 Keywords

Pi extension, Pi coding agent, usage, quota, OpenAI Codex usage, ChatGPT subscription limits, GitHub Copilot AI credits, GitHub Copilot premium requests, OpenRouter credits, API-key spend limits, TypeScript Pi package, npm Pi extension.

📄 License

MIT. See LICENSE.