@jetserge/pi-usage-bars

Quota, balance, and spend indicators for Pi.

It adds:

• a footer status bar for the active supported provider
• a /usage command showing configured quota, balance, and spend data

Supported providers

JetBrains Central takes precedence when the active model points at Central's local Wire proxy, or directly at the JetBrains AI Platform LLM routes that a Central session pays for. The footer shows the monthly Central credit limit as M and today's locally tracked spend against a configurable daily limit as D. Both bars include dollar amounts and reset countdowns. This applies to Anthropic, OpenAI, OpenAI Codex, and any future provider routed through the same proxy marker.

For the new openai ChatGPT login, the footer shows ChatGPT plan, not quota percentages. /usage links to ChatGPT usage settings. This token cannot query the legacy Codex quota endpoint. API-key accounts stay hidden, and the extension never silently substitutes a legacy Codex account's quota. The openai-codex provider keeps its existing quota bars.

To show Codex-style shared-plan bars while using openai, explicitly confirm that both OAuth logins use the same ChatGPT account and workspace, then save their openaiQuotaLink(openaiToken, codexToken) fingerprint (exported by extensions/usage-bars/core.ts) as openaiCodexQuotaLink in ~/.pi/agent/usage-bars.json. Compute it locally without printing or saving the tokens. This is a user-confirmed link, not automatic account verification.

The extension resolves both credentials through Pi and uses only the Codex token for quota requests. The fingerprint binds the OpenAI client and subject to the Codex subject and workspace. Token refresh preserves it. Changing either identity disables polling until the link is confirmed and recreated. Remove openaiCodexQuotaLink to unlink. These bars show the shared plan, not Pi's separate per-app cap, which remains available in ChatGPT settings.

DeepSeek shows total, topped-up, and granted balances in the currency returned by the API. Moonshot shows available, cash, and voucher balances; this is separate from the Kimi For Coding subscription provider. Pi uses MOONSHOT_API_KEY for both Moonshot regions, so /usage automatically hides the expected authentication failure from the region where a shared environment key is not valid.

OpenRouter shows the account credit balance and current daily, weekly, and monthly key spend. If the API key has a configured credit limit, that limit is also rendered as a usage bar with the amount used and the limit, for example 75% $15/$20. Baseten shows current calendar-month credits used, aggregated across its documented dedicated, training, and Model APIs billing categories; it does not invent a remaining-balance or quota percentage.

Vercel AI Gateway shows the team's remaining AI Gateway Credits balance and lifetime spend. Fireworks shows account-wide rated spend for the current UTC calendar month. Its high default monthly-spend quota is not treated as a useful budget percentage. xAI shows the team's prepaid balance and current billing-cycle spend.

MiniMax Subscription Keys can represent an active Token Plan, purchased Credits, or both. The extension shows quota windows when present and a neutral credit-balance line if a first-party key-authenticated response exposes points_balance/credits_balance. MiniMax currently exposes Credits-only balances through a console endpoint requiring browser-cookie authentication, so a key-only Credits account is shown as “No active Token Plan” with a direction to check the console rather than a fabricated percentage. The extension does not import browser cookies.

Google Gemini CLI and Google Antigravity are not supported because Pi removed those built-in providers in version 0.71.0. Pi 1.3.0 also adds the TypeSafe classifier, which is not an active chat model monitored by the footer. The reviewed TypeSafe and Xiaomi MiMo documentation does not describe a key-authenticated account-usage endpoint, so neither is currently supported; see provider support research.

Requirements

• Pi 0.84.2 or newer (tested with Pi 1.3.0)
• Node.js 22.19 or newer when using the npm-distributed Pi CLI
• JetBrains Central CLI on PATH to show Central usage for a routed model

Authenticate direct providers through Pi's /login command. The extension resolves those credentials through Pi's provider API and does not read or write auth.json. For a Central-routed model, it runs central limit --json and does not use the direct provider credential.

xAI keeps inference and billing credentials separate. After authenticating Pi's normal xai provider, configure usage reporting with a read-only, team-scoped Management Key:

/login pi-usage-bars-xai-management

Select xAI Management (pi-usage-bars) and paste the key into Pi's secret prompt. For headless or CI use, XAI_MANAGEMENT_KEY is also accepted from the environment. Organization-scoped Management Keys are not selected or aggregated automatically.

Install

Install the npm package:

Remove the upstream package first if it is already installed. Both packages own /usage and cannot load together:

pi remove npm:@hk_net/pi-usage-bars

pi install npm:@jetserge/pi-usage-bars

Or install the latest source directly from GitHub:

pi install https://github.com/CrazyCoder/pi-usage-bars

Restart Pi after installation, or use /reload when the package is already installed.

