📊 pi-usage — Check Provider Usage, API Balance, and Codex Fast Mode

Inspect usage and DeepSeek API balance for Pi's active provider account, query other configured providers, and toggle Fast mode for supported OpenAI Codex models. The extension keeps each provider's native quota, allowance, and spending semantics instead of treating unlike values as equivalent. xAI OAuth subscription reporting follows the reviewed Grok Build contract and runs only after an explicit /usage action.

✨ Features

• Shows active-account usage and next actions through /usage.
• Reports OpenAI Codex subscription windows, credits, resets, and model-specific buckets.
• Reports Kimi For Coding plan windows, resets, and separately labeled booster-wallet currency.
• Reports Moonshot AI Global and China API account balances in their native currencies.
• Reports MiniMax Global and China Token Plan windows or pay-as-you-go API balance.
• Reports GitHub Copilot allowances and OpenRouter per-key limits and spending windows.
• Reports exact DeepSeek API balances with separate CNY and USD values.
• Reports OpenCode Go plan windows and Z.AI Coding Plan quotas.
• Reports Fireworks rated API spend for the last 30 days with per-series subtotals and account selection.
• Reports Vercel AI Gateway credit balance and lifetime spend.
• Reports Baseten organization Model APIs spend after credits for the last 30 days.
• Reports xAI OAuth subscription allowances and credits.
• Toggles persistent Codex Fast routing through /fast or the usage menu.
• Redeems eligible Codex resets only after fresh account matching and explicit confirmation.
• Refreshes one or all configured providers with bounded concurrency while preserving partial results.
• Scopes statusline and cache data to the active provider and runtime account.
• Resolves credentials through Pi or the process-local OAuth credential-source protocol and validates the effective provider endpoint before sending them.

📦 Install

Requires Pi 0.81.0 or newer to validate the effective base URL for resolved provider auth before sending credentials to an official usage endpoint. The v1 credential-source path is characterized against Pi 0.84.3; other runtimes keep the standalone fallback without its protocol timing guarantee.

Like every Pi extension, this package runs with Pi's process permissions. Review Security and privacy before installation.

pi install npm:@narumitw/pi-usage

Try without installing permanently:

pi -e npm:@narumitw/pi-usage

Build and try this package locally from the repository root:

npm --workspace @narumitw/pi-usage run build
pi -e ./packages/pi-usage

The package declares dist/index.ts, so an unbuilt local checkout must run the build before Pi loads the package directory.

🚀 Quick start

Run /usage in TUI or RPC mode to inspect the active provider, refresh its usage, or choose another configured provider. When a provider exposes several billing targets, /usage asks for one target before querying usage. Run /fast to toggle Fast mode for a supported active Codex model.

💬 Commands

Open the manager with:

/usage

In TUI or RPC mode, the menu first queries the active model provider and then offers these actions:

Refresh current usage
Settings
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

/usage accepts no arguments, including --refresh, a provider ID, or --all. Cross-provider requests require an explicit interactive choice. Escape returns from provider selection or closes the root menu. Print and JSON modes reject /usage because they cannot host the interactive flow. The extension owns the cancellable live-query progress view because it streams provider work and supports in-flight abort.

Provider targets

A target is the provider-owned account, organization, project, team, or workspace used for one usage query. Providers without target discovery query immediately, and a single returned target is selected automatically without writing settings. When several targets are available, /usage remembers an explicit selection by provider and reuses it only while it remains in a fresh listing. A missing remembered target returns Selection required instead of querying another target silently. The current provider then offers Select <target>…, while a ready current or individually viewed provider offers Change <target>….

Selecting another provider may open one Pi target prompt after that provider is queried lazily. Cancelling the prompt changes nothing. Auth and target membership are revalidated before an explicit selection is saved, then both are resolved again before billing is queried. View all configured providers… never opens nested target prompts: unresolved providers remain visible with guidance to view them individually. Background status refresh also stays non-interactive and shows selection required until /usage completes the choice. Fireworks accounts are the first implementation of this provider-neutral flow.

For the current OpenAI Codex provider, Redeem usage limit reset… first checks fresh earned-reset details. When details are available, you select a reset and review its exact effect before 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.

⚙️ Settings

