Real-time AI Provider Balance for pi Coding Agent Display your API provider credit balance right in the pi status bar
---
## π Features
pi-balance is an **extension** for the [pi coding agent](https://github.com/earendil-works/pi-coding-agent) that automatically fetches and displays your AI provider's API credit balance in the pi **status bar**.
- β **Auto-detects** your currently active model provider
- β **Event-driven refresh** β balance updates automatically after each conversation (with delta display β²βΌ)
- β **Live updates** on provider/model switch
- β **Multi-provider support** β DeepSeek, Moonshot/Kimi, OpenRouter, Sub2Api, OpenAI Codex (and compatible APIs)
- β **Zero configuration for balance APIs** β supported balance APIs work from existing model headers
- β **Graceful fallback** β quietly hides when balance info is unavailable
- β **i18n support** β English and Simplified Chinese, with `/balance lang ` command
## π¦ Installation
### Option 1: Install from npm (Recommended)
```bash
pi install npm:pi-balance
```
### Option 2: Install from GitHub
```bash
pi install git:github.com/DragonYH/pi-balance
```
### Option 3: Local Development
```bash
git clone https://github.com/DragonYH/pi-balance.git
cd pi-balance
npm install
npm run build
pi install ./
```
### Verify Installation
Restart pi. You should see the balance indicator appear in the status bar once you connect to a supported provider.
## π Supported Providers
| Provider | Balance Endpoint | Display |
|----------|--------------------------|---------|
| **DeepSeek** | `/user/balance` | Β₯ (CNY) balance |
| **Moonshot / Kimi** | `/v1/users/me/balance` | Β₯ (CNY) available balance |
| **Sub2Api** | `/usage` | $ (USD) remaining balance |
| **Compatible APIs** | `/usage`, `/v1/usage` | $ (USD) remaining balance |
| **OpenAI Codex** | ChatGPT Codex usage API / `codex app-server` | 5-hour and weekly usage remaining |
| **OpenRouter** | `/v1/credits` | $ (USD) remaining credits |
> The extension automatically detects which provider you're using based on your current model configuration β no manual setup required.
## π Usage
Once installed, pi-balance works **completely automatically**:
1. **On session start** β it fetches your balance immediately
2. **On model switch** β it re-fetches for the new provider
3. **After each conversation** (`agent_end`) β automatically refreshes and shows balance delta (β²βΌ)
The balance is displayed in the **status bar** at the bottom of your pi terminal:
```
DeepSeek: Β₯49.87
```
> If the extension cannot determine your balance (e.g., unsupported provider or network issue), the status bar entry is gracefully hidden.
### `/balance` Command
Run `/balance` to open an interactive configuration menu. You can:
- View support status for configured providers
- Expand/collapse providers to toggle display and extra options
- Enable/disable **Sub2Api** sub-providers inline (with auto-discovery)
- Toggle **Codex CLI fallback** on/off
- Refresh the current status immediately
You can also use command arguments directly:
```bash
/balance status
/balance refresh
/balance enable deepseek
/balance disable moonshot
/balance toggle codex
/balance toggle openrouter
/balance toggle sub2api
/balance sub2api # Open Sub2Api sub-provider menu
/balance sub2api rescan # Re-scan for new Sub2Api providers
/balance lang zh-CN # Switch to Simplified Chinese
/balance lang en # Switch to English
```
### Configuration Notes
- **Provider display toggles** are saved by the `/balance` menu and apply on the next refresh.
- **Custom Sub2Api providers** are discovered from your pi model configuration (`~/.pi/agent/models.json`) and can be enabled/disabled individually from the main menu or `/balance sub2api`. Use `/balance sub2api rescan` after changing model configuration.
- **OpenAI Codex usage** is shown only while the active model provider is `openai-codex`. The extension first reuses pi's Codex subscription auth headers and can fall back to `codex app-server --listen stdio://` when available; the CLI fallback can be toggled in the `/balance` menu.
- The menu caches support states intelligently: expanding/collapsing providers is instant (no recomputation), while config changes trigger automatic refresh.
- Network requests time out quickly and failures are hidden from the status bar instead of interrupting your session.
## π§ How It Works
```
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β pi Coding Agent β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β β β
β β [Chat Interface] β β
β β β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€ β
β β Status Bar: DeepSeek: Β₯49.87 β Connected β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β ββ Extension: pi-balance ββββββββββββββββββββββββββββββββ β
β β session_start βββΊ fetchBalance() βββΊ setStatus() β β
β β model_select βββΊ fetchBalance() βββΊ setStatus() β β
β β agent_end βββββΊ refreshBalance(showDelta) β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
### Events Handled
- **`session_start`** β initial balance fetch when a session begins
- **`model_select`** β re-fetch when you switch models/providers
- **`agent_end`** β refresh balance after each conversation, showing delta (β²βΌ)
- **`session_shutdown`** β cleanup and clear status
## ποΈ Project Structure
```
pi-balance/
βββ src/
β βββ index.ts # Entry point, commands, lifecycle
β βββ types.ts # Type definitions and constants
β βββ config.ts # Config load/persist/toggle
β βββ utils.ts # Helpers (fetch, JSON, type guards)
β βββ menu.ts # Dynamic menu builder with caching
β βββ providers/
β βββ types.ts # BalanceProvider interface
β βββ registry.ts # Singleton provider registry
β βββ deepseek.ts # DeepSeek provider
β βββ moonshot.ts # Moonshot/Kimi provider
β βββ openrouter.ts # OpenRouter provider
β βββ sub2api.ts # Sub2Api + auto-discovery
β βββ codex.ts # OpenAI Codex + CLI fallback
β βββ i18n/
β βββ index.ts # t() function + language detection
β βββ zh-CN.ts # Chinese translations
β βββ en.ts # English translations
βββ tests/
β βββ index.test.ts
βββ LICENSE # MIT license
βββ README.md # English documentation
βββ README.zh-CN.md # Chinese documentation
βββ package.json # Node.js and pi package manifest
βββ tsconfig.build.json # Build configuration
βββ tsconfig.json # TypeScript configuration
```
## π οΈ For Developers
### Type-Checking
```bash
npm run typecheck
```
### Build
```bash
npm run build
```
### Test
```bash
npm test
```
### Publish Checklist
This project publishes through GitHub Actions when a version tag is pushed.
Before publishing, verify the package contents:
```bash
npm pack --dry-run
```
Then create and push a tag that matches `package.json`:
```bash
git tag vX.Y.Z
git push origin vX.Y.Z
```
Before pushing the tag, configure npm Trusted Publishing for this package:
- Publisher: GitHub Actions
- Owner: `DragonYH`
- Repository: `pi-balance`
- Workflow: `release.yml`
- Environment: leave empty unless you add one to the workflow.
### Adding a New Provider
The extension uses a pluggable provider architecture. To add support for a new provider, create a module in `src/providers/` that implements the `BalanceProvider` interface, then import it in `src/index.ts` to trigger auto-registration:
```typescript
// src/providers/yourprovider.ts
import type { BalanceProvider } from "./types.js";
import { registry } from "./registry.js";
import type {
BalanceResult,
BalanceConfig,
FetchContext,
ProviderSupport,
} from "../types.js";
import { getJson } from "../utils.js";
export const yourProvider: BalanceProvider = {
key: "yourprovider",
definition: {
key: "yourprovider",
label: "YourProvider",
color: "#FFD700",
},
shouldTry(model, baseUrl) {
return baseUrl.includes("yourprovider.com");
},
async fetchBalance(
ctx: FetchContext,
signal?: AbortSignal,
): Promise {
const data = await getJson(`${ctx.baseUrl}/your/endpoint`, ctx.headers, signal);
const amount = data?.credits_remaining;
return typeof amount === "number" ? { amount, unit: "$" } : undefined;
},
async getSupport(
ctx: ExtensionContext,
config: BalanceConfig,
): Promise {
return {
provider: this.definition,
configured: true,
details: ["Configured"],
};
},
};
registry.register(yourProvider);
```
Then add one import in `src/index.ts`:
```typescript
import "./providers/yourprovider.js";
```
That's it β the provider auto-registers, appears in the `/balance` menu, and participates in balance fetching. No other code changes needed.
## π License
[MIT](./LICENSE)
---
