pi-nan-quota

Your NaN Builders quota in the pi footer: a bar for the model you are using, in NaN's violet, and a /nan-quota command with the per-model breakdown.

Read-only. It does not register a provider, does not write any configuration, does not touch auth.json, and sends nothing anywhere while you are using a model from another provider (unless you ask for that with alwaysShow).

Unofficial. Not affiliated with NaN Builders or Helmcode.

Install

pi install npm:pi-nan-quota

Then pick a NaN model (/model). The segment appears in the footer within a second or two.

Requirements

• pi ≥ 1.3.0 and Node.js ≥ 22.
• A NaN API key from an inference plan: NaN member or GLM 5.3 premium. The Community plan has no API access, so there is no key to read quota with. Create one at cloud.nan.builders → Settings → API Keys.
• The NaN provider configured in pi, any of:
  • the nan block in ~/.pi/agent/models.json from NaN's pi guide (or written by the NaN CLI);
  • @gtrabanco/pi-nan-provider;
  • any provider whose baseUrl is on nan.builders, whatever its id.

The key is read from that provider's stored credential (/login <provider>), falling back to NAN_API_KEY.

What you see

Footer

Drawn only while the active model talks to NaN (or always, with alwaysShow):

The bar is ten pills, ▰ for the used part and ▱ for the rest, all in NaN's violet #7D39EB, with no gap between the two parts. The scale is uniform: empty means nothing used, full means the cap is reached, and the nine steps in between share 1–99 % evenly, eleven points each:

So the bar climbs one pill at a time, never skips one, lights the first pill at the first unit of usage, is exactly half around 50 %, and is only full at the cap. It is drawn from the printed percentage, so the two always agree. The scale is the same for every model: it is a share of that model's own cap. The bar is always ten columns and the percentage four, so nothing in the footer moves as the numbers change.

From warnAt (80 %) the used part and the alerts switch to your theme's warning colour, from criticalAt (95 %) to its error colour.

/nan-quota

NaN · period 2026-11-01 → 2026-12-01 (resets in 24d 3h)

  deepseek-v4-flash  ▰▰▱▱▱▱▱▱▱▱  20%   614.6M / 3.0B    2.4B free
  glm5.3-flash       ▰▰▰▱▱▱▱▱▱▱  26%   529.3M / 2.0B    1.5B free
  mimo-v2.6-flash    ▰▱▱▱▱▱▱▱▱▱   2%    19.1M / 1.0B  980.9M free
  qwen3.8-flash      ▰▱▱▱▱▱▱▱▱▱   7%    34.5M / 500M  465.5M free

other models this month: qwen3-embedding 14.8k · qwen3.6 427 · gemma4 135

month: 1.2B · total: 1.2B · 12.4k requests

source: quota (server) · updated 20:48 UTC

On a GLM 5.3 premium key, glm5.3 gets its own row with its rolling window (4h window: 400M). A purchased extra pool adds +125M extra until 2027-04-29 to its model's row, or (paused: needs an active membership) when NaN has paused it.

The table is written to the transcript as a custom entry, which pi keeps out of the model's context: asking for your quota costs no tokens.

• /nan-quota refresh reads the API now, ignoring the cache.
• /nan-quota help lists the subcommands and settings.

How it works with NaN's plans

The extension does not carry a list of plans, premium models or retired models. It asks NaN:

• Caps, consumption, reset and extra pools come from the quota endpoint the NaN dashboard uses, so a cap NaN changes tomorrow is right tomorrow.
• Which models your key can call comes from the documented GET /v1/models, which NaN filters by plan. That is how a member key does not see glm5.3, nobody sees retired models such as glm5.2 (the quota endpoint still reports both), and a model NaN starts serving today shows up today.
• Month and all-time totals, and the usage of uncapped models, come from the documented GET /v1/usage.

Percentages are always against the monthly cap. A purchased extra pool is shown next to it, not folded into it: the API reports what is left in a pool, not how large it was or in which order NaN draws from it.

The rolling window of the premium model is shown by size only: NaN reports how large the window is, not how much of it has been used, and the extension does not guess.

Privacy and network

Requests go to two NaN hosts, with your key in the Authorization header and pi-nan-quota/<version> as the user agent. Nothing else is sent, and nothing is sent anywhere else. There is no telemetry.

A refresh happens when a session starts on a NaN model, when you switch to one, after a turn (at most once every two minutes), and on /nan-quota. That is well under the documented limit of the usage endpoint (30 requests per minute, counted separately from inference).

The quota endpoint is not in NaN's published documentation; it is the one the dashboard reads, and its own error message states that sk- API keys are accepted. To keep every request on the documented API, turn it off:

{ "quotaEndpoint": false }

Caps then come from a table copied from NaN's model docs, dated in src/caps.ts, and every percentage is marked ~ as an estimate. The same thing happens automatically, with one warning, if the quota endpoint ever stops answering in the expected shape.

Configuration

~/.pi/agent/nan-quota.json, every key optional:

{
  "warnAt": 80,
  "criticalAt": 95,
  "maxAlerts": 2,
  "alwaysShow": false,
  "providerId": "nan",
  "glyphs": "pill",
  "quotaEndpoint": true,
  "models": [],
  "refreshSeconds": 120
}

An invalid value is ignored on its own, so one typo does not reset the rest. The file is read again on /reload.

PI_NAN_QUOTA_GLYPHS=safe switches the glyphs for a single session.

Terminals and fonts

• Colour follows the terminal: 24-bit when COLORTERM says truecolor, the nearest of 256 colours otherwise, none with NO_COLOR or TERM=dumb (the pills still show the progress through their shape).
• ▰ and ▱ are East Asian Width neutral: one column wide even where ambiguous-width characters are drawn double.
• Some monospace fonts do not have them (JetBrains Mono, for one). The terminal then borrows them from another font, which can look uneven; "glyphs": "safe" uses small squares every monospace font tested has.

What it does not do

• It is not a provider: no model list, no request rewriting, no X-Pi-Provider header. Use it with whichever NaN provider you already have.
• No /nan-usage command: that name belongs to @gtrabanco/pi-nan-provider, and both packages work side by side.
• No writes: no settings, no credentials, no session entries other than the tables you ask for.
• No history, charts, notifications beyond one warning per failure, or support for several NaN accounts at once.
• No Helmcode enterprise tenants (api.helmcode.com): only the NaN community cluster.

Troubleshooting

Development

npm ci
npm run check   # tsc --noEmit, strict
npm test        # unit, wiring and real-pi smoke suites; no network

• test/run.mjs — the pure pieces against payloads captured verbatim from the three endpoints (test/fixtures/): validation, plan filtering, provider detection, bar geometry, footer shapes, cache policy, command text.
• test/wiring.mjs — the extension driven through a stand-in ExtensionAPI with fetch stubbed: events, the provider gate, request counts, failure paths, the privacy switch.
• test/smoke.mjs — the package loaded by a real pi through its SDK. CI runs it against pi 1.3.0 and the latest pi.

License

GPL-3.0-or-later. Copyright © 2026 Adrián Rodríguez Mesa.