Choose Settings in /usage to edit Codex Fast mode and the Codex reset countdown through Pi's settings-list interaction in TUI mode. RPC mode reports the active manual settings path instead of opening terminal UI.

These preferences live in pi-usage.json under Pi's user agent directory, normally ~/.pi/agent/pi-usage.json. The extension reloads this file at every session start and does not create it until the first successful save. Within one Pi process, changes save immediately in invocation order. Saves preserve unknown JSON fields and publish through a private temporary file plus rename. Malformed or invalid files remain untouched. A failed save restores the prior displayed and effective value, while shutdown waits for queued writes. Separate Pi processes are not mutually locked.

Target selections are stored only as IDs in the provider-neutral selectedTargets object in this file and are managed through /usage, not the Settings screen. The former fireworksAccountId field remains read-compatible: it supplies selectedTargets.fireworks in memory only when the generic value is absent. A successful explicit Fireworks account selection writes the generic field and removes the legacy field atomically; ordinary reads do not rewrite the file.

Codex Fast mode

Run /fast without arguments 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 codexFastMode preference defaults to Off.

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% ↻ 2h30m with the default reset countdown. 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. Repair or remove an invalid file, then run /reload before trying the toggle again.

Codex statusline reset countdown

The codexStatusResetCountdown preference defaults to true. It replaces the window labels with the time remaining until each returned limit resets. Turn Codex reset countdown Off in the TUI Settings screen, or set it to false in pi-usage.json and run /reload, to restore the legacy 5h and wk labels:

{
  "codexStatusResetCountdown": false
}

📋 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% ↻ 2h30m 61% ↻ 2d15m, codex fast 59% ↻ 2h30m, or codex spark 100% ↻ 2h30m. Set codexStatusResetCountdown to false for the legacy 5h and wk labels.

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. Pi's freshly resolved access token must exactly match an OAuth credential from Pi's stored login or a compatible credential source. 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.

Kimi For Coding

• Provider ID: kimi-coding
• Semantics: Kimi Coding Plan request windows plus a separate Extra Usage booster wallet
• Source: GET https://api.kimi.com/coding/v1/usages using Pi's freshly resolved runtime Bearer credential
• Displayed plan data: the weekly summary, returned sub-windows, used and remaining request percentages, and valid reset times
• Displayed wallet data: balance, monthly spend, and monthly charge limit
• Statusline examples: kimi 99% 5h 96% wk or kimi 95% 1d

Both Pi API-key credentials and Pi OAuth credentials are accepted because current Pi resolves each form as Bearer authorization for the same official Kimi inference origin. The extension queries the fixed usage endpoint only when both the selected model origin and the effective resolved-auth origin are https://api.kimi.com. Custom and proxy origins fail before network access, redirects are rejected, and the credential is never sent to an override from Kimi Code's environment-specific development path.

Plan buckets remain integer request counts and are rendered with their source-defined windows. Unknown units, duplicate windows, missing counts, invalid timestamps, and malformed rows remain unavailable rather than receiving guessed semantics. Booster-wallet amount and amountLeft values use Kimi's first-party conversion of 1,000,000 fixed-point units per cent, while monthly values already arrive in cents. Wallet values retain their currency and stay separate from plan requests and percentages in reports and the statusline. Wallet fields remain unavailable unless the response supplies one consistent currency; missing monthly values are omitted, and an enabled zero cap is shown as zero.

The contract was revalidated on 2026-08-27 against Pi c49906ec77788625aacbdc53ebca6fbe65bd20f5, including kimi-coding.ts and auth/oauth/kimi-coding.ts. It was also revalidated against Kimi Code 676e4d82240855044fe809fea89ce1dbe8e512cf, including managed-usage.ts and its tests. The pinned Pi source at e86823096c5bad39e1ca282ec24bc5eb9bec745b has no changes in either reviewed Kimi file at the selected revision. The pinned Kimi managed-usage source at cd7c97b377a77f7ae1b9d541cafe314e986ec074 is an ancestor of that selected revision and has no changes in the reviewed source or tests.

Moonshot AI API balance

• Provider IDs: moonshotai and moonshotai-cn
• Semantics: current API account balance, not Kimi For Coding subscription usage
• Global source: GET https://api.moonshot.ai/v1/users/me/balance
• China source: GET https://api.moonshot.cn/v1/users/me/balance
• Displayed data: available, voucher, and cash balance in USD for Global or CNY for China
• Statusline examples: moonshot USD 49.58894 or moonshot CNY 49.58894

