pi-quota-status

Pi extension that shows quota usage for the active provider in the footer and exposes a command-first JSON interface for scripts.

What is shipped to npm

The npm package is intentionally small. It ships only what Pi needs to load the extension:

• src/ production TypeScript files
• README.md
• package.json
• assets/screenshots/ for README/gallery images

It does not ship repository-only artifacts, local menu-bar helper scripts/icons, or tests. Those live in the repo for development/manual install, but they are not part of the npm runtime package.

Install

pi install npm:@mjfuertesf/pi-quota-status

From git or a local checkout:

pi install git:gitlab.com/mjfuertesf/pi-quota-status
pi install ./relative/path/to/pi-quota-status

Pi loads the extension from the explicit package manifest entry:

{
  "pi": {
    "extensions": ["./src/extension.ts"]
  }
}

No root index.ts shim or build step is required.

Supported providers

Runtime provider	Footer label	Source
openai-codex	5h(XX%, Yh) Wk(ZZ%, Wd)	ChatGPT backend quota API
opencode-go	5h(XX%, Yh) Wk(ZZ%, Wd)	opencode.ai Go usage API
zai	5h(XX%, Yh) Wk(ZZ%, Wd)	Z.ai GLM Coding Plan usage API
claude-bridge	5h(XX%, Yh) Wk(ZZ%, Wd)	Claude web usage API via the Anthropic quota adapter path
anthropic	5h(XX%, Yh) Wk(ZZ%, Wd)	Claude web usage API via the Anthropic quota adapter path

claude-bridge deliberately uses the same Anthropic quota adapter and quota-status.anthropic-subscription auth entry as anthropic.

Unsupported provider or no active session renders n/a. Supported provider with unresolved quota data renders unknown.

Commands

Usage

/quota-status-usage

Prints the display string, for example:

5h(82%, 1h30m) Wk(91%, 3.00d)

For structured output:

/quota-status-usage --json

Manual smoke test:

pi --print --no-session --no-context-files --model anthropic/claude-haiku-4-5 "/quota-status-usage --json"

--model <provider>/<model> determines the active runtime provider seen by the command.

Stable result states:

• ok: provider is supported and both quota windows were resolved
• partial: provider is supported and at least one quota window was resolved
• unknown: provider is supported, but config/auth/network/API data was unusable
• unsupported: active provider is not handled by this extension

JSON results include the same display format plus normalized quota fields.

HAR extraction

/quota-status-extract <har_filepath>

Flags:

• --write: save extracted secrets to ~/.pi/agent/auth.json
• --no-verify: skip live credential verification
• --provider <anthropic-subscription>: force provider when a HAR is ambiguous

Examples:

/quota-status-extract @~/Downloads/claude-usage.har
/quota-status-extract --write --no-verify @~/Downloads/claude-usage.har

Path handling supports @/path, ~/path, and paths with spaces.

Auth storage

Saved secrets live in ~/.pi/agent/auth.json.

Claude / Anthropic quota:

{
  "quota-status": {
    "anthropic-subscription": {
      "organizationUuid": "...",
      "authCookie": "...",
      "headers": {
        "anthropic-device-id": "...",
        "user-agent": "..."
      }
    }
  }
}

OpenAI Codex quota:

{
  "openai-codex": {
    "access": "<bearer-token>",
    "accountId": "<account-id>"
  }
}

opencode-go quota:

{
  "opencode-go": {
    "key": "<api-key>"
  }
}

Z.ai uses Pi's native auth entry automatically:

{
  "zai": { "type": "api_key", "key": "<api-key>" }
}

The adapter calls https://api.z.ai/api/monitor/usage/quota/limit. Kimi Code is intentionally disabled until its subscription API can be verified live.

HAR files and extracted auth entries contain active session secrets. Treat them like credentials and never commit or share them.

Development

npm test

The recursive test suite covers command parsing/execution, provider adapters, provider registry, footer refresh behavior, Anthropic HAR extraction, and script smoke tests.

Credits

• BlockLune/pi-chatgpt-usage-status — original compact format and extension skeleton
• mattleong/pi-better-openai — wham/usage endpoint discovery and header shape for OpenAI Codex quota reads
• anomalyco/opencode#16513 — OpenCode Go usage endpoint