@tzlzl/pi-usage0.1.0

📊 @tzlzl/pi-usage — Native Quota Panels for Pi

Fork of @narumitw/pi-usage 0.61.1. Published only on npm as @tzlzl/pi-usage. There is no GitHub repository for this fork. Original copyright and MIT license are preserved.

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 current-provider usage as persistent conversation output, or all/single configured providers through /usage.
• Reports subscription allowances, API balances, and spending for the supported providers listed below without mixing their billing semantics.
• Toggles persistent Codex Fast routing through /fast.
• Redeems eligible Codex resets only after selecting a banked reset, reviewing its actual scope/expiration/consumption, and explicitly confirming.
• 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, waits for compatible pending account activation, and validates the effective provider endpoint before sending them.

📦 Install

This local fork is tested with Pi 0.99.2 and Node.js 26; Node.js 22 or newer is required by the package. Older Pi versions are not verified for this fork. Host Pi libraries remain peer dependencies and are not bundled. The upstream v1 credential-source protocol was characterized against Pi 0.84.3; compatible credential owners remain optional.

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

Install and pin it through Pi's package manager:

pi install npm:@tzlzl/pi-usage@0.1.0

Do not also leave a copy in ~/.pi/agent/extensions/; Pi would load both.

To use the generated archive elsewhere, extract it first (it already contains dist/index.ts):

mkdir -p ~/pi-usage-local
tar -xzf pi-usage-local-0.61.1-local.3.tgz -C ~/pi-usage-local --strip-components=1
pi -e ~/pi-usage-local
# Optional permanent registration, only if it is not already discovered:
pi install ~/pi-usage-local

No build dependencies are required to load the prebuilt package in Pi. To develop or rebuild it:

cd ~/pi-usage-local
npm install
npm run check                 # Build, TypeScript, and standalone tests
npm pack --pack-destination . # Revalidates before creating the archive

The source directory includes package-lock.json for reproducible npm ci installs. npm omits this lockfile from tarballs, so extracted development copies use npm install. The archive includes source, generated runtime and maps, package-local build scripts, tests/fixtures, configuration, documentation, changelog, and license. It excludes node_modules, credentials, and existing archives. The build uses only package-local files; it does not rely on the original monorepo or temporary test-runner paths.

🚀 Quick start

Run /usage to report the selected model's provider quota in the conversation. Run /usage show for a scrollable overlay of all configured providers, or /usage show <provider> for one configured provider. Queries that need a billing target or fail remain explicitly visible; the extension does not silently pick a target. Run /fast to toggle Fast mode for a supported active Codex model.

Tab completion inserts the token only. Type a space after show to list configured providers; selecting one replaces the argument with /usage show <provider>. Automatically opening the next suggestion list after Tab is supported by the independent local pi-editor extension. It uses Pi's editor replacement API and does not require modifications to Pi core. This usage package alone does not change the editor.

💬 Commands

Command	Purpose
/usage	Report current-provider usage in the conversation; /usage show opens all configured providers; /usage show <provider> queries one. /usage reset opens eligible Codex banked resets.

/usage show and /usage reset require an interactive UI. /usage publishes the current report in the conversation. Provider names for show must identify a configured provider, and completion lists only those providers. Requests use the matched provider credentials; see Security and privacy. Codex Fast routing lives in the separate pi-codex-fast extension.

/usage reset requires the currently selected OpenAI Codex model and a freshly matched current ChatGPT OAuth account (Pi /login or compatible credential source); Codex API keys cannot redeem resets. It shows the actual available reset scope and expiration, then asks for confirmation before consuming it. After confirmation, cancellation cannot safely interrupt redemption. Missing provider targets are shown as requiring a target; no target is chosen silently. Read the query and reset guide for cancellation and safe retry behavior.

⚙️ Settings

Settings and provider target preferences are configured manually in pi-usage.json; the /usage command no longer exposes settings, target selection, or Fast mode.

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 must be configured manually; /usage reports a missing required target without selecting one silently. 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

Fast routing moved to the separate pi-codex-fast extension and its /fast command. An old codexFastMode value in this file is ignored so existing files stay valid.

Codex statusline percentage

The codexStatusPercentage preference accepts "remaining" or "used" and defaults to "remaining" to preserve existing output. Set the field manually and run /reload:

{
  "codexStatusPercentage": "used"
}