Each endpoint uses Pi's resolved inference Bearer key for the matching region. Pi maps both built-in providers to MOONSHOT_API_KEY, so that shared environment credential is eligible only for the currently selected region. Querying the sibling region requires a provider-specific stored, runtime, or models.json credential. The extension rejects custom, proxy, and cross-region origins before network access and refuses redirects. Available and voucher balances must be nonnegative, while cash balance may be negative when the account owes money. The endpoint does not provide historical spend, token totals, quota windows, or reset times. These API-platform balances are independent from the kimi-coding subscription and booster wallet.

The contracts were verified on 2026-08-30 against the official Global balance reference, China balance reference, and first-party MoonshotAI-Cookbook balance client and DTO.

MiniMax Token Plan and API balance

• Provider IDs: minimax and minimax-cn
• Token Plan source: GET {region-api-root}/v1/token_plan/remains
• Pay-as-you-go source: GET {region-api-root}/account/query_balance
• Region API roots: https://api.minimax.io and https://api.minimaxi.com
• Statusline examples: minimax 15% 5h 80% wk or minimax USD 98.00001

Pi's resolved MiniMax API key selects exactly one endpoint before network access. Keys with the first-party sk-api- prefix query pay-as-you-go balance; other MiniMax API keys query Token Plan quota. The extension never probes both endpoints with one credential. Token Plan reports preserve provider rows, rolling and weekly windows, counts, reset times, unlimited status, and first-party handling for legacy versus current *_usage_count semantics. Pay-as-you-go reports keep available, cash, voucher, credit, and owed amounts separate in USD for Global or CNY for China. Custom, proxy, and cross-region origins fail before network access, and redirects are rejected.

The contract was verified on 2026-08-30 against MiniMax's Token Plan FAQ and the first-party MiniMax-AI/cli, including endpoint selection, response types, quota normalization, and SDK tests.

GitHub Copilot

• Provider ID: github-copilot
• Semantics: the allowance reported for the active Copilot plan
• Allowance labels: AI credits for usage-based billing, premium requests for legacy annual billing, or chat requests for Copilot Free
• 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 supports Copilot accounts created through Pi's /login flow and named accounts offered by a compatible oauth:credential-source:v1 owner. It uses a candidate only when its short-lived access token exactly matches the freshly resolved active runtime credential. Duplicate equivalent candidates are harmless, while conflicting matches fail closed without choosing by extension load order. 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. It reports overage without treating a negative included balance as malformed.

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.

DeepSeek API balance

• Provider ID: deepseek
• Semantics: current API account balance, not historical usage or quota
• Source: documented GET https://api.deepseek.com/user/balance using Pi's freshly resolved runtime API key
• Displayed data: whether API calls are available plus separate total, granted, and topped-up balances for each returned CNY or USD currency
• Statusline examples: deepseek CNY 110.00 or deepseek CNY 110.00 · USD 20.00

The extension queries the fixed balance endpoint only when the selected model origin is https://api.deepseek.com and any resolved-auth origin override, when present, has the same official origin. Pi's built-in DeepSeek API-key resolver does not attach a redundant auth origin, so the validated model origin remains authoritative when no override exists. Custom and proxy origins fail before network access, redirects are rejected, and only the resolved Bearer credential is forwarded from Pi's runtime auth. Monetary decimal strings remain exact from the response through display. CNY and USD stay separate and are never converted or added together. The balance endpoint does not provide historical spend, request windows, reset times, or aggregate token usage, so pi-usage does not claim those DeepSeek capabilities.

The contract was verified on 2026-08-28 against DeepSeek's Get User Balance documentation and Pi's deepseek.ts at c49906ec77788625aacbdc53ebca6fbe65bd20f5. DeepSeek Harness cd5ef8148158c3a752a658978873241fdf8e2bbc reports only per-request model token usage and does not provide account balance data.

Fireworks API spend

• Provider ID: fireworks
• Semantics: rated 30-day account spend, not credit balance or spend-cap quota
• Source: documented GET https://api.fireworks.ai/v1/accounts account discovery and GET https://api.fireworks.ai/v1/accounts/{account_id}/billing/summary rated costs using Pi's resolved inference API key
• Displayed data: exact rated spend per currency with serverless, dedicated-deployment, and training subtotals for the trailing 30 days
• Statusline example: fireworks USD 12.345678901