Update an existing npm installation with:

pi update npm:@jetserge/pi-usage-bars

Use

Footer usage bars

When the active model belongs to a configured supported provider, the footer shows its available quota windows with reset countdowns. A Central-routed model always uses the monthly Central credit limit instead of the underlying provider's direct subscription quota.

When a provider reports the amounts behind a quota window, the footer and /usage show them next to the percentage: the OpenRouter key limit in the reported currency ($15/$20), and Kimi and MiniMax windows as plain counts (50/200). Kimi and MiniMax do not document what those counts measure, so they carry no unit. The footer abbreviates amounts from 10,000 upward (12.5K); /usage shows them in full.

The footer only shows a provider's quota when the model actually calls that provider. If models.json points a supported provider at another host, such as a local proxy or LiteLLM, the footer stays empty instead of showing a quota that the request does not spend. OpenRouter regional hosts such as us.openrouter.ai count as OpenRouter.

A model routed to OpenRouter (openrouter.ai, *.openrouter.ai) or Vercel AI Gateway (ai-gateway.vercel.sh) under any other provider ID shows that gateway's usage instead. The footer then queries the gateway with the key Pi sends for that model, not the key configured for the openrouter or vercel-ai-gateway provider, so it reports the account the model actually spends. /usage still lists every configured account with its provider credentials.

Usage refresh runs in interactive TUI sessions every two minutes. It does not run in print, JSON, or RPC mode. Run /central-quota to refresh a Central-routed model immediately.

Central daily limit

The Central daily bar defaults to $50. Show or change it from Pi:

/central-daily-limit
/central-daily-limit 75

The command writes the same setting that can be edited by hand in ~/.pi/agent/usage-bars.json:

{
  "centralDailyLimitUsd": 75
}

Central exposes the current allowance total but no daily breakdown. The extension therefore stores the last observed total in ~/.pi/agent/usage-bars-central-state.json and sums positive changes during the local calendar day, matching JBCentralGUI's snapshot method. The first observation is a baseline, so the daily amount becomes complete after the extension has observed usage from the start of a day. An account switch or a new allowance period establishes a new baseline instead of counting the new total as today's spend.

/usage

Run /usage to open a searchable list of configured supported providers. The selected provider's details are expanded; use the configured selection and page-navigation keybindings to browse the bounded list.

--usage

Pass --usage to print one JSON line for the active model provider and exit without opening the usage UI. This is also useful as a loader and credential smoke test:

pi --no-extensions -e C:\hk\code\pi-usage-bars\extensions\usage-bars\index.ts --usage

The result has status set to ok, unconfigured, unsupported, or error. A supported provider routed through another host reports unsupported, unless the host is a supported gateway. No credential is included in the output.

Endpoint configuration

First-party monitoring endpoints can be overridden:

Security: the corresponding provider token is sent as a bearer token to the configured endpoint. Only override endpoint variables with an endpoint you trust. PI_FIREWORKS_ACCOUNT_ID selects an account already returned by Fireworks account discovery; it may be either the account slug or its accounts/<slug> resource name. When a key can access multiple accounts, this variable is required rather than guessing or aggregating across accounts.

The Codex and Claude usage endpoints are fixed to their first-party services. Claude responses are cached briefly in the system temporary directory to coordinate multiple Pi processes and reduce rate limiting. The cache contains usage values, not credentials. Central usage comes from the local central executable.

Financial metrics roadmap

Quota percentages and monetary account data have different meaning and color semantics. OpenRouter, DeepSeek, Moonshot, MiniMax, Vercel AI Gateway, Fireworks, and xAI financial data are rendered as neutral account values; percentages are used only when an actual limit exists.

Future: Qwen Token Plan

Qwen Token Plan Individual has a documented seven-day Credits quota, but Qwen currently directs users to console usage details and prohibits API-key automation. Add Qwen support only when Qwen documents and authorizes a key-authenticated usage endpoint compatible with Pi's resolved sk-sp-… credential. Do not use browser cookies or console-session tokens. The endpoint must expose used Credits, quota limit, reset time, and any separate Credit Pack balance; validate it with redacted fixtures before implementation.

See provider support research for the supporting Qwen investigation.

Development

Install Node.js 22.19+ and Bun 1.3, then run:

npm install
npm run check

npm run check performs a strict TypeScript check and runs the Bun test suite.

Maintainers should follow the release guide. The first npm version is published manually; later tagged releases use npm trusted publishing through GitHub Actions.

Credits

This extension is based on and inspired by:

• hknet/pi-usage-bars, the upstream project

• CodexBar

• rho usage-bars

• ajarellanod/pi-usage-bars

This fork adds route-aware JetBrains Central usage and publishes under the @jetserge npm scope.