@master.g/pi-usage-hud

Persistent pi HUD showing the subscription usage of the current model's provider (Codex, Kimi, Zhipu)

Packages

Package details

extension

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

npm repohome report
$ pi install npm:@master.g/pi-usage-hud
Package
@master.g/pi-usage-hud
Version
0.2.0
Published
Oct 16, 2026
Downloads
418/mo · 418/wk
Author
master.g
License
MIT
Types
extension
Size
63.8 KB
Dependencies
0 dependencies · 1 peer
Pi manifest JSON
{
  "extensions": [
    "./index.ts"
  ]
}

Security note

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

README

@master.g/pi-usage-hud

A small pi extension that keeps the subscription usage of the current model's provider pinned in the HUD, so you always know how much of your plan is left before the next request.

Supported providers

Provider What is shown Auth source
codex ChatGPT plan main rate limit (model-specific entries like Codex Spark are intentionally ignored) pi's openai-codex OAuth login
kimi Kimi Code subscription rolling windows API key from ~/.pi/agent/auth.json
zhipu Zhipu (GLM) quota API key from ~/.pi/agent/auth.json

Other providers show nothing — the HUD stays out of the way.

Install

pi install npm:@master.g/pi-usage-hud

Then restart pi. The HUD line appears once a supported provider is active.

Behavior

  • One snapshot file per provider at ~/.pi/agent/<provider>-quota.json, shared across all pi sessions so the API is never hammered.
  • A cooldown window skips the network call when the last successful fetch is fresh enough.
  • On fetch errors the last-good usage is preserved — the HUD never blanks out.
  • Snapshots are provider-namespaced, so switching providers and back keeps each one's data.

Adding a provider

Each provider is a module exporting a ProviderAdapter (see provider.ts):

  1. Add xxx.ts exporting a ProviderAdapter.
  2. Register it in the PROVIDERS array in index.ts.

Development

bun install        # or npm install
bun test           # self-contained assert-based tests
bun run typecheck  # tsc --noEmit

The extension is plain TypeScript loaded by pi's jiti runtime — no build step, the published package ships sources.

License

MIT