The extension queries the fixed endpoints only when the selected model origin is https://api.fireworks.ai and any resolved-auth origin override, when present, has the same official origin. The account slug is discovered through the documented account listing. One visible account is selected automatically; several visible accounts use the remembered selection or ask through /usage, and a disappeared selection returns Selection required without a billing request. Monetary units and nanos values are summed exactly with integer arithmetic and stay exact through display. Fireworks does not expose credit balance, spend caps, per-window quota, or reset times through its API, so pi-usage does not claim those Fireworks capabilities; the web console remains the authoritative balance source. Rated line items may differ from the final invoice once credits or adjustments are applied.

The contract was verified on 2026-07-31 against Fireworks' Usage & Cost Breakdown, Get billing summary, and List Accounts API references.

Vercel AI Gateway credits

• Provider ID: vercel-ai-gateway
• Semantics: current team credit balance and lifetime spend, not rate-limit quota
• Source: documented GET https://ai-gateway.vercel.sh/v1/credits using Pi's resolved AI Gateway API key
• Displayed data: exact decimal-string credit balance and lifetime spend in USD
• Statusline example: vercel USD 95.50 left

The extension queries the fixed endpoint only when the selected model origin and any resolved-auth origin are https://ai-gateway.vercel.sh. Custom and proxy origins fail before network access, redirects are rejected, and only the resolved Bearer credential is forwarded. The credits endpoint does not provide reset times, request-rate counters, or date-window usage, so pi-usage does not claim those capabilities. Vercel's separate Custom Reporting API is limited to eligible paid plans and is intentionally outside this first integration.

The contract was verified on 2026-08-30 against Vercel's REST API Reference and the first-party vercel/ai Gateway implementation.

Baseten Model APIs spend

• Provider ID: baseten
• Semantics: organization-wide Model APIs spend, not per-key quota or account balance
• Source: GET https://api.baseten.co/v1/billing/usage_summary using Pi's resolved Baseten API key
• Displayed data: trailing 30-day gross usage, credits used, and net subtotal in USD
• Statusline example: baseten USD 166.15 net

The extension intentionally ignores Dedicated deployment and Training categories because they do not represent Pi's Model APIs provider usage. The query window is a precise trailing 30 days and stays below the endpoint's 31-day maximum. The fixed Management API endpoint is queried only for an official https://inference.baseten.co model and an official resolved-auth origin. Custom and proxy origins fail before network access, redirects are rejected, and only the resolved Bearer credential is forwarded. An empty model_apis_usage result is reported as no Model APIs usage rather than zero account-wide spend.

The contract was verified on 2026-08-30 against Baseten's Billing and usage, Model APIs usage, first-party baseten-go Management OpenAPI, and baseten-cli billing behavior.

OpenCode Go (Zen)

• Provider ID: opencode-go
• Semantics: OpenCode Zen plan usage windows—rolling, weekly, and monthly
• Source: GET https://opencode.ai/zen/go/v1/usage using Pi's resolved inference API key
• Displayed data: used percentage and reset time for each window
• Status handling: rate-limited windows remain visible, while unknown statuses become unavailable notes
• Statusline examples: zen 0% r 4% w 2% m

The fixed endpoint is queried only when the OpenCode Go model uses the official https://opencode.ai origin. When resolved provider auth includes a base URL, that URL must use the same origin. Other origins fail before the credential is sent.

xAI consumer subscriptions

• Provider ID: xai
• Semantics: consumer subscription allowance and credits, not xAI API-team billing
• Identity route: GET https://cli-chat-proxy.grok.com/v1/user?include=subscription
• Billing route: GET https://cli-chat-proxy.grok.com/v1/billing?format=credits
• Displayed data: included allowance or legacy monetary limit, period and reset, on-demand spend and cap, prepaid balance, and a sanitized optional plan tier
• Statusline: not published; xAI is queried only through an explicit /usage action

