@kaishin/pi-usage

Pi extension that surfaces per-provider token-usage and quota status in the footer, plus a /usage command and dashboard. Restored from pi-quotas with MiniMax support.

Packages

Package details

extension

Install @kaishin/pi-usage from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@kaishin/pi-usage
Package
@kaishin/pi-usage
Version
2.1.0
Published
Sep 11, 2026
Downloads
333/mo · 333/wk
Author
kaishin
License
MIT
Types
extension
Size
241.3 KB
Dependencies
0 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./src/extensions/core/index.ts",
    "./src/extensions/command-quotas/index.ts",
    "./src/extensions/command-tokens/index.ts",
    "./src/extensions/usage-status/index.ts",
    "./src/extensions/token-status/index.ts",
    "./src/extensions/quota-warnings/index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@kaishin/pi-usage

Pi extension that surfaces per-provider token-usage and quota status in the footer, plus a /usage command and dashboard. Restores the full provider set and TUI from upstream pi-quotas and adds MiniMax support via PR #41.

Supported providers

Anthropic, OpenAI Codex, GitHub Copilot, OpenRouter, Synthetic, Grok, Z.ai, OpenCode Go, Kimi Code, Ollama Cloud, and MiniMax.

Install

pi install npm:@kaishin/pi-usage
# or from source
pi install /path/to/pi-usage

After install, register credentials once per provider, e.g.:

pi /login minimax
# paste MINIMAX_API_KEY (or set MINIMAX_API_KEY env var)

Restart or /reload to load the extension.

Commands

Command Description
/usage Combined dashboard for all configured providers
/anthropic:usage Anthropic usage only
/codex:usage OpenAI Codex usage only
/github:usage GitHub Copilot usage only
/openrouter:usage OpenRouter usage only
/synthetic:usage Synthetic usage only
/grok:usage Grok usage only
/zai:usage Z.ai usage only
/opencode-go:usage OpenCode Go usage only
/kimi:usage Kimi Code usage only
/ollama:usage Ollama Cloud usage only
/minimax:usage MiniMax usage only
/tokens Cross-session token/cost usage
/usage:settings Toggle features on or off

Features

Dashboard

/usage opens a bordered TUI view showing all configured providers side by side with progress bars, used/remaining counts, and reset times. Hourly and weekly bars include a | at the current elapsed time so you can tell if usage is ahead of or behind pace. Press r to refresh, q or Esc to close.

Footer status

When the active model is from a supported provider, the Pi footer shows real-time quota headroom refreshed every 60 seconds and on each turn.

Quota warnings

Automatic warning notifications when usage or the current pace risks exhausting a quota before reset. Severity increases are reported immediately; unchanged risks repeat at most once per hour.

Settings

/usage:settings toggles:

  • Combined /usage command
  • Per-provider /...:usage commands
  • Footer usage status
  • Token usage status and /tokens
  • Quota warning notifications
  • Defer to Synthetic — hide the Synthetic footer when pi-synthetic is also showing usage

Settings are saved to ~/.pi/agent/extensions/usage.json (global) or .pi/usage.json (per-project). Run /reload after changing command visibility.

Test

npm install
npm run check   # tsc --noEmit
npm test        # vitest run

Origin

Restored from the upstream @latentminds/pi-quotas PR #41, renamed to /usage and usage.json, and retargeted to the current @earendil-works/pi-coding-agent / @earendil-works/pi-tui API.

License

MIT