pi-usage

English | 简体中文

An extension for Pi — a minimal agent harness — that shows AI provider usage and quota inside Pi.

Supports Z.ai / GLM Coding Plan, Kimi Coding Plan, DeepSeek, OpenRouter, and OpenCode Go. Each provider only appears when a matching one is configured in Pi. A configured provider whose query fails is still shown (marked error/stale); unconfigured ones are never rendered.

Honesty about API stability: this extension actively queries each provider's usage endpoints. Design principles: officially documented APIs only, and multi-provider by design — whichever providers you configure in Pi are the ones shown.

• DeepSeek (GET /user/balance) and OpenRouter (GET /api/v1/key, GET /api/v1/credits) are official documented APIs — stable, but their fields may still evolve.
• Z.ai endpoints (model-usage, tool-usage, quota/limit) are undocumented: derived from the official glm-plan-usage plugin and may change without notice.
• Kimi endpoint (GET /coding/v1/usages) is undocumented: it is the same endpoint the official Kimi Code CLI's built-in /usage command queries, and may change without notice.
• OpenCode Go usage endpoint (GET /zen/go/v1/usage) is undocumented: it reuses the same API key as the documented Go endpoints (/zen/go/v1/chat/completions, /zen/go/v1/responses; see docs) and may change without notice.
• OpenAI / Anthropic / Google Gemini are NOT supported: subscription-quota endpoints used by some plugins are undocumented private APIs (reverse-engineered from official CLIs) that can break or be blocked at any time — that risk is deliberately not taken here. Their admin usage APIs, in turn, require organization admin keys that are never used as chat provider keys.

If an endpoint breaks, the extension degrades gracefully (usage unavailable) and never affects model requests.

/usage
GLM/glm-5.3 (zai) — 5h 32% 2026-08-15 11:43:00 · MCP 18% 2026-08-27 09:43:00
Kimi/kimi-for-coding (kimi) — 5h 27% 2026-08-08 14:53:05 · Weekly quota 26% 2026-08-11 15:53:05