The adapter accepts only the official Pi inference origin https://api.x.ai and a freshly resolved bearer that exactly matches one complete Pi OAuth credential. Pi's reviewed OAuth scope is openid profile email offline_access grok-cli:access api:access. The adapter rejects XAI_API_KEY, duplicate or conflicting OAuth candidates, account mismatches, and incomplete OAuth records. It also rejects custom or proxy-resolved origins before consumer-proxy access. API-key users can review API-team spend through console.x.ai instead. The public Management API requires a separate management key and team ID and is intentionally outside this runtime-credential integration.

The identity response supplies a transient proxy-canonical userId that is validated and sent as x-userid only on the billing request. The extension sends the matched bearer as Authorization plus Grok Build's source-defined non-secret X-XAI-Token-Auth, client-version, and interactive client-mode headers. It does not read Grok Build files, device state, names, email, or other profile fields. Responses are body-bounded, redirects are rejected, raw identity and billing payloads are not retained, and secrets are redacted from errors. Included allowance, on-demand usage, and prepaid balance remain distinct because they represent different billing concepts.

The current official Grok Build implementation is the ground truth for the xAI integration contract. The implementation contract was verified against these first-party revisions:

• Pi providers/xai.ts and auth/oauth/xai.ts at e868230, revalidated byte-for-byte for those files at ccfe79e.
• Grok Build UserInfo, subscription_check.rs, billing.rs, auth/config.rs, xai-grok-http, and xai-grok-version at 9684fa3.
• xAI Management API team billing boundary at 723dd2a.

The approved 2026-08-27 protocol smoke used only Pi's OAuth bearer and read no Grok-local files. A disposable or maintainer account received HTTP 200 without redirects from both routes. The implementation also sends the non-secret client headers present on both routes in current Grok Build source, with x-userid added only for billing. The sanitized identity shape contained a string userId and nullable subscriptionTier. The billing shape contained a config object with period and distinct on-demand and prepaid wrappers, without retaining field values.

xAI identity and billing requests occur only after an explicit current, configured-provider, or all-provider /usage action.

Z.AI (GLM Coding Plan)

• Provider ID: zai and zai-coding-cn
• Semantics: GLM Coding Plan quota windows—the rolling 5-hour and weekly plan-usage windows plus the monthly MCP allowance
• Source: the undocumented GET {origin}/api/monitor/usage/quota/limit endpoint also used by Z.AI's official coding plugin, plus the undocumented GET {origin}/api/biz/subscription/list plan endpoint
• Allowed origins: the model base URL must resolve to https://api.z.ai or https://open.bigmodel.cn
• Displayed data: explicit used and remaining values, reset times, provider-reported per-tool MCP details, and the plan name with its renewal date
• Percentage-only windows remain percent-based
• Statusline: publishes remaining plan percentages such as zai 87% 5h 76% wk; monthly MCP details remain available through /usage

The monitor endpoint is not a published API contract and may return legacy TOKENS_LIMIT or newer CREDIT_LIMIT window names. The extension classifies both forms by the provider's window unit and does not label provider-reported counts as tokens or calls. The quota monitor expects a raw API key without a Bearer prefix. The extension removes that prefix from resolved authorization before sending it to the monitor endpoint. Fingerprinting and redaction keep using the original resolved credential. The plan endpoint only contributes the plan name and renewal date; when it is unavailable or fails, the quota windows remain reported and the plan note falls back to the quota response's plan level. Only the official api.z.ai and open.bigmodel.cn origins are queried; other origins fail before sending the credential.

🧭 Current and configured accounts

Current identifies the provider and credential used by Pi's selected model. Configured identifies runtime auth for another supported provider, not an active provider.

The extension selects one provider target for one query and never flattens targets into provider rows or aggregates every visible target. Provider adapters own target discovery and validation; core owns one-target selection, persistence, cache identity, cancellation, and UI. A compatible credential owner may offer the verified active named account through the versioned process-local protocol without exposing its account label or storage. Without such an owner, pi-usage retains its standalone Pi auth.json behavior. An older or incompatible owner degrades to the existing authentication-unavailable result when the stored login does not match runtime auth. 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 selected providers that publish statusline usage. It refreshes every five minutes while the session remains on such a provider and is cleared when the model changes to an unsupported or menu-only provider. DeepSeek publishes each returned currency as a separate exact balance segment and reports when the API is unavailable. Fireworks publishes exact per-currency rated spend totals and reports when no rated usage exists. Moonshot AI publishes the available balance with its region-native currency. Vercel AI Gateway publishes the exact current USD credit balance. MiniMax publishes Token Plan window percentages or the regional pay-as-you-go available balance. Baseten publishes the exact trailing 30-day Model APIs net subtotal after credits. xAI is always menu-only and never starts a scheduled status refresh. Z.AI statusline usage refreshes every five minutes while the selected model remains on Z.AI.