With "used", a limit with 70% remaining appears as 30%; its reset countdown or window label stays unchanged. This preference changes only Codex statusline formatting, not provider data or the detailed /usage report.

Codex statusline reset countdown

The codexStatusResetCountdown preference defaults to true. It replaces the window labels with the time remaining until each returned limit resets. Set it to false in pi-usage.json and run /reload to restore the legacy 5h and wk labels:

{
  "codexStatusResetCountdown": false
}

📋 Provider semantics

Usage is provider-specific: a subscription allowance, current balance, and rated spend are not interchangeable. Currencies and billing targets remain separate.

Provider	Reported data
OpenAI Codex	Subscription windows, credits, resets, and model buckets
Kimi For Coding	Plan request windows and a separate booster wallet
Moonshot AI Global/China	Current API balance in USD/CNY
MiniMax Global/China	Token Plan windows or pay-as-you-go API balance
GitHub Copilot	AI credits, premium requests, or Free-plan chat allowance
OpenRouter	Per-key credit limits and spending windows
DeepSeek	Exact current CNY and USD API balances
Fireworks	Rated trailing 30-day spend for one selected account
Vercel AI Gateway	Team credit balance and lifetime spend
Baseten	Organization-wide trailing 30-day Model APIs spend after credits
OpenCode Go	Rolling, weekly, and monthly plan windows
xAI	OAuth subscription allowance and credits; explicit usage commands only
Z.AI	Coding Plan quota windows, MCP allowance, plan name, and renewal date

Read the provider reference for provider IDs, exact endpoints, authentication requirements, normalization rules, statusline examples, limitations, and pinned contract evidence. Codex reset redemption requires a freshly matched current OAuth account and explicit confirmation; custom or proxy origins fail before mutation.

🧭 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 queries a provider target only when one is already configured or unambiguous. It never flattens targets into provider rows or aggregates visible targets. A missing choice is reported and must be configured manually in pi-usage.json. A compatible credential owner may offer the verified active named account through the versioned process-local protocol without exposing its account label or storage. When that owner is still activating the requested provider in the current session, /usage waits through the extension-neutral oauth:credential-readiness:v1 protocol before collecting the synchronous credential offer. 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 explicit-query-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 does not publish the native usage status chip. The same refresh still queries it and emits the remaining allowance or prepaid balance on pi-usage:footer, for example 75% or $0.00. 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.

Local pi-footer integration

The independent pi-footer extension consumes display-only snapshots on pi-usage:footer and can request the latest current-session snapshot on pi-usage:footer-request with { sessionId }. Version 1 snapshots include the session/provider/model IDs, query state, compact remaining text, remaining/usage/unavailable semantics, and optional remaining percentage and capture time. pi-footer renders that text directly; it does not add a rest prefix. Account labels, authentication, fingerprints, provider request details, and report notes are not included.

These snapshots reuse already validated query results: no additional provider requests are made. They always format remaining percentages, regardless of codexStatusPercentage, omit reset countdowns to keep the footer compact, and label rated spending as usage rather than balance. The native usage status item remains available for other footer implementations. Snapshots are cleared during refresh and session shutdown; replay requests must match the current active session.

🔄 Migrating from pi-codex-usage

The upstream pi-codex-usage package is deprecated; its archived source is not included in this standalone fork. To migrate one installation:

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

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

Behavior changes:

• Use /usage for usage management; /codex-status is no longer registered.
• Use /usage show [provider] for cross-provider reports; the former settings/target menu actions are no longer part of /usage.
• 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 after any compatible readiness promises settle, and are not cached, persisted, logged, formatted, or appended to the Pi session. The protocols carry 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

pi-usage-local/
├── src/                               # Provider adapters, auth, settings, and presentation
│   ├── index.ts                       # Thin Pi entrypoint
│   └── usage.ts                       # Provider queries, cache, and command flows
├── dist/                              # Generated Jiti runtime
├── scripts/                           # Package-local build tooling
│   ├── build-runtime.mjs              # Runtime builder wrapper
│   └── runtime-builder.mjs            # Self-contained build implementation
├── docs/                              # Published reference documentation
└── test/                              # Behavior and lifecycle coverage

src/index.ts forwards the default factory from usage.ts and retains the package's named helper exports; other source modules are internal. The generated runtime is built from src/index.ts 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.