/usage zai
+-------------------+--------------+-----+--------------+-------+---------------------+
|                                 GLM/glm-5.3                                         |
|                        refreshed 2026-08-15 09:43:00                                |
+-------------------+--------------+-----+--------------+-------+---------------------+
| Quota             | Usage        | Pct | Used         | Left  | Resets              |
+-------------------+--------------+-----+--------------+-------+---------------------+
| MCP monthly quota | [##--------] | 18% | 180 / 1000   | 820   | 2026-08-27 09:43:00 |
|   web-search      | [##--------] | 22% | 220 / 1000   | 780   | —                   |
| 5-hour quota      | [###-------] | 32% | 5000 / 28000 | 23000 | 2026-08-15 11:43:00 |
+-------------------+--------------+-----+--------------+-------+---------------------+

Models (* = current):
  * glm-5.3                  5000  (32%)
    glm-5.2                   800  (5%)

status line (always auto-refreshed every 2 min)
GLM/glm-5.3 · 5h 32% · MCP 18% | Kimi/kimi-for-coding · 5h 27% · Weekly quota 26%

/usage pin (widget pinned above the editor, auto-refreshed)
┌─ pinned above the editor ──────────────────────────────────────────┐
│ GLM/glm-5.3 (zai) — 5h 32% 2026-08-15 11:43:00 · MCP 18% …    │
│ Kimi/kimi-for-coding (kimi) — 5h 27% · Weekly quota 26% …     │
└───────────────────────────────────────────────────────────────────────┘

Install

pi install npm:@imdlan/pi-usage

Update with pi update --extensions; remove with pi remove npm:@imdlan/pi-usage.

Requires Node.js 20+ and at least one supported provider configured in Pi:

• Z.ai / GLM Coding Plan — base URL at an official Z.ai / GLM endpoint, API key resolving to your GLM Coding Plan token.
• Kimi Coding Plan — the built-in kimi-coding provider at https://api.kimi.com/coding, authenticated via /login kimi-coding (OAuth) or a Kimi Code Console API key (KIMI_API_KEY).
• DeepSeek — base URL at https://api.deepseek.com, standard API key.
• OpenRouter — base URL at https://openrouter.ai, standard sk-or-v1-... key.
• OpenCode Go — a custom provider with base URL https://opencode.ai/zen/go/v1, using your Go API key from the console.

Commands

Command	Behavior	Auto-refresh?
/usage	Usage summary for all providers, with quota reset times (local time).	❌ One-time snapshot
/usage zai	Detailed Z.ai usage table: 5-hour quota, MCP monthly quota with per-tool breakdown, per-model usage.	❌
/usage kimi	Detailed Kimi Coding Plan usage table: 5-hour quota and weekly (7-day rolling) quota with reset times.	❌
/usage deepseek	DeepSeek balance per currency (CNY/USD) with granted / topped-up breakdown.	❌
/usage openrouter	OpenRouter key spend cap (used/remaining/reset) plus daily/weekly/monthly spend and account credits balance (USD).	❌
/usage opencode	OpenCode Go usage table: rolling 5-hour, weekly, and monthly quotas as percentages with reset times.	❌
/usage refresh	Force-refresh from the API, then render the summary. Keeps the last good snapshot on failure.	❌ Renders once
/usage status	Status line content, last refresh, cache state.	❌
/usage pin	Pin the summary widget above the editor. pin on / pin off set it explicitly; pin toggles.	✅ Every ~2 min

Key difference: plain /usage is a static snapshot. Only a pinned widget (/usage pin) stays fresh, re-rendered from cache every background cycle (~2 min, no extra API calls). Pin state is per-session. The footer status line is always auto-refreshed regardless.

The detail table is width-aware: narrow terminals drop optional columns (Resets → Left → Used → Usage bar), never overflowing.

Current model indicator

Wherever the provider name appears, the active model id is appended as Name/model (e.g. GLM/glm-5.3, Kimi/kimi-for-coding) — footer, summary, pinned widget, and detail table header. It follows model switches via /model, cycling (Ctrl+P), or session restore. The active model is matched by provider id first, then by base-URL host, so Pi entries like zai-coding-cn and kimi-coding map onto the zai and kimi usage providers.

Security & privacy

• Read-only: only queries usage.
• No secrets handled: auth resolves through Pi's getProviderAuth; never reads credential files or runs subprocesses.
• Locked-down networking: HTTPS only, host allowlist (api.z.ai, open.bigmodel.cn, dev.bigmodel.cn, api.kimi.com, opencode.ai), redirects rejected.
• No telemetry; all output sanitized.

Development

npm install
npm run typecheck   # strict tsc
npm test            # node:test via tsx

Zero runtime dependencies (Node built-ins + Pi Extension API). Pi loads the TypeScript entry directly — no build step.

Adding a provider: implement UsageProvider in src/providers/<name>.ts (auth strategy, allowlist, redaction rules), register in registry.ts + PROVIDER_HOSTS in index.ts, add tests (401/403/429/5xx, timeout, allowlist, redaction).

The Z.ai adapter mirrors the official glm-plan-usage plugin: endpoints derived from the configured base URL origin (model-usage, tool-usage, quota/limit). Parsing is isolated in src/providers/zai.ts.

The Kimi adapter queries GET /coding/v1/usages — the endpoint behind the official Kimi Code CLI's built-in /usage command. Parsing is isolated in src/providers/kimi.ts.

The OpenCode Go adapter queries GET /zen/go/v1/usage and reports the rolling / weekly / monthly windows as percentages; the documented base limits ($12 / $30 / $60) vary by model, so no dollar amounts are shown. Parsing is isolated in src/providers/opencode.ts.

Trademarks & disclaimer

• This project is not affiliated with, endorsed by, or sponsored by Z.ai / Zhipu AI, Moonshot AI / Kimi, DeepSeek, OpenRouter, OpenCode, or any other provider. Provider names and trademarks belong to their respective owners and are used only to identify the services being queried (nominative fair use).
• Usage queries are made read-only, with the credentials Pi already holds for the user's own account, at a low fixed rate (every 2 minutes). It is the user's responsibility to comply with each provider's terms of service.
• The Z.ai adapter references endpoint behavior of the upstream glm-plan-usage plugin (Apache-2.0, Zhipu AI). No upstream code is included in this repository.

License

Apache-2.0. Copyright © 2026 imdlan.