Queries for another provider or all providers never publish their results 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.

🔒 Security and privacy

Credential candidates are collected synchronously in memory and are not cached, persisted, logged, formatted, or appended to the Pi session. The protocol carries no account name or extension identity. Only the selected provider's exact runtime match is used, and secrets are sent only to its validated official origin. DeepSeek balance requests require Bearer authentication, send only that resolved credential from Pi's runtime auth to https://api.deepseek.com/user/balance, and refuse redirects. Fireworks spend requests send only that resolved credential to the official https://api.fireworks.ai account-listing and billing-summary endpoints and refuse redirects. Moonshot balance requests send only the resolved Bearer credential to the matching official Global or China balance origin and refuse redirects. Vercel AI Gateway credit requests send only the resolved Bearer credential to https://ai-gateway.vercel.sh/v1/credits and refuse redirects. MiniMax usage requests send only the resolved API key to one deterministic endpoint on the matching official Global or China API root and refuse redirects. Baseten billing requests send only the resolved Bearer credential to https://api.baseten.co/v1/billing/usage_summary for an official Baseten model and refuse redirects. Pi extensions run with the user's process privileges, so the shared event bus is not a security boundary between installed extensions. Install only trusted extensions because they can read user files and process memory. Protocol v1 interoperability is characterized for the repository's supported Pi runtime. An absent or incompatible peer preserves standalone fallback and fail-closed mismatch behavior.

🚧 Limitations

• Only providers with a meaningful usage source and verifiable Pi runtime auth are supported.
• GitHub Copilot quota, Kimi managed usage, Z.AI quota, and OpenAI Codex reset redemption rely on provider-owned endpoints that may change without notice.
• Codex reset redemption requires a current ChatGPT OAuth credential from Pi's login or a compatible credential source; Codex API keys cannot redeem earned subscription resets.
• xAI usage supports only a uniquely matched Pi OAuth subscription credential; xAI API keys and Management API credentials are unsupported.
• 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.
• DeepSeek reports current API balance only; it does not expose historical usage, quota windows, reset times, or account-wide token totals through the balance endpoint.
• Fireworks reports rated 30-day spend only; credit balance and spend caps are visible only in the Fireworks web console, and /usage must select one visible account before querying a multi-account key.
• Moonshot AI reports current API balance only; it does not expose historical spend, aggregate token usage, quota windows, or reset times through the balance endpoint.
• Vercel AI Gateway reports current team credits and lifetime spend only; Custom Reporting and request-rate counters are not queried.
• MiniMax Token Plan field semantics have changed over time; contradictory counts and percentages are reported as unavailable rather than guessed.
• Baseten reports organization-wide Model APIs spend, not usage attributable only to Pi's current key; Dedicated and Training spend are excluded.
• 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
│   ├── usage-settings-ui.ts # Pi SettingsList interaction and save rollback
│   ├── 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
│   ├── usage-targets.ts # Provider-neutral target resolution and safe picker descriptors
│   ├── query.ts       # Runtime auth resolution and bounded provider queries
│   ├── oauth-credential-source.ts # Ephemeral OAuth candidate collection
│   ├── 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/     # Provider-specific usage 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, DeepSeek API balance, DeepSeek balance, Fireworks API spend, Fireworks rated spend, Vercel AI Gateway credits, Vercel AI Gateway usage, Baseten Model APIs spend, Baseten usage, OpenAI Codex usage, ChatGPT subscription limits, Kimi For Coding, Kimi Coding Plan usage, Moonshot AI balance, Moonshot API balance, MiniMax Token Plan, MiniMax API balance, GitHub Copilot AI credits, GitHub Copilot premium requests, OpenRouter credits, xAI OAuth usage, Grok subscription allowance, API-key spend limits, TypeScript Pi package, npm Pi extension.

📄 License

MIT. See LICENSE.