@wayner6/pi-usage

ChatGPT OAuth and CLIProxyAPI quota monitoring with local skill statistics for Pi and pi-web

Packages

Package details

extension

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

npm report

$ pi install npm:@wayner6/pi-usage

Package: @wayner6/pi-usage
Version: 0.3.0
Published: Oct 2, 2026
Downloads: 749/mo · 147/wk
Author: wayner6
License: MIT
Types: extension
Size: 87.6 KB
Dependencies: 0 dependencies · 2 peers

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

Pi Usage

ChatGPT OAuth and CLIProxyAPI quota windows, reset times, and local Skill usage counts for Pi and pi-web.

中文文档 · Report a bug

At a glance

Pi Usage adds a compact status item for the active model:

Codex · 5h 92% (resets in 2h) · 7d 85% (resets in 5d 3h)

It also provides one command for detailed provider data and Skill statistics:

/usage
/usage skills

The status follows the active model. Only ChatGPT OAuth (OpenAI Codex) and CLIProxyAPI with pi-bridge are queried. Other providers are unsupported. Network errors, missing authentication, unsupported providers, exhausted plans, and a real zero quota remain separate states.

Screenshots

Provider details with `/usage`

Active model quota in the footer

Click an image to open the full-size version.

Install

Choose npm or GitHub as the installation source.

Pi terminal

# npm
pi install npm:@wayner6/pi-usage

# GitHub
pi install github:wayner6/pi-usage

pi-web

Open Settings > Plugins > Add Plugin, choose the global scope, and enter one of these sources:

npm:@wayner6/pi-usage

git:https://github.com/wayner6/pi-usage

Reload the current session after installing or updating the plugin.

Commands

Pi Usage registers only the /usage command.

Command	What it does
`/usage`	Shows configured ChatGPT OAuth and CLIProxyAPI providers
`/usage all`	Same as `/usage`
`/usage current`	Shows data for the active model's provider
`/usage refresh`	Bypasses the cache and refreshes the active provider
`/usage doctor`	Shows the active model, adapter, authentication state, and bridge diagnostics
`/usage skills`	Lists every installed Skill and its accumulated use count, including zero
`/usage settings`	Shows the current plugin settings and configuration path

Skill counting

Pi does not emit a dedicated skill_invoked event. Pi Usage detects a Skill activation when either of these happens:

An accepted /skill:name command enters an agent run (failed or cancelled submissions do not count).
The model successfully reads the entry file of a Skill discovered by Pi.

The same Skill is counted once per agent run, so a /skill:name command followed by a read of its SKILL.md adds one use, not two. Counts begin after Skill tracking is installed and enabled. Old sessions are not scanned.

/usage skills always includes every Skill currently discovered by Pi. Skills that have not been used show 0.

Provider support

Provider	Level	Authentication	Displayed data
OpenAI Codex	Full quota	ChatGPT Plus/Pro OAuth only	Main 5-hour and 7-day windows; additional model limits when returned
CLIProxyAPI	Upstream-dependent	Proxy API key and server-side `pi-bridge`	Only accounts and pools returned by `pi-bridge`

All other native providers are unsupported and are not queried. CPA may display quota pools for upstream services returned by pi-bridge; this is not a native integration with those services.

How provider data is handled

ChatGPT OAuth is queried at the official ChatGPT origin. API keys are not used for this integration. The account ID comes from the resolved OAuth token, not a separate auth file. Additional model limits appear in /usage; the compact status stays focused on the main windows. Reset countdowns are shown only when the provider returns a reset timestamp.

For CLIProxyAPI, install pi-bridge on the CLIProxyAPI server. Pi Usage uses the normal proxy API key and never requests or stores the CLIProxyAPI Management Key. It displays only the accounts and quota pools returned by the bridge.

Proxy accounts are matched by model family and model ID. An unrelated model cannot reuse another provider's quota. Shared pools stay shared: Pi Usage does not turn one Antigravity pool into fictional 5-hour and weekly windows.

States you may see

State	Meaning
`Unauthorized`	Pi could not resolve valid credentials, or the provider rejected them
`No active quota`	Authentication worked, but the account has no usable plan or credits
`Unsupported`	This provider is outside the supported quota integrations
`Bridge Not Found`	CLIProxyAPI is reachable, but its `pi-bridge` endpoint is missing
`stale`	A refresh failed and the last successful result is being shown
`0%`	The provider successfully reported a real zero quota

Settings

/usage settings status on|off       # compact status item, default: on
/usage settings widget on|off       # detailed widget below the editor, default: off
/usage settings skills on|off       # local Skill counting, default: on
/usage settings interval <seconds>  # automatic refresh, 30 to 3600, default: 120
/usage settings timeout <seconds>   # request timeout, 2 to 60, default: 10

Local files:

~/.pi/agent/pi-usage/config.json
~/.pi/agent/pi-usage/skill-usage.jsonl

The Skill log is append-only and stores only the Skill name and timestamp.

Update

# Update Pi Usage installed from npm
pi update npm:@wayner6/pi-usage

# Update all installed extensions without updating Pi itself
pi update --extensions

In pi-web, open Settings > Plugins, update Pi Usage, and reload the session.

Privacy and security

Pi Usage does not use browser cookies, telemetry, or cloud synchronization. It does not send credentials to third-party origins. ChatGPT requests stay on its official origin, while CLIProxyAPI requests stay on the configured proxy origin.

Skill counting does not store prompts, conversation text, tool output, or Skill contents.

Security reports are covered by SECURITY.md.

Development

npm install
npm run verify
npm run pack:check

npm run verify runs TypeScript checks and the test suite. See CONTRIBUTING.md before submitting a change.

Community

Thanks to the LINUX DO community for testing and discussion.

License

MIT