# quota

Subscription quota dashboard for Pi.

## Install / load

Loaded through the root [pi-ext package](../../README.md).

## Commands / tools / settings

- Command:
  `/quota` — show/hide the quota widget.
  Requires interactive mode.
- Tools:
  none.
- Settings:
  see [Settings](#settings).
- Hooks/events:
  - `session_start` — clear stale footer/status state, hide widget, start the
    refresh timer, fetch active-provider quota, publish current status.
  - `agent_start` — republish footer/status from cached data.
  - `agent_end` — refresh when cache is expired, then republish footer/status.
  - `model_select` — force refresh quota for the active provider, then republish
    footer/status.
  - `session_shutdown` — stop refresh timer; clear widget, footer, and status
    state.
  - Emits `footer:segment` when `@bugabinga/pi-ext-footer` is loaded.

## Behavior

Supports Anthropic, OpenAI Codex, GitHub Copilot, Gemini CLI, MiniMax, MiniMax
CN, Zai, and Kimi.
Klaus maps to the Anthropic subscription quota through Pi's Anthropic OAuth
token.

Only the active model provider is fetched.
Provider auth is read through Pi model registry auth storage.
Providers without configured auth are skipped.

Quota data is cached for `quota.refreshIntervalMs` (default 5 minutes) outside forced refreshes.
Fetch failures keep the last cached row for that provider when available;
otherwise no row is shown.

The `/quota` command writes details to widget id `usage`.
When visible, the widget updates after a forced refresh and on the refresh timer.

Footer/status behavior:

- With `@bugabinga/pi-ext-footer`:
  emits one segment for the active visible provider into the `llm` zone with
  `order: 4`.
- Without it:
  writes compact Pi status text under status id `quota`.
- Footer and fallback status text are filtered to the active model provider.
- Footer segment id:
  `quota:${providerName}`.
- Active provider marker:
  `●`; inactive marker:
  `◌`.
- The active provider's segment omits the provider name, because the model
  segment already shows that provider's icon.
  Inactive providers keep their name.
- Outside TUI mode, the status text is spelled out, for example
  `Anthropic quota 4% used, resets in 4h50m`.
- Without UI, no status is published and no quota requests are made.

OpenAI Codex needs both an auth token and an account id.
The account id is read from Pi auth storage first, then `~/.codex/auth.json`.

## Settings

`quota.refreshIntervalMs` sets both the quota cache lifetime and the refresh timer interval, in milliseconds.
Environment variable: `PI_QUOTA_REFRESH_INTERVAL_MS`.
Default: `300000` (5 minutes).
Valid range: integer from `10000` to `2147483647`.
Precedence: environment variable, then trusted project `.pi/settings.json`, then user `~/.pi/agent/settings.json`, then default.
Project settings apply only when the project is trusted.
Settings files must hold a JSON number; numeric strings are accepted only from the environment variable.
The value is resolved once per session at `session_start`, only when a UI is present.
An invalid value never falls through to a lower-priority source.
Instead, it produces one warning naming the error and the default `300000` is used.

## Debug

Opt in through [debug configuration](../DEBUG.md).
Safe events: `session.start`, `session.shutdown`, `quota.fetch.start`, `quota.fetch.finish`, `quota.fetch.error`.