# pi-usage-bars

Quota, balance, and spend indicators for [Pi](https://github.com/earendil-works/pi).

![Codex footer bar](https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/codex.png)

It adds:

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

## Supported providers

| Provider | Pi provider ID | Authentication |
| --- | --- | --- |
| OpenAI Codex | `openai-codex` | ChatGPT subscription OAuth |
| Anthropic Claude | `anthropic` | Claude Pro/Max OAuth |
| ZAI Coding Plan (Global) | `zai` | ZAI API key |
| ZAI Coding Plan (China) | `zai-coding-cn` | ZAI China API key |
| Kimi For Coding | `kimi-coding` | Kimi Coding Plan API key |
| MiniMax Coding Plan (Global) | `minimax` | MiniMax Global API key |
| MiniMax Coding Plan (China) | `minimax-cn` | MiniMax China API key |
| OpenRouter | `openrouter` | OpenRouter API key |
| DeepSeek | `deepseek` | DeepSeek API key |
| Moonshot/Kimi API (Global) | `moonshotai` | Moonshot Global API key |
| Moonshot/Kimi API (China) | `moonshotai-cn` | Moonshot China API key |

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.

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.

## Requirements

- Pi 0.81.1 or newer (tested with the current Pi 0.83.0 release)
- Node.js 22.19 or newer when using the npm-distributed Pi CLI

Authenticate providers through Pi's `/login` command. The extension resolves credentials through Pi's provider API; it does not read or write `auth.json` itself.

## Install

Install the npm package:

```bash
pi install npm:@hk_net/pi-usage-bars
```

Or install the latest source directly from GitHub:

```bash
pi install https://github.com/hknet/pi-usage-bars
```

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

Update an existing npm installation with:

```bash
pi update npm:@hk_net/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 when provided by the service.

![Claude footer bar](https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/claude.png)

Usage refresh runs in interactive TUI sessions every two minutes. It does not run in print, JSON, or RPC mode.

### `/usage`

Run `/usage` to open a searchable list of configured supported providers.

![/usage command](https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/usage-command.png)

## Endpoint configuration

First-party monitoring endpoints can be overridden:

| Variable | Default |
| --- | --- |
| `PI_ZAI_USAGE_ENDPOINT` | `https://api.z.ai/api/monitor/usage/quota/limit` |
| `PI_ZAI_CODING_CN_USAGE_ENDPOINT` | `https://open.bigmodel.cn/api/monitor/usage/quota/limit` |
| `PI_KIMI_USAGE_ENDPOINT` | `https://api.kimi.com/coding/v1/usages` |
| `PI_MINIMAX_USAGE_ENDPOINT` | `https://api.minimax.io/v1/token_plan/remains` |
| `PI_MINIMAX_LEGACY_USAGE_ENDPOINT` | `https://api.minimax.io/v1/api/openplatform/coding_plan/remains` |
| `PI_MINIMAX_CN_USAGE_ENDPOINT` | `https://api.minimaxi.com/v1/token_plan/remains` |
| `PI_MINIMAX_CN_LEGACY_USAGE_ENDPOINT` | `https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains` |
| `PI_OPENROUTER_CREDITS_ENDPOINT` | `https://openrouter.ai/api/v1/credits` |
| `PI_OPENROUTER_KEY_ENDPOINT` | `https://openrouter.ai/api/v1/key` |
| `PI_DEEPSEEK_BALANCE_ENDPOINT` | `https://api.deepseek.com/user/balance` |
| `PI_MOONSHOT_BALANCE_ENDPOINT` | `https://api.moonshot.ai/v1/users/me/balance` |
| `PI_MOONSHOT_CN_BALANCE_ENDPOINT` | `https://api.moonshot.cn/v1/users/me/balance` |

**Security:** the corresponding provider token is sent as a bearer token to the configured endpoint. Only override these variables with an endpoint you trust.

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.

## Financial metrics roadmap

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

## Development

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

```bash
npm install
npm run check
```

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

Maintainers should follow the complete [release and npm publication guide](docs/releasing.md): prepare the release, stage it for npm browser approval, then finalize it after 2FA approval. Pushing a Git tag does not publish automatically.

## Credits

This extension is based on and inspired by:

- [CodexBar](https://github.com/steipete/CodexBar)
- [rho usage-bars](https://github.com/mikeyobrien/rho/tree/main/extensions/usage-bars)
- [ajarellanod/pi-usage-bars](https://github.com/ajarellanod/pi-usage-bars)