pi-quota-status

Multi-adapter quota footer status for Pi. Shows remaining quota in the footer for the active provider.

Install

pi install npm:@mjfuertesf/pi-quota-status
pi install git:gitlab.com/mjfuertesf/pi-quota-status

Repo: https://gitlab.com/mjfuertesf/pi-quota-status

All provider configuration in this package is global-only.

Supported providers

| Provider | Footer label | Source | |---|---|---| | openai-codex | 5h(XX%,Yh) Wk(ZZ%,Wd) | ChatGPT backend API | | opencode-go | 5h(XX%,Yh) Wk(ZZ%,Wd) | opencode.ai dashboard scrape | | claude-bridge | 5h(XX%,Yh) Wk(ZZ%,Wd) | Claude web usage API (claude.ai/settings/usage) via exported HAR credentials |

Unsupported provider (or no active session) → grey italic n/a
Supported provider, but data not yet resolved → grey italic unknown

Output format

5h(82%,1.50h) Wk(91%,3.00d)

• 5h = 5-hour rolling window
• Wk = weekly window
• XX% = remaining quota (100 − used%)
• Yh / Yd = time until window resets

HAR-based setup for supported web providers

Use one command for HAR extraction:

/quota-status-extract <har_filepath>

Supported flags:

• --write: save extracted secrets to ~/.pi/agent/auth.json instead of only printing the extracted JSON; write mode does not echo secrets back into chat output
• --no-verify: skip live verification; by default the command verifies extracted credentials before succeeding
• --provider <anthropic-subscription|opencode-go>: force the provider when needed

To capture a usable HAR:

• for Claude, open https://claude.ai/settings/usage while signed in and export a HAR that includes the organization usage request
• for opencode-go, open your authenticated https://opencode.ai/workspace/<workspaceId>/go dashboard and export a HAR that includes that request

Path handling:

• @/path/to/file.har works
• ~/Downloads/file.har works
• paths with spaces work

Examples:

/quota-status-extract @~/Downloads/claude-usage.har
/quota-status-extract --write ~/Downloads/opencode-session.har
/quota-status-extract --write --no-verify @~/Downloads/claude-usage.har
/quota-status-extract --provider opencode-go /path/to/mixed-capture.har

Provider detection is automatic when the HAR matches exactly one supported provider. If the HAR matches multiple supported providers, extraction fails and you must re-run with --provider to disambiguate.

Saved secrets live under the quota-status parent key in ~/.pi/agent/auth.json:

{
  "quota-status": {
    "anthropic-subscription": {
      "organizationUuid": "11111111-2222-3333-4444-555555555555",
      "authCookie": "sessionKey=fake-session-cookie; cf_clearance=fake-clearance-cookie",
      "headers": {
        "anthropic-device-id": "fake-device-id",
        "user-agent": "Fake Browser 1.0"
      }
    },
    "opencode-go": {
      "workspaceId": "fake-workspace-id",
      "authCookie": "fake-opencode-auth-cookie"
    }
  }
}

Notes:

• anthropic-subscription is the saved config name for Claude web usage data
• the active Pi runtime provider still remains claude-bridge
• opencode-go keeps the same saved and runtime provider name

Security warning

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

Failure behavior

Shows unknown when config is invalid/missing, cookies are expired, Cloudflare rejects the request (for example HTTP 403), or network/API calls fail.

When a fetch fails after a prior successful read, the stale-cache behavior still applies (last good value is shown briefly, then falls back to unknown/partial placeholder per existing retry rules).

Adapter: openai-codex

Reads auth from ~/.pi/agent/auth.json:

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

Fetches from (tries in order):

1. https://chatgpt.com/backend-api/wham/usage
2. https://chatgpt.com/backend-api/codex/usage (fallback)

Adapter: opencode-go

Scrapes the opencode.ai dashboard for the authenticated workspace.

Runtime auth is read only from ~/.pi/agent/auth.json at quota-status.opencode-go.

Tests

npm test

Runs tsx --test ./*.test.ts. Currently 143 tests covering ANSI helpers, duration formatting, all three adapters, /quota-status-extract flows (arg parsing, autodetection, ambiguity handling, verification, auth writes, command registration), refresh cadence, and session/provider guards.

Credits

• BlockLune/pi-chatgpt-usage-status — original compact format and extension skeleton that inspired this project
• mattleong/pi-better-openai — wham/usage endpoint discovery and header shape for OpenAI Codex quota reads
• donrami/pi-go-bars — opencode-go adapter inspiration