Skip to content
Back to search

quota-axi

Allow your agents to see your LLM subscription quota windows.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kunchenguid-quota-axi/badge.svg)](/listings/kunchenguid-quota-axi)

HTML

<a href="/listings/kunchenguid-quota-axi"><img src="/api/listings/kunchenguid-quota-axi/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Credential-source note:** Claude Code, the Cursor CLI (`cursor-agent`), Copilot CLI, and Muse Code keep live tokens in native secure stores on supported platforms. Linux `cursor-agent` stores its access token in `~/.config/cursor/auth.json` (or the XDG/`$CURSOR_CLI_CONFIG` override); Copilot CLI uses Windows Credential Manager on Windows and the macOS Keychain on macOS; Muse Code on macOS stores the OAuth token in the login Keychain item its `auth.json` `storage: "keychain"` records point to. quota-axi does not read native secure-store values until the user grants permission, so Claude quota, CLI-only Cursor auth, Copilot CLI auth, or Muse quota can stay stale or appear unavailable when no other usable credential exists. On Linux it reads only the Cursor auth file's `accessToken` and never its refresh token. Run `quota-axi --allow-keychain-prompt` once and approve macOS Keychain access with "Always Allow"; on Windows the same flag permits the Copilot CLI Credential Manager read without an OS prompt. After a successful read, future non-interactive quota calls reuse the corresponding account-scoped grant without requiring the flag. Claude grants are also profile-scoped; legacy Claude markers created before account-pinned lookup are not reused.

$ npx -y quota-axi --provider claude,codex,cursor,copilot,grok,kimi,zai,agy
bin: ~/.npm/_npx/.../quota-axi
description: Report local agent-provider quota windows for routing-aware agents
generatedAt: "2026-03-15T16:42:00.000Z"
quota[12]{provider,scope,effectivePercentRemaining,spendPriority,runway,confidence,limitedBy,resetsAt}:
  claude,all_models,64,-0.3798,projected_exhaustion,established,seven_day,"2026-03-20T17:59:45.600Z"
  claude,seven_day_opus,64,0.3218,projected_exhaustion,established,seven_day,"2026-03-20T17:59:45.600Z"
  claude,"model:fable",64,-0.0932,projected_exhaustion,established,seven_day,"2026-03-20T17:59:45.600Z"
  codex,all_models,47,-0.2383,projected_exhaustion,established,weekly,"2026-03-19T09:54:28.800Z"
  codex,"model:gpt-5.1-codex",47,-0.1973,projected_exhaustion,established,weekly,"2026-03-19T09:54:28.800Z"
  cursor,all_models,72,1.4067,through_reset,established,included_usage,"2026-04-01T00:00:00.000Z"
  grok,all_products,67,0.5778,through_reset,established,week,"2026-04-01T00:00:00.000Z"
  kimi,all_models,74,0.2484,through_reset,established,weekly,"2026-03-20T12:17:02.400Z"
  zai,all_models,50,-1.0046,projected_exhaustion,established,weekly,"2026-03-20T16:42:00.000Z"
  zai,tools,100,unknown,unknown,unknown,mcp_month,"2026-04-01T00:00:00.000Z"
  agy,gemini,88,0.4102,through_reset,established,gemini_weekly,"2026-03-20T00:00:00.000Z"
  agy,claude_gpt,90,0.3687,through_reset,established,claude_gpt_weekly,"2026-03-21T00:00:00.000Z"
exhaustion[6]{provider,scope,usableRunwaySeconds,projectedExhaustedAt,limitingWindowId}:
  claude,all_models,298906,"2026-03-19T03:43:45.600Z",seven_day
  claude,seven_day_opus,298906,"2026-03-19T03:43:45.600Z",seven_day
  claude,"model:fable",298906,"2026-03-19T03:43:45.600Z",seven_day
  codex,all_models,10365,"2026-03-15T19:34:45.428Z",five_hour
  codex,"model:gpt-5.1-codex",10365,"2026-03-15T19:34:45.428Z",five_hour
  zai,all_models,172800,"2026-03-17T16:42:00.000Z",weekly
attention[2]{provider,scope,kind,detail,remedy}:
  copilot,all,unresolved_windows,chat + premium_interactions,none
  zai,tools,unmeasurable,"mcp_month blocks runway + spendPriority",none
help[1]:
  Run `quota-axi --full` for windows, pace, reserve, and account evidence

Default TOON is decision-shaped: `quota[]` carries one fully populated row per measurable scope, and the sparse `exhaustion[]` and `attention[]` blocks carry the finite-runway and non-nominal facts. See [Default report blocks](#default-report-blocks).

`--json` emits the normalized model instead. Derivation inputs are demoted to `--full`; see [Output tiers](#output-tiers).

$ quota-axi --provider claude --json
{
  "generatedAt": "2026-03-15T16:42:00.000Z",
  "schemaVersion": 5,

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 912 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <h1 align="center">quota-axi</h1>
  2. <h3 align="center">Your agent needs to be aware of your quota</h3>
  3. <p align="center">
  4. <a href="https://www.npmjs.com/package/quota-axi"><img alt="npm" src="https://img.shields.io/npm/v/quota-axi?style=flat-square" /></a>
  5. <a href="https://github.com/kunchenguid/quota-axi/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/kunchenguid/quota-axi/ci.yml?style=flat-square&label=ci" /></a>
  6. <a href="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=flat-square"><img alt="Platform" src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=flat-square" /></a>
  7. <a href="https://x.com/kunchenguid"><img alt="X" src="https://img.shields.io/badge/X-@kunchenguid-black?style=flat-square" /></a>
  8. <a href="https://discord.gg/Wsy2NpnZDu"><img alt="Discord" src="https://img.shields.io/discord/1439901831038763092?style=flat-square&label=discord" /></a>
  9. </p>
  10. Quota CLI for agents - designed with [AXI](https://axi.md) (Agent eXperience Interface).
  11. Agents need quota state before they choose where work can safely run.
  12. Vendor dashboards are not shaped for shell automation, and local CLIs expose different windows, resets, and auth sources.
  13. quota-axi reports local Claude, Codex, Cursor, GitHub Copilot, Grok, Kimi, Z.AI, Alibaba, OpenCode Go, Antigravity (`agy`), Command Code, MiniMax, MiMo, DeepSeek, OpenRouter, ElevenLabs, Devin, Muse, and Higgsfield quota windows in one [AXI](https://axi.md)-shaped call.
  14. It is data only: it never routes, recommends a provider, model, harness, credential, or route, proxies, intercepts, logs in, imports browser cookies, or mints or rotates a credential. Muse's only quota read also issues an API key server-side, which quota-axi discards unread and rate-bounds ([Muse provider notes](#provider-notes)). When the same stored access token is expired, carries a refresh token, and is definitively rejected, quota-axi may delegate renewal to that vendor's own non-interactive CLI command and re-read the result ([Delegated credential refresh](#delegated-credential-refresh)). Default output has no ordering preference. The opt-in `models --sort runway` surface applies only its documented deterministic comparator to quota evidence, preserves all evidence and explicit ties, and is not a recommendation. It publishes one derived per-scope comparative selection signal, [`selection`](#per-scope-selection-signal), as data computed from figures it already reports; the consumer, not quota-axi, does any routing or ranking with it.
  15. - **Official sources** - quota-axi reads local provider auth sources and calls first-party quota, usage, billing, entitlement, local loopback, or read-only credential-liveness endpoints used by the local agents, with read-only CLI probes where applicable. Vendor-command boundaries and the explicit inference exception are documented under [Safety guarantees](#safety-guarantees).
  16. - **Local first** - quota and auth reports run on the machine that holds the credentials; their network calls go to first-party provider endpoints, never a third-party relay.
  17. The separate `update` command contacts npm only when the user runs it.
  18. - **Token efficient** - default stdout is compact TOON so agents spend fewer tokens parsing quota state, with `--json` available when a caller needs the normalized model.
  19. ## Quick Start
  20. **Credential-source note:** Claude Code, the Cursor CLI (`cursor-agent`), Copilot CLI, and Muse Code keep live tokens in native secure stores on supported platforms. Linux `cursor-agent` stores its access token in `~/.config/cursor/auth.json` (or the XDG/`$CURSOR_CLI_CONFIG` override); Copilot CLI uses Windows Credential Manager on Windows and the macOS Keychain on macOS; Muse Code on macOS stores the OAuth token in the login Keychain item its `auth.json` `storage: "keychain"` records point to.
  21. quota-axi does not read native secure-store values until the user grants permission, so Claude quota, CLI-only Cursor auth, Copilot CLI auth, or Muse quota can stay stale or appear unavailable when no other usable credential exists. On Linux it reads only the Cursor auth file's `accessToken` and never its refresh token.
  22. Run `quota-axi --allow-keychain-prompt` once and approve macOS Keychain access with "Always Allow"; on Windows the same flag permits the Copilot CLI Credential Manager read without an OS prompt.
  23. After a successful read, future non-interactive quota calls reuse the corresponding account-scoped grant without requiring the flag. Claude grants are also profile-scoped; legacy Claude markers created before account-pinned lookup are not reused.
  24. ```sh
  25. $ npx -y quota-axi --provider claude,codex,cursor,copilot,grok,kimi,zai,agy
  26. bin: ~/.npm/_npx/.../quota-axi
  27. description: Report local agent-provider quota windows for routing-aware agents
  28. generatedAt: "2026-03-15T16:42:00.000Z"
  29. quota[12]{provider,scope,effectivePercentRemaining,spendPriority,runway,confidence,limitedBy,resetsAt}:
  30. claude,all_models,64,-0.3798,projected_exhaustion,established,seven_day,"2026-03-20T17:59:45.600Z"
  31. claude,seven_day_opus,64,0.3218,projected_exhaustion,established,seven_day,"2026-03-20T17:59:45.600Z"
  32. claude,"model:fable",64,-0.0932,projected_exhaustion,established,seven_day,"2026-03-20T17:59:45.600Z"
  33. codex,all_models,47,-0.2383,projected_exhaustion,established,weekly,"2026-03-19T09:54:28.800Z"
  34. codex,"model:gpt-5.1-codex",47,-0.1973,projected_exhaustion,established,weekly,"2026-03-19T09:54:28.800Z"
  35. cursor,all_models,72,1.4067,through_reset,established,included_usage,"2026-04-01T00:00:00.000Z"
  36. grok,all_products,67,0.5778,through_reset,established,week,"2026-04-01T00:00:00.000Z"
  37. kimi,all_models,74,0.2484,through_reset,established,weekly,"2026-03-20T12:17:02.400Z"
  38. zai,all_models,50,-1.0046,projected_exhaustion,established,weekly,"2026-03-20T16:42:00.000Z"
  39. zai,tools,100,unknown,unknown,unknown,mcp_month,"2026-04-01T00:00:00.000Z"
  40. agy,gemini,88,0.4102,through_reset,established,gemini_weekly,"2026-03-20T00:00:00.000Z"
  41. agy,claude_gpt,90,0.3687,through_reset,established,claude_gpt_weekly,"2026-03-21T00:00:00.000Z"
  42. exhaustion[6]{provider,scope,usableRunwaySeconds,projectedExhaustedAt,limitingWindowId}:
  43. claude,all_models,298906,"2026-03-19T03:43:45.600Z",seven_day
  44. claude,seven_day_opus,298906,"2026-03-19T03:43:45.600Z",seven_day
  45. claude,"model:fable",298906,"2026-03-19T03:43:45.600Z",seven_day
  46. codex,all_models,10365,"2026-03-15T19:34:45.428Z",five_hour
  47. codex,"model:gpt-5.1-codex",10365,"2026-03-15T19:34:45.428Z",five_hour
  48. zai,all_models,172800,"2026-03-17T16:42:00.000Z",weekly
  49. attention[2]{provider,scope,kind,detail,remedy}:
  50. copilot,all,unresolved_windows,chat + premium_interactions,none
  51. zai,tools,unmeasurable,"mcp_month blocks runway + spendPriority",none
  52. help[1]:
  53. Run `quota-axi --full` for windows, pace, reserve, and account evidence
  54. ```
  55. Default TOON is decision-shaped: `quota[]` carries one fully populated row per measurable scope, and the sparse `exhaustion[]` and `attention[]` blocks carry the finite-runway and non-nominal facts. See [Default report blocks](#default-report-blocks).
  56. `--json` emits the normalized model instead. Derivation inputs are demoted to `--full`; see [Output tiers](#output-tiers).
  57. ```sh
  58. $ quota-axi --provider claude --json
  59. {
  60. "generatedAt": "2026-03-15T16:42:00.000Z",
  61. "schemaVersion": 5,
  62. "providers": [
  63. {
  64. "provider": "claude",
  65. "accountKeys": ["default"],
  66. "plan": "pro",
  67. "windows": [
  68. {
  69. "id": "five_hour",
  70. "label": "session",
  71. "kind": "session",
  72. "percentRemaining": 82,
  73. "resetsAt": "2026-03-15T20:10:48.000Z",
  74. "pace": {
  75. "status": "behind",
  76. "reservePercentPoints": 12.4,
  77. "burnMultiple": 0.5921
  78. }
  79. },
  80. {
  81. "id": "seven_day",
  82. "label": "week",
  83. "kind": "weekly",
  84. "percentRemaining": 64,
  85. "resetsAt": "2026-03-20T17:59:45.600Z",
  86. "pace": {
  87. "status": "ahead",
  88. "reservePercentPoints": -8.2,
  89. "burnMultiple": 1.295
  90. }
  91. },
  92. {
  93. "id": "model:fable",
  94. "label": "Fable week",
  95. "kind": "model",
  96. "percentRemaining": 71,
  97. "resetsAt": "2026-03-20T08:25:12.000Z",
  98. "pace": {
  99. "status": "behind",
  100. "reservePercentPoints": 4.5,
  101. "burnMultiple": 0.8657
  102. }
  103. }
  104. ],
  105. "state": {
  106. "status": "fresh",
  107. "stale": false
  108. },
  109. "quotaSemantics": {
  110. "status": "known",
  111. "effectiveAvailability": [
  112. {
  113. "scope": "all_models",
  114. "status": "known",
  115. "effectivePercentRemaining": 64,
  116. "boundedBy": [
  117. "five_hour",
  118. "seven_day"
  119. ],
  120. "limitingWindowIds": [
  121. "seven_day"
  122. ],
  123. "pace": {
  124. "status": "mixed",
  125. "aheadWindowIds": [
  126. "seven_day"
  127. ],
  128. "worstReservePercentPoints": -8.2,
  129. "worstReserveWindowId": "seven_day"
  130. },
  131. "runway": {
  132. "status": "projected_exhaustion",
  133. "usableRunwaySeconds": 298906,
  134. "projectedExhaustedAt": "2026-03-19T03:43:45.600Z",
  135. "limitingWindowId": "seven_day",
  136. "projectionConfidence": "established"
  137. },
  138. "selection": {
  139. "status": "known",
  140. "spendPriority": -0.3798
  141. }
  142. },
  143. {
  144. "scope": "model:fable",
  145. "status": "known",
  146. "effectivePercentRemaining": 64,
  147. "boundedBy": [
  148. "five_hour",
  149. "seven_day",
  150. "model:fable"
  151. ],
  152. "limitingWindowIds": [
  153. "seven_day"
  154. ],
  155. "pace": {
  156. "status": "mixed",
  157. "aheadWindowIds": [
  158. "seven_day"
  159. ],
  160. "worstReservePercentPoints": -8.2,
  161. "worstReserveWindowId": "seven_day"
  162. },
  163. "runway": {
  164. "status": "projected_exhaustion",
  165. "usableRunwaySeconds": 298906,
  166. "projectedExhaustedAt": "2026-03-19T03:43:45.600Z",
  167. "limitingWindowId": "seven_day",
  168. "projectionConfidence": "established"
  169. },
  170. "selection": {
  171. "status": "known",
  172. "spendPriority": -0.0932
  173. }
  174. }
  175. ]
  176. }
  177. }
  178. ]
  179. }
  180. ```
  181. ```sh
  182. $ quota-axi auth
  183. bin: ~/.npm/_npx/.../quota-axi
  184. description: Inspect local quota auth sources without printing secret values
  185. auth[42]{provider,source,path,status,error}:
  186. claude,oauth-file,~/.claude/.credentials.json,available,none
  187. claude,keychain,none,skipped,keychain_prompt_required
  188. codex,auth-json,~/.codex/auth.json,available,none
  189. codex,pi:openai-codex,~/.pi/agent/auth.json,available,none
  190. codex,cli-rpc,~/.local/bin/codex,available,none
  191. cursor,state-vscdb,~/Library/Application Support/Cursor/User/globalStorage/state.vscdb,available,none
  192. cursor,cli-keychain,~/.cursor/cli-config.json,skipped,keychain_prompt_required
  193. copilot,apps-json,~/.config/github-copilot/apps.json,available,none
  194. copilot,copilot-cli:keychain,~/.copilot/config.json,skipped,keychain_prompt_required
  195. copilot,gh:hosts.yml,~/.config/gh/hosts.yml,available,none
  196. grok,auth-json,~/.grok/auth.json,available,none
  197. grok,pi:xai,none,missing,none
  198. kimi,pi:kimi-coding,none,available,none
  199. kimi,kimi-code-cli,none,available,none
  200. zai,pi:zai,~/.pi/agent/auth.json,missing,none
  201. zai,opencode:auth.json,~/.local/share/opencode/auth.json,available,none
  202. agy,loopback,none,available,none
  203. alibaba,bl-cli,none,available,none
  204. opencode-go,opencode:opencode.db,~/.local/share/opencode/opencode.db,available,none
  205. opencode-go,opencode:auth.json,~/.local/share/opencode/auth.json,missing,none
  206. commandcode,pi:commandcode,~/.pi/agent/auth.json,missing,none
  207. commandcode,env:COMMAND_CODE_API_KEY,none,missing,none
  208. commandcode,env:COMMANDCODE_API_KEY,none,missing,none
  209. commandcode,commandcode-cli,~/.commandcode/auth.json,missing,none
  210. commandcode,omp:commandcode,~/.omp/agent/auth.json,missing,none
  211. minimax,env:MINIMAX_API_KEY,none,missing,none
  212. minimax,pi:minimax,~/.pi/agent/auth.json,available,none
  213. minimax,minimax:config.json,~/.mmx/config.json,missing,none
  214. mimo,env:MIMO_API_KEY,none,available,none
  215. mimo,pi:xiaomi,~/.pi/agent/auth.json,missing,none
  216. mimo,pi:xiaomi-token-plan-sgp,~/.pi/agent/auth.json,missing,none
  217. mimo,pi:xiaomi-token-plan-cn,~/.pi/agent/auth.json,missing,none
  218. mimo,pi:xiaomi-token-plan-ams,~/.pi/agent/auth.json,missing,none
  219. deepseek,env:DEEPSEEK_API_KEY,none,missing,none
  220. deepseek,pi:deepseek,~/.pi/agent/auth.json,available,none
  221. openrouter,env:OPENROUTER_API_KEY,none,missing,none
  222. openrouter,pi:openrouter,~/.pi/agent/auth.json,available,none
  223. elevenlabs,env:ELEVENLABS_API_KEY,ELEVENLABS_API_KEY,missing,none
  224. devin,env:WINDSURF_API_KEY,WINDSURF_API_KEY,missing,none
  225. devin,file:credentials.toml,~/.local/share/devin/credentials.toml,missing,none
  226. muse,muse:auth.json,~/.config/muse/auth.json,missing,none
  227. muse,cli-keychain,Keychain ai.meta.dev.credentials,skipped,keychain_prompt_required
  228. muse,env:META_API_KEY,META_API_KEY,missing,none
  229. help[1]:
  230. Run `quota-axi --allow-keychain-prompt auth` to permit native secure-store access
  231. ```
  232. This `auth` example's header count and the rows below it come from one capture and are internally consistent (the count equals the rows shown); a live `auth` run varies by the providers and credential stores actually present on the machine.
  233. ## Install
  234. quota-axi requires Node.js 22.19 or newer.
  235. **Agent skill (recommended)**
  236. Install the skill in the [Agent Skills](https://agentskills.io) format with [`npx skills`](https://github.com/vercel-labs/skills):
  237. ```sh
  238. npx skills add kunchenguid/quota-axi --skill quota-axi -g
  239. ```
  240. The minimal skill points your agent to quota-axi's live CLI guidance through `npx -y quota-axi`, so nothing needs to be installed ahead of time and installed skill copies do not duplicate changing CLI instructions.
  241. The `skills` CLI's `-g` option is intended to install for all projects (e.g. `~/.claude/skills/`).
  242. It may report `PromptScript does not support global skill installation` even when the skill was installed for other agents.
  243. Check the relevant agent's skills directory for `quota-axi/SKILL.md` to confirm.
  244. Drop `-g` for a per-project install (`.claude/skills/`), or use `npm install -g quota-axi` or `npx -y quota-axi` for the CLI.
  245. **Direct use**
  246. ```sh
  247. npx -y quota-axi
  248. ```
  249. **npm**
  250. ```sh
  251. npm install -g quota-axi
  252. ```
  253. **From source**
  254. ```sh
  255. git clone https://github.com/kunchenguid/quota-axi.git
  256. cd quota-axi
  257. pnpm install
  258. pnpm run build
  259. pnpm run dev
  260. ```
  261. ## Agent Skill
  262. The npm package includes `skills/quota-axi/SKILL.md`, the same installable skill recommended above.
  263. It is generated from `src/skill.ts` as a minimal stub: discovery frontmatter, what quota-axi is, when to reach for it, and pointers to the live CLI (`npx -y quota-axi`, `--help`, `--json` / `--full`). CLI output is the source of truth. Do not restate CLI instructions or claim that quota-axi recommends or ranks. Update the skill with `pnpm run build:skill` and verify it with `pnpm run build:skill -- --check`.
  264. ## How It Works
  265. ```
  266. ┌────────────┐
  267. │ quota-axi │
  268. └─────┬──────┘
  269. ▼
  270. ┌───────────────┐
  271. │ provider │
  272. │ adapters │
  273. └─────┬─────────┘
  274. ▼
  275. ┌───────────────┐ ┌──────────────┐
  276. │ local auth or │ ───▶ │ first-party │
  277. │ runtime │ │ APIs/loopback│
  278. └─────┬─────────┘ └──────┬───────┘
  279. ▼ ▼
  280. ┌───────────────┐ ┌──────────────┐
  281. │ CLI │ ───▶ │ normalized │
  282. │ fallbacks │ │ quota model │
  283. └─────┬─────────┘ └──────┬───────┘
  284. ▼ ▼
  285. ┌───────────────┐ ┌──────────────┐
  286. │ stale cache │ ◀─── │ TOON/JSON/TUI│
  287. └───────────────┘ └──────────────┘
  288. ```
  289. - **Live first** - provider HTTP calls and Antigravity's structured print command use 15 second timeouts, Codex JSON-RPC and Antigravity loopback reads use shorter per-call timeouts, and stale cache fallback is per provider.
  290. - **Host network policy** - Claude, Codex, Copilot, Cursor, Grok, Z.AI, Command Code, MiniMax, DeepSeek, OpenRouter, ElevenLabs, Devin, and Muse outbound HTTP calls honor standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables (including lowercase forms). This only follows the user's configured egress path; quota-axi does not expose a proxy service or print proxy URLs. New remote fetches go through `src/lib/http.ts` rather than global `fetch`. The proxy path pairs the installed `undici` build's `ProxyAgent` with that same build's `fetch`, because Node's global fetch only accepts a dispatcher from the undici build Node bundles.
  291. - **Opt-in secure-store access** - macOS Claude, Cursor CLI, Copilot CLI, and Muse Keychain value reads, plus Windows Copilot Credential Manager reads, are skipped on plain calls until `--allow-keychain-prompt` succeeds once for that source, then future quota calls reuse the corresponding grant.
  292. - **Delegated refresh, never minted** - when the same stored access token is expired, carries a refresh token, and is definitively rejected, quota-axi may run that vendor CLI's own smallest non-interactive refresh command and re-read the store the CLI rewrote. quota-axi never performs a refresh-token exchange itself. See [Delegated credential refresh](#delegated-credential-refresh).
  293. - **Partial success is success** - one provider can fail while another returns fresh or stale data, and the process still exits 0. Exit code 1 means every provider failed and the report is still rendered. Exit code 2 is a usage error (`VALIDATION_ERROR`). `quota` is the implicit default command: a bare call or a flag-first call is read as `quota`, while `auth`, `update`, a single-token `--help`, and a version flag stay with the SDK. Slow-path routing, help, exit framing, and `update` come from `axi-sdk-js` `runAxiCli`; machine TOON/JSON stays in `src/render.ts` and command bodies in `src/commands.ts`. A bare `-v`/`-V`/`--version` is answered by `axi-sdk-js/fast-path` plus the leaf `src/version.ts` (node builtins only), which imports the CLI only on the slow path so the provider graph never loads. Keep `src/version.ts` leaf-clean.
  294. - **No token equivalence** - quota-axi does not claim that one provider percentage equals another provider percentage.
  295. ## CLI Reference
  296. | Command | Description |
  297. | ---------------- | ---------------------------------------------------- |
  298. | `quota-axi` | Report supported local quota windows |
  299. | `auth` | Report local auth-source availability, no values |
  300. | `models` | Join curated model buckets with local quota evidence |
  301. | `update` | Upgrade quota-axi to the latest published version |
  302. | `update --check` | Report current vs. latest without installing |
  303. ### Flags
  304. | Flag | Description |
  305. | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
  306. | `--provider claude,codex,cursor,copilot,grok,kimi,zai,agy,alibaba,opencode-go,commandcode,minimax,mimo,deepseek,openrouter,elevenlabs,devin,muse,higgsfield` | Scope providers; repeat to union in first-seen order (`--provider zai --provider codex` equals `--provider zai,codex`) |
  307. | `--json` | Emit normalized JSON instead of TOON for quota, auth, or models |
  308. | `--full` | Include audit and derivation details |
  309. | `--tui` | Render the live human terminal report instead of TOON (quota only) |
  310. | `--refresh 30s\|5m\|1h` | Live `--tui` refresh interval, default 5m (30s-24h) |
  311. | `--once` | Render one `--tui` frame and exit instead of staying live |
  312. | `--theme light\|dark\|system` | `--tui` palette; flag overrides `QUOTA_AXI_THEME`, default `dark` |
  313. | `--all` | Draw not-set-up providers as full `--tui` cards |
  314. | `--allow-keychain-prompt` | Permit native secure-store access that could prompt (macOS or Windows) |
  315. | `--allow-claude-inference` | Spend one bounded native Claude inference to read env-token quota headers |
  316. | `--no-credential-refresh` | Never run a vendor CLI's own non-interactive credential refresh |
  317. | `--max-age 0\|90s\|2m` | Opt in to reusing a fresh reading up to this old instead of asking the vendor; `0` always asks |
  318. | `--profile-only` | Read one explicitly selected Claude or Codex credential file (quota only) |
  319. | `--intelligence high\|medium\|low` | Filter `models` by editorial intelligence bucket |
  320. | `--sort runway` | Explicitly sort `models` by documented usable-runway evidence |
  321. | `-h`, `--help` | Print terse [AXI](https://axi.md) help |
  322. | `-v`, `-V`, `--version` | Print version |
  323. ### Profile-only quota reads
  324. Profile-only mode is accepted only by `quota`, requires exactly one `--provider` selector, and supports only Claude and Codex. Claude requires an explicit nonblank `CLAUDE_CONFIG_DIR`; Codex requires an explicit nonblank `CODEX_HOME`. There is no default-location fallback in this mode, and `--allow-keychain-prompt` and `--allow-claude-inference` are rejected rather than ignored.
  325. It reads only `$CLAUDE_CONFIG_DIR/.credentials.json` or `$CODEX_HOME/auth.json`. It never reads the macOS Keychain or Pi auth, invokes a CLI RPC or other credential fallback, delegates a refresh, or reads, writes, clears, or persists quota cache data. `--full --json` retains non-secret account identity, the top-level source, and source attempts for provenance. Tokens and credential-file contents remain excluded. Ordinary output remains redacted.
  326. ```sh
  327. CLAUDE_CONFIG_DIR=/path/to/claude-profile quota-axi --provider claude --profile-only --full --json
  328. CODEX_HOME=/path/to/codex-profile quota-axi --provider codex --profile-only --full --json
  329. ```
  330. ### Fresh reuse
  331. A burst of back-to-back reads (a dispatcher that takes a fresh reading per decision, a test run) can trip a vendor's usage-endpoint rate limit and leave the provider unmeasured until the limit clears.
  332. Fresh reuse lets such a caller serve the last successful reading instead of asking the vendor again.
  333. It is opt-in: with neither `--max-age` nor `QUOTA_AXI_MAX_AGE`, every `quota` and `models` read asks the vendor.
  334. `--max-age <duration>` enables it for one call, and `QUOTA_AXI_MAX_AGE=<duration>` enables it for a host; the flag wins, so `--max-age 0` always asks the vendor.
  335. Both accept `0`, bare seconds, or a whole-unit duration up to one hour, and a `QUOTA_AXI_MAX_AGE` that does not parse fails the read with a validation error instead of being ignored.
  336. Ninety seconds absorbs a burst and moves a five-hour window's elapsed time by half a percent.
  337. A reading is reused only when all of these hold:
  338. - It came from the same credential selection: every environment variable a provider consults to choose a profile, store, credential, CLI, or deployment (`CREDENTIAL_SELECTION_ENV` in `src/lib/reuse-context.ts`) has the value it had, plus the same home directory and user. The values are hashed together and never stored.
  339. - No local file the reading was derived from has changed. Every file quota-axi opened for that provider, present or absent, is recorded with its identity, size, and modification times (never its contents), so a login that rewrites a credential store, or a Kimi Code configuration that now names another deployment, is read again. A store read through a vendor tool (the macOS Keychain, Cursor's SQLite database, a vendor CLI) is identified by the selection that names it, the same boundary the stale-cache context uses, so an in-place Keychain login switch can be reused for at most `--max-age`. Muse is excluded from this path: its macOS credential lives in a Keychain item that is not a traced file, so a login switch cannot be detected here, and `--max-age` never serves a Muse reading. The five-minute key-endpoint ledger remains the bound on those vendor calls. Higgsfield is excluded the same way: a CLI login switch does not change a traced file, and the status payload quota-axi already fetches has no stable non-email account discriminator (the email field is ignored and never stored), so `--max-age` never serves a Higgsfield reading.
  340. - Every lane the provider reported in that reading was a fresh reading with windows, so part of an account-expanded report is never served, and a failed, stale, or window-less lane makes the next read ask the vendor.
  341. - It is younger than `--max-age`, and no window has reached its own reported `resetsAt`, because a number that has stopped being true is never served ([#257](https://github.com/kunchenguid/quota-axi/issues/257)).
  342. The cache keeps one slot per provider lane, so two profiles that alternate each read the vendor; each still reuses its own reading between switches.
  343. `--full` is the audit tier and account identity and source attempts are never cached, so `QUOTA_AXI_MAX_AGE` does not reach it; it reuses only when `--max-age` is passed explicitly.
  344. `--profile-only` never reuses, and readings the cache excludes (Claude native inference and Copilot native secure-store readings) are never reused.
  345. With reuse enabled, a live `--tui` reuses on its first frame; a scheduled refresh reuses only a reading younger than the refresh interval, so it never repeats its own previous frame and still reads the vendor at any `--refresh`, unless `--max-age` is passed explicitly.
  346. Pressing `r` always reads the vendor, because it is an operator asking for a new reading now.
  347. With reuse enabled, processes that miss the cache together make one vendor read per provider and credential selection.
  348. The first creates a lock file under the cache directory, reads the vendor, and caches that provider's reading before releasing it; the others poll the cache and are answered by that reading through the same checks as any reuse.
  349. A waiter gives up after 30 seconds and reads the vendor itself, and a lock whose holder has exited, or that is older than two minutes, is taken over, so a crashed or wedged holder never blocks a read.
  350. If the holder's reading is not reusable (it failed, is stale, has no windows, or is a reading the cache excludes), nothing is cached and the waiters read the vendor together rather than one at a time, so a burst takes about one vendor round trip beyond the holder's, not one per waiter.
  351. Leaders of different providers merge their readings into the one cache file under a short lock of their own, so one leader's write never drops another's reading and leaves its waiters to read the vendor; if that lock is not free within five seconds the write goes ahead unlocked.
  352. The lock only saves vendor calls: a lost race costs an extra read, never a wrong one.
  353. A new environment variable a provider reads to choose a credential must be listed in `CREDENTIAL_SELECTION_ENV` (`src/lib/reuse-context.ts`) or declared non-selecting in `test/reuse-context.test.ts`. A new provider file read goes through the `src/lib/fs.ts` readers or `traceInput` (`src/lib/input-trace.ts`). quota-axi's own cache is read untraced, because every write changes it. `QUOTA_AXI_SNAPSHOT` is the fixture surface on the same path.
  354. A reused reading is a fresh reading, not a stale one: `state.status` stays `fresh`, `stale` stays `false`, and quota rows, pace, runway, and selection are derived as usual at the report's `generatedAt`.
  355. It is marked honestly on every surface: `--json` adds `state.reused: true` and keeps its `state.refreshedAt` (the time the vendor answered) in the default tier, default TOON adds a `reused` attention row naming that time, and the `--tui` card title says `reused 42s`.
  356. Reusing never rewrites the cache record, so its age keeps counting from the vendor's answer.
  357. Serving it as fresh is honest because the caller chose the bound: a reused reading is the vendor's own answer at `refreshedAt`, no older than the `--max-age` the caller asked for, and never past a window's reset, so a consumer that needs a newer number reads `refreshedAt` or passes a smaller `--max-age`.
  358. #### Snapshot fixtures
  359. `QUOTA_AXI_SNAPSHOT=<file>` makes `quota` and `models` answer every provider from that file instead of any credential or vendor, for tests and fixtures of tools that consume quota-axi output.
  360. The file uses the cache file format (`{"schemaVersion": 3, "providers": [...]}`), so a cache file captured from a real run is a valid fixture.
  361. Each provider's snapshots are served as reused readings with `sourcesTried: ["snapshot"]`, whatever their age; a provider the file does not name reports `unavailable` with `not_in_snapshot`, and one with a window past its own reset reports `unavailable` with `snapshot_expired`.
  362. A file that is missing, does not parse as that format, or holds a provider record that does not parse fails with `VALIDATION_ERROR` (exit 2) rather than reporting that provider as `not_in_snapshot`.
  363. Nothing is written to the cache, and the variable cannot be combined with `--profile-only`.
  364. ```sh
  365. QUOTA_AXI_SNAPSHOT=test/fixtures/quota.json quota-axi --json
  366. ```
  367. ### Human terminal report (`--tui`)
  368. `quota-axi --tui` renders the same redacted report as a live human terminal view instead of TOON: a two-up provider card grid with thin quota bars and a `┃` linear-pace marker whenever pace is known. It is presentation only and is not part of the machine-readable contract.
  369. - On an interactive terminal the report stays up and refreshes every 5 minutes until you press `q` (or Ctrl+C). Press `r` to refresh immediately; the footer lists both controls. `--refresh` sets the interval (30s-24h) and `--once` renders a single frame. A non-TTY stdout or stdin (pipes, CI, screenshots) always renders one frame and exits.
  370. - Every refresh re-runs the same quota read as a bare `quota-axi`, including [delegated credential refresh](#delegated-credential-refresh) when a stored session has expired in the meantime. Run `quota-axi --tui --no-credential-refresh` to keep the live report strictly read-only.
  371. - Live frames paint on the alternate screen and repaint immediately on terminal resize; quitting restores the screen and prints the final frame so the last report stays in scrollback.
  372. - Height comes from the terminal too. When the report is taller than the terminal, the live view windows it instead of letting the alternate screen (which has no scrollback) push the header and first cards out of reach. The viewport accounts for physical rows after terminal-width wrapping: a full-width visible line can consume its own row without wrapping the optional scroll affordance, which is omitted when it cannot fit. At five or more rows the header stays pinned; when there is room, the last row carries a scroll affordance naming how many report lines are above and below. Below five rows the header scrolls with the other report content, and at one row the scroll affordance is omitted so content still remains visible. Use `j`/`k`, the arrow keys, `PgUp`/`PgDn`, `Space`/`b`, or `g`/`G` to move the window. `renderQuotaTui` lays cards out for the width and returns every line that takes; `scrollFrame` in `src/tui-viewport.ts` windows that frame to the terminal, pins the first line, and clips oversized lines. The closing hint is composed outside `renderQuotaTui`, and the live paint has no trailing newline, so a frame that exactly fills the terminal does not scroll itself. Fold a provider only on positive evidence of absence. Declare an uncertain skip on the adapter that owns the source (`isUncertainSkip`) and a sibling-tool login as incidental (`incidentalSources`); do not special-case those in the TUI. The `tui.show` and `tui.accountLabels` preferences stay on the human path in `src/commands.ts` and `src/tui.ts` and never change the model or machine output. Scrolling clamps at both ends, survives a refresh, and re-clamps on resize; growing the terminal back past the report's height restores the whole frame and the ordinary `Press r to refresh · q to quit` footer. `--once`, non-TTY output, the final frame echoed on quit, and the TOON and JSON surfaces are all unaffected by terminal height.
  373. - Each live card with a combinable bound leads with the effective-availability rollup (min across bounding windows), colored by headroom: >=50% healthy, 20-50% tight, <20% critical. Per-window rows, including per-model breakouts, are the supporting detail.
  374. - Percentages and bars show what is left by default. To have every provider's headline, window rows, and bars show what has been used instead, set `tui.show` to `used` in the user config file `~/.config/quota-axi/config.json` (`$XDG_CONFIG_HOME/quota-axi/config.json` when `XDG_CONFIG_HOME` is set): `{ "tui": { "show": "used" } }`. That file is the only place the preference is read - there is no environment variable or flag for it - and it is read once when `--tui` starts, so restart a live report to pick up a change. Only the exact values `used` and `remaining` are recognized; a missing, unreadable, or malformed file, or any other value, keeps the default remaining view. The used view rounds the raw consumed percentage independently of the remaining view, so rounded figures need not sum to 100% (48.5% used / 51.5% remaining displays 49% used / 52% remaining). It labels each headline `49% used · week`. Its bar fill is consumption, the `┃` marker moves to the elapsed share of the window, and fill running past the marker means burning ahead of the reset clock. Health colors, runway verdicts, used-share rows, raw credit balances, and `?` rows read the same in both views. It is a human display preference only: quota-axi never reads the file outside `--tui`, so the default TOON, `--json`, `--full`, and the cache are byte-identical whatever it says.
  375. - Account lanes can be named for people. Each lane of a provider that [reports more than one account](#multiple-accounts) shows its opaque account key under the card title, so several `claude` profile cards look alike. Set `tui.accountLabels` in the same user config file to an object from a lane's `accountLocator.path` (the Claude config directory, written as an absolute or `~/` path) or from its account key to a name, and that lane's card title reads `claude · posam` instead of `claude`, with the account key still on the line below: `{ "tui": { "accountLabels": { "~/.claude": "personal", "~/.claude-work": "posam" } } }`. A [claude-swap](#claude-swap-accounts) lane has no locator, so name it by the account key its card shows: `{ "tui": { "accountLabels": { "claude-swap:9a1c20d6b88a9bcec745fb70": "team" } } }`. Paths are compared after `~` expansion and symlink resolution, so a trailing slash or a linked directory names the same lane; any other entry must equal the account key exactly, so a relative path names nothing. A label is trimmed and cut to 20 columns; a non-string or blank label, or a malformed setting, is ignored. Only a lane that reports an account key can carry a label, so a provider reporting a single lane keeps its plain title. Folded not-set-up lanes read `claude/posam` instead of `claude/profile:…`. Like `tui.show`, the file is read once when `--tui` starts, and the labels never reach TOON, `--json`, `--full`, or the cache.
  376. - A window with `shareOf` is a used-share, not an independent remaining pool: the row prints `N% of <parent>` (or `share of <parent>` when `percentUsed` is absent) instead of a remaining bar or `?`, so it cannot be read as missing data or as its own headroom.
  377. - The headline is labeled with the window it actually is: the minimum across bounding windows always equals at least one named window, so the label names the `limitingWindowIds` window (`week`, `session`, `credits`) and changes per provider and over time. Tied limiting windows read `credits + grok build`, compacting to `credits +2` when the names do not fit; a model- or product-scoped headline appends its scope, and any unresolved limiter falls back to the scope wording (`all models`).
  378. - In the default view, the bar fill is current headroom; the `┃` marker sits at the binding window's `pace.timeRemainingPercent`, the fill position of exactly linear burn. The headline marker therefore matches the corresponding `limitingWindowIds` sub-bar even when another window supplies the finite-runway `empty in` verdict. Fill ending left of the marker means burning faster than the reset clock. The marker is omitted when that window's pace is unknown.
  379. - Pace is shown by the bar and marker alone, never as a numeric burn multiple. The runway verdict on the headline reads `on pace ✓` for `through_reset` and `empty in 7h 21m` for `projected_exhaustion`. Two-up rows keep both card bottoms aligned by padding the shorter card inside its border. The TUI does not display the per-scope selection signal; that signal remains on the JSON and TOON machine surfaces. Those surfaces also keep the `through_reset` vocabulary, while `--full --json` exposes the complete `pace` object. The TUI renders from the complete in-memory model, so `--json` tiering never removes anything it draws.
  380. - A provider whose window relationships are wholly unknown (Copilot or Antigravity, with every window unresolved) has no combined effective percentage, pace, or runway to show, so its card replaces the headline block with a single `per-window usage · no combined bound` line and leads straight into its real per-window rows. Partially understood providers keep the effective-unknown headline. No combined headroom, pace, or runway number is invented.
  381. - Providers are grouped by what quota-axi found on this machine, and the header always counts all four groups in that order, for example `4 live · 1 stale · 2 need attention · 10 not set up`, including the ones that are empty. Every count is kept even in the narrowest supported terminal: a header that would not fit gives up its timestamp - the time zone first, then the date, then the clock - never a count. A fresh reading is live: an accented `●` and a full border. A stale cached reading is its own lane, counted apart from live. Its card uses a `◐` glyph and a dim border, and notes name when the snapshot was last refreshed and the error from the live read that failed, including `fetch failed` when the failure was the usage fetch. A provider without a reading whose sources found something (a credential that is expired, rejected, or waiting on a Keychain prompt, an installed tool that failed, or a request that failed) needs attention: it stays a dimmed full card right after the live and stale cards, with its remedy, and is excluded from the live total. A provider is not set up only when every credential source it checks was skipped as absent (no file, environment variable, CLI, or running app). A provider that recorded no sources at all still needs attention, so absence is never assumed, and so does one whose skip could not establish absence either way, such as a Copilot CLI account whose Keychain value still awaits `--allow-keychain-prompt` or a configuration that names no account quota-axi can confirm, a Kimi Code configuration quota-axi could not read to the environment it names, or an Antigravity CLI that is installed but timed out. A GitHub CLI login alone, or one Copilot refused, is not evidence of Copilot access and leaves Copilot not set up rather than broken; a `gh` store that could not be read, or a request through it that failed transiently, keeps Copilot in view.
  382. - Providers that are not set up fold into one dim footer line that names each of them and points at `quota-axi auth` for where each one is read. Press `a` in the live report to draw them as dimmed full cards under a `○ not set up · N` label, and press it again to fold them; while any are folded or expanded the closing line names the key, including when the report scrolls. `--all` starts the report expanded and is how a `--once` frame shows them. A provider named with `--provider` is never folded.
  383. - Width comes from the terminal, clamped to 80-120 columns; below the two-up width the grid reflows to one column. Color honors `NO_COLOR`, `TERM=dumb`, and non-TTY stdout (the glyph skeleton is kept), re-enables with `FORCE_COLOR`, and uses truecolor when `COLORTERM` advertises it, falling back to 256-color then ANSI-16.
  384. - The truecolor and 256-color palettes come in a dark (Catppuccin Mocha) and a light (Catppuccin Latte) theme. `--theme light|dark|system` picks one or follows the OS appearance; when the flag is absent `QUOTA_AXI_THEME` (same values) applies, and the default is `dark`. Light and system modes are opt-in only. `system` reads macOS appearance, Windows default app mode (AppsUseLightTheme), or GNOME’s `color-scheme` on Linux once per quota refresh (`--once` reads it once). The read has a 500 ms timeout; missing tools, errors, unsupported platforms, and unknown settings (including GNOME’s `default`) fall back to `dark`. A blank `QUOTA_AXI_THEME` is the same as unset. An invalid flag or variable value is a usage error, not a silent fallback. The ANSI-16 path is theme-independent and always uses the terminal's own colors.
  385. - `--tui` composes with `--provider` scoping, `--all`, and `--full` (account identity and source-attempt footers, including for folded providers). It is mutually exclusive with `--json` and only supported by the `quota` command; `--all` is only supported with `--tui`.
  386. ## Multiple accounts
  387. The reporting unit is the verified underlying subscription, not each credential route that can read it.
  388. A normal invocation reports every Codex ChatGPT subscription it can discover from sibling entries in one Pi `auth.json`.
  389. Claude reports more than its one selected profile only when `QUOTA_AXI_CLAUDE_PROFILES` ([Claude profiles](#claude-profiles)) or `QUOTA_AXI_CLAUDE_SWAP` ([claude-swap accounts](#claude-swap-accounts)) opts in.
  390. It keeps each account's quota windows, resets, plan, effective availability, runway, and `spendPriority` separate.
  391. Each account gets its own TUI card, naming its key on an `account <key>` line under the card title, including accounts whose quota cannot be read.
  392. The `default` key an expanded report fills in for single-account providers is a schema artefact, so the TUI leaves it out of both the card and the `--full` footer; TOON and JSON still publish it.
  393. ```sh
  394. quota-axi --provider codex --json
  395. quota-axi --provider codex --tui --no-credential-refresh
  396. quota-axi --provider codex --full --json # adds vendor identity and source attempts per key
  397. ```
  398. Pi's built-in provider id is `openai-codex`.
  399. `pi-codex-accounts` stores additional logins under ids such as `openai-codex-work` in the same file.
  400. quota-axi enrolls those already-present keys; it does not read `codex-accounts.json`, copy tokens, launch Pi, or change the active account.
  401. Discovery order is the built-in `openai-codex` entry, then other `openai-codex-*` keys in lexical order.
  402. Two keys that carry the same stored `accountId` are the same ChatGPT account and are not reported as extra capacity.
  403. The later key stays a credential fallback until a probe succeeds or every candidate is rejected.
  404. The lane keeps the first key as its `accountKey`, while `source` names the key that answered.
  405. See [Account keys and compatibility](#account-keys-and-compatibility) for how consumers join folded keys to a row.
  406. A key whose identity cannot be compared is left as its own lane so the uncertainty stays visible.
  407. When only the built-in Pi entry (or none) is present, Codex keeps its existing single-winner path: native `$CODEX_HOME/auth.json`, then `openai-codex`, then the CLI fallback.
  408. That row's `accountKeys` names the key of the credential that produced it: `codex-home` for the native login or CLI fallback, `openai-codex` for the built-in entry. A failed row names the credential it speaks for, and a stale row names the one that produced its cached snapshot. The other key is added when the native login and the built-in entry store the same `accountId`. A `--profile-only` row is always `codex-home`.
  409. When siblings are present and a native `$CODEX_HOME/auth.json` exists, that login stays first as its own `codex-home` lane, read from `auth.json` and then the CLI fallback.
  410. The built-in `openai-codex` entry whose stored `accountId` matches the native login is not a separate lane; it stays the native lane's fallback, as it was before.
  411. Without a native `auth.json`, an installed Codex CLI fallback is probed once as the `codex-home` lane.
  412. The lane is left out only when the app-server's `account/read` positively reports no ChatGPT login (`account: null` or a non-ChatGPT account).
  413. A reading without the optional `accountId` stays its own lane with no identity.
  414. A failed CLI reading is shown as stale or unavailable only when `account/read` confirmed a ChatGPT login or a `codex-home` snapshot is cached; a probe that fails before that evidence adds no lane, and `auth` still shows the `cli-rpc` source.
  415. A native login (from `auth.json` or the CLI) for the same account as a Pi lane is not a second lane.
  416. The account is compared by the vendor `accountId` a fresh reading reports, or else the stored one; email, tokens, and key names are never used as identity.
  417. That Pi lane keeps its own reading when fresh, and shows the native reading when its own is expired, rejected, or stale and the native one is fresh, or when only the native one has stale cached windows.
  418. A proven sign-out retires only cached Codex snapshots whose stored account identity matches the rejected credential; a native login that coalesces into a Pi lane no longer removes the shared `codex-home` slot by name, so another account's snapshot cannot be discarded.
  419. `--profile-only` still reads one native Codex file and never opens Pi auth.
  420. ### Claude profiles
  421. Claude account lanes are opt-in. When `QUOTA_AXI_CLAUDE_SWAP` is not enabled and `QUOTA_AXI_CLAUDE_PROFILES` is absent, blank, or lists no entry, Claude reads only the profile this process selects, and the report, its schema, and the cache slot it uses are exactly what they are without these features: one keyless lane, quota schema 5, `accountKeys: ["default"]`. quota-axi never searches the home directory for other Claude profiles.
  422. ```sh
  423. QUOTA_AXI_CLAUDE_PROFILES="$HOME/.claude-work:$HOME/.claude-team" quota-axi --provider claude --json
  424. QUOTA_AXI_CLAUDE_PROFILES="$HOME/.claude-work:$HOME/.claude-team" quota-axi --provider claude --full --json # adds accountLocator per lane
  425. ```
  426. - The value lists Claude config directories separated by the platform path delimiter (`:` on macOS and Linux, `;` on Windows). Write each one exactly as you would set `CLAUDE_CONFIG_DIR`: Claude Code hashes the raw path to name a profile's Keychain item, so quota-axi does not trim entries, expand `~`, or resolve relative paths. Empty entries are ignored, and a relative entry fails the read with `VALIDATION_ERROR` (exit 2) whenever `claude` is in scope, like a malformed `QUOTA_AXI_MAX_AGE`.
  427. - Lanes are reported in this order: the process-selected profile first (`CLAUDE_CONFIG_DIR`, `CLAUDE_SECURESTORAGE_CONFIG_DIR`, `CLAUDE_CODE_OAUTH_TOKEN`; exactly the lane a run without the variable reports), then the default profile (`~/.claude` with no `CLAUDE_CONFIG_DIR`, whose macOS Keychain service is the unsuffixed `Claude Code-credentials`), then each listed directory in order. Profiles that read the same credential store are reported once, at their first position: on macOS the same config directory and Keychain service, elsewhere the same real directory.
  428. - The selected profile and every listed directory always get a lane, because the user named them, including a listed directory that is also the default profile. A listed directory with no credential reports that as its own reading through the same rules as the selected profile (for example `auth_required` with `credentials_missing`, marked `notSetUp: true` in JSON and drawn as an attention row in TOON) instead of silently disappearing. The default profile was not named, so it joins only on positive evidence that it holds a credential: its native `.credentials.json` (off macOS, or with no secure-storage selector), or its exact Keychain item, found from metadata without reading a value or prompting.
  429. - Each lane reads only its own store. Only the selected lane consults `CLAUDE_CODE_OAUTH_TOKEN` and may run the delegated `claude doctor` refresh; every other lane is read-only and never uses a sibling's token. A lane never takes another listed profile's Keychain item for its own opaque default item.
  430. - Keychain consent stays per item: a lane reads its Keychain value only under its own grant marker or `--allow-keychain-prompt`. When a sibling lane needs a grant, its `state.remedyCommand` selects exactly that profile, for example `env -u QUOTA_AXI_CLAUDE_PROFILES CLAUDE_CONFIG_DIR='/Users/me/.claude-team' quota-axi --provider claude --allow-keychain-prompt` (the default profile's command unsets `CLAUDE_CONFIG_DIR` instead), so one approval records that one item's marker.
  431. - A sibling lane whose stored session expired with a refresh token present reports `state.reason: credentials_expired` with `state.remedyCommand` naming that profile's own refresh, for example `CLAUDE_CONFIG_DIR='/Users/me/.claude-team' claude doctor`, plus an agent-directed JSON `help` entry. A secure-storage selector set in the environment is unset in both commands, because it would override the profile.
  432. - Each lane's key is `profile:` plus 24 hexadecimal characters of a one-way digest of the profile's own store (on macOS the config directory and Keychain service, elsewhere the real config directory). It contains no path, token, or email, does not move when `CLAUDE_CODE_OAUTH_TOKEN` is exported, and names the lane's cache slot.
  433. - `--full` adds `accountLocator: { kind: "config-dir", path, keychainService, delegateEligible }` to each expanded lane, so a consumer can map a lane to the `CLAUDE_CONFIG_DIR` that selects it, and the default lane by `keychainService: "Claude Code-credentials"`. One exception: on macOS, when the selected lane's Keychain service comes from `CLAUDE_SECURESTORAGE_CONFIG_DIR`, `path` alone is not a complete selector, because setting only that `CLAUDE_CONFIG_DIR` names a different Keychain item; the locator does not publish the secure-storage selector, only the resulting `keychainService`. `keychainService` is present on macOS only, and `delegateEligible` is `true` only on the process-selected lane. `--full` TOON adds the same fields to `accounts[]` as `locatorKind`, `locatorPath` (home shown as `~`), `keychainService`, and `delegateEligible` columns whenever any row has a locator, and the `--tui --full` footer shows the lane's path. The locator is never in default output, and a single surviving lane keeps the legacy keyless shape with no locator.
  434. - Each lane is cached and served stale under its own profile context, and a definitive sign-out retires only that lane's snapshot; a sibling's stays.
  435. - Two lanes signed in to the same Anthropic account and organization are one subscription and coalesce as described below. Claude identity for this purpose is the verified account id plus the organization the bearer is scoped to, because one login can hold seats in several organizations, each with its own limits; a reading whose organization is not reported stays its own lane.
  436. - The `--tui` report can name each lane by its config directory or account key with `tui.accountLabels` ([Human terminal report](#human-terminal-report---tui)); agent output keeps only the account key.
  437. - `--profile-only` ignores the variable and keeps reading exactly one file.
  438. ### claude-swap accounts
  439. `QUOTA_AXI_CLAUDE_SWAP=1` (or `true`) is an opt-in for people who run the third-party [claude-swap](https://github.com/realiti4/claude-swap) to hold several Claude accounts. Instead of reading Claude's own stores, quota-axi then runs claude-swap's non-interactive `cswap list --json` (fixed argv, resolved on `PATH`) and reports one lane per account it lists. Only the real executable is launched directly; a Windows `.cmd` or `.bat` launcher is reported as `claude_swap_unavailable` with `remedyCommand: pipx install claude-swap`, and can instead be replaced by the `cswap.exe` installed through uv. Unset or any value other than `1` or `true`, Claude behaves exactly as it does without the variable and `cswap` never runs.
  440. ```sh
  441. QUOTA_AXI_CLAUDE_SWAP=1 quota-axi --provider claude --json
  442. QUOTA_AXI_CLAUDE_SWAP=1 quota-axi --provider claude --full --json # adds source attempts and claude-swap's account labels
  443. ```
  444. - quota-axi takes no credential or token from claude-swap: it reads only the account labels and usage that command prints, and sends no request of its own for these lanes. The child receives only set values from this environment allowlist: `HOME`, `PATH`, `USER`, `LOGNAME`, `SHELL`, `TMPDIR`, `TMP`, `TEMP`, `LANG`, `LC_ALL`, every `LC_*` variable, `TERM`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and `XDG_CACHE_HOME`; Windows additionally allows `SystemRoot`, `USERPROFILE`, `APPDATA`, `LOCALAPPDATA`, `PATHEXT`, and `COMSPEC`, matched case-insensitively. Claude, Anthropic, other provider, and quota-axi variables are not inherited. The command is claude-swap's own; it may fetch usage from Anthropic and renew credentials it manages under its own polling policy. For that reason, `--no-credential-refresh` does not run `cswap` and reports Claude unavailable with `claude_swap_refresh_disabled`. quota-axi otherwise waits up to 30 seconds and then walks away without signalling it, like a [delegated refresh](#delegated-credential-refresh). Command output goes to a private `0600` temporary file so a timed-out child keeps a writable destination without keeping quota-axi alive; completed output is read within a 1 MiB bound and then removed. A timed-out child's output is removed when it exits, or when quota-axi exits first.
  445. - It reads claude-swap's JSON schema 1 (verified against claude-swap 0.26). Every account row must carry a non-empty `email`, string `organizationUuid` (which may be empty), non-empty `usageStatus`, and `usage` as an object or null; `organizationName` is optional but must be a string when present, and an object-valued `usage` requires a parseable `usageFetchedAt`. The complete source is malformed if any listed row violates that schema or produces a repeated lane key. `usage.fiveHour` and `usage.sevenDay`, when present, require a finite numeric `pct`; `resetsAt` must parse when present, and claude-swap omits it for a window that has not started. Their percentages are claude-swap's copies of the Anthropic usage endpoint's `utilization`, which is percent used, so they map through the native Claude normalizer to `five_hour` and `seven_day` windows with the same trusted durations. `resetsAt` passes through, and a window without one is treated like a native untriggered window. Nothing else is read: `usage.scoped`, `active`, `number`, `alias`, `spend`, and claude-swap's pace and projection fields are not published.
  446. - Each lane's key is `claude-swap:` plus 24 hexadecimal characters of a one-way digest of the account's email and organization UUID, so it survives slot renumbering and contains no email. Lanes keep claude-swap's order, which carries no preference.
  447. - A lane's `refreshedAt` is claude-swap's `usageFetchedAt`, and a window whose reset has passed since then is dropped. An account whose `usageStatus` is not `ok`, or that has no window left, is its own `unavailable` lane with `state.error: claude_swap_<usageStatus>` (or `claude_swap_usage_unavailable`) rather than disappearing; quota-axi does not treat claude-swap's status as a sign-out.
  448. - `--full` reports `source: cli` with a `claude-swap` attempt, and `account` with claude-swap's `email` and `organizationName` marked `identityStatus: unverified`. With no verified account id, lanes never coalesce: two seats are never combined.
  449. - These lanes are not cached and never served stale; claude-swap keeps its own last-good usage. `auth` never runs `cswap` and continues to inspect Claude's selected native credential.
  450. - When `cswap` is missing, exits nonzero, outruns the wait, or prints anything but schema 1 whose complete account list passes the schema above with unique lane keys, Claude reports unavailable with a `claude_swap_*` reason and never falls back to native Claude.
  451. - The variable takes precedence over `QUOTA_AXI_CLAUDE_PROFILES`, and `--profile-only` ignores it.
  452. ### Same subscription across sources
  453. After a provider's lanes have been read, collection coalesces readings that share a provider-supported subscription identity.
  454. That identity is `account.accountId` when it is present and not marked `identityStatus: unverified`; Claude narrows it to that account in the organization the bearer is scoped to, and a Claude reading without an organization has no comparable identity.
  455. Email, token, credential path, profile label, and runner name do not establish equality or distinctness.
  456. Missing or incomparable identity stays its own lane so the uncertainty stays visible: quota-axi does not guess a merge, and it does not invent extra capacity by summing those lanes.
  457. A successful response that supplies comparable identity missing from the local store is enough to coalesce the resulting cards.
  458. When two readings share an identity, the usable one is published (fresh over stale over a rejected source) and the other is not a second card.
  459. The published row's `accountKeys` lists every coalesced lane, the winner's key first, so a consumer still binds either credential route to that one row.
  460. Between two stale readings, the one refreshed more recently is published.
  461. Windows are never summed, averaged, or concatenated across those readings.
  462. Every lane keeps its own cache slot: a coalesced lane that also read fresh has its snapshot saved in the same cache write as the published reading, and a lane that served its own stale snapshot keeps it.
  463. So when that route fails on a later run, its snapshot still joins the other lane's reading instead of reappearing as a separate unavailable report, and when every route fails the subscription is still served once.
  464. A cached snapshot also records a SHA-256 hash of the verified subscription identity it was read from (never the id itself), so a stale reading served from one lane still coalesces with a fresh reading of the same subscription from another.
  465. Machine-readable output and the TUI share the same coalesced provider list.
  466. Codex still discovers and folds its own native and Pi lanes as described above; this collection step is the shared contract any multi-account provider goes through.
  467. ### Account keys and compatibility
  468. When a provider expands to multiple accounts, the report uses quota `schemaVersion: 6` (auth and models use version 2).
  469. Every provider record then has an `accountKey`; providers still using one selected account use the literal `default`.
  470. Every quota-axi output quota row, in schema 5 and schema 6 alike, has `accountKeys`: the credential keys that one row covers, own `accountKey` first, then any keys folded into it in the order the provider recorded them. The exported `ProviderQuota.accountKeys` type remains optional so package consumers can construct reports without it; quota-axi output sets it on every quota row.
  471. A row covering one credential lists just its own key. A consumer that holds a credential key binds the row whose `accountKeys` contains that key. Matching `accountKey` alone misses a key that was folded into another row.
  472. A provider without account discovery lists `accountKeys: ["default"]`, the same literal as its schema 6 `accountKey` filler. A discovering provider that stays on one row, such as two Pi keys for one account with no native login, keeps schema 5 and no `accountKey`, and its `accountKeys` starts with that lane's key.
  473. Membership mirrors quota-axi's own grouping exactly: every key the provider grouped into the row, and no other. That grouping relies on stored account identity when no fresh live reading confirms it, so a fold is published as applied even when a later live reading names a different account.
  474. `accountKeys` is a quota JSON field. Auth still lists each discovered lane on its own, because a fold that depends on the quota reading has not happened there. TOON does not add a column: its flat blocks already name the published lane by `accountKey`, and the membership list is the JSON account row's join field.
  475. The shared account collector puts each discovered lane's key first; an adapter adds folded keys to its quota reading's `ProviderQuota.accountKeys`, including keys learned during the read. Codex and, when `QUOTA_AXI_CLAUDE_PROFILES` or `QUOTA_AXI_CLAUDE_SWAP` opts in, Claude are the adapters that discover accounts today; other providers report `default`. The list itself is not cached; Codex reconstructs a stale row's originating key from the cached credential source.
  476. Every flat TOON block adds `accountKey` immediately after `provider`, and the quota/exhaustion/attention join becomes **`provider` + `accountKey` + `scope`**.
  477. Models and model sort ties use **`provider` + `accountKey` + `id`**.
  478. Models `unmatchedWindowIds` entries gain the same key, so an unmapped window reads `provider/accountKey/scope` instead of `provider/scope`; the key keeps two accounts of one provider from reporting the same unmapped window indistinguishably.
  479. Declaration order remains non-preferential; quotas are never combined across accounts, and never summed across coalesced routes of one subscription.
  480. A Codex Pi lane's key is the auth.json provider id (`openai-codex`, `openai-codex-work`); the native Codex lane's key is `codex-home`.
  481. It is stable across refreshes and discovery order and contains no token, email, or path, and it also names the account's cache slot.
  482. A lone lane keeps the legacy keyless slot, which the single selected account uses too, so the snapshot itself records the stored ChatGPT account id of the credential that produced it (see [Cache](#cache)).
  483. A key the report cannot publish (malformed or repeated) costs only its own lane: the lanes with usable keys still expand, so one unreadable entry never hides the accounts beside it.
  484. The provider normally falls back to its single selected account only when no usable lane remains; a source-owned failure lane, such as enabled claude-swap being unavailable, keeps that source's failure instead.
  485. `--full` adds the vendor identity the usage endpoint supplied, when any.
  486. If no provider expands, existing fields retain their shape and order, while quota JSON adds `accountKeys`: quota schema 5, auth/models schema 1, and no account column.
  487. A sole discovered Pi sibling uses that legacy representation.
  488. Expansion follows the lanes discovered rather than the rows published, so when a native login and a Pi sibling turn out to be one account the single surviving row still carries its key and the report stays schema 6.
  489. Consumers must honor the schema version; a legacy keyless row means the single selected lane, and keys must never be inferred from row position.
  490. Account collection is shared in `src/providers/accounts.ts`.
  491. Adapters can implement `ProviderAdapter.discoverAccounts` with stable keys and bound quota/auth readers; collection preserves each account's success or failure.
  492. Codex Pi sibling entries are the first discovery implementation on this tree, opt-in Claude profiles the second, and opt-in claude-swap accounts the third. An adapter may also name each lane's local selector as `ProviderAccount.locator`; the collector publishes it as `accountLocator` on an expanded lane's row, in `--full` only.
  493. Other adapters retain their existing source-selection behavior.
  494. ## Output Model
  495. The `quota` command's `--json` emits `schemaVersion: 5`, or `6` when a provider expands to multiple accounts.
  496. ### Normalized schema contract
  497. The package publishes TypeScript declarations from its package root, so consumers can use `import type { QuotaAxiResponse, ModelsResponse } from "quota-axi"`. The adapter contract is `ProviderAdapter` in and normalized `ProviderQuota` out: adapters report observed quota data, never rank, mint credentials, or retain raw responses. The narrowly bounded vendor-owned renewal path is documented under [Delegated credential refresh](#delegated-credential-refresh).
  498. `schemaVersion` is command-specific. Additive fields do not bump it. A semantic or incompatible shape change does. The legacy single-account `quota` report is version 5, `auth` is version 1, and `models` is version 1. When account discovery expands a provider, those versions are 6, 2, and 2 respectively. For quota row membership, see [Account keys and compatibility](#account-keys-and-compatibility).
  499. ### Default report blocks
  500. Default TOON is organized by the reading agent's decision rather than by quota-axi's data structures:
  501. | Block | Rows |
  502. | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  503. | `quota[]` | One row per **measurable** scope: `provider`, optional `accountKey`, `scope`, `effectivePercentRemaining`, `spendPriority`, `runway`, `confidence`, `limitedBy`, `resetsAt`. Every column is populated on every row. `limitedBy` is the scope's `limitingWindowIds`, and `resetsAt` is that binding window's own reset. |
  504. | `exhaustion[]` | **Sparse.** One row per scope with a finite exhaustion point: `usableRunwaySeconds`, `projectedExhaustedAt`, `limitingWindowId`. `exhaustion[0]:` means nothing is projected to run out. |
  505. | `attention[]` | **Sparse.** Every non-nominal fact: `provider`, optional `accountKey`, `scope`, `kind`, `detail`, `remedy`. |
  506. A `quota[]` row whose `runway` is `projected_exhaustion` or `exhausted_now` has exactly one matching `exhaustion[]` row, joined on `provider` + `scope` (plus `accountKey` in an account-expanded report). A row with `through_reset` or `unknown` has none, by definition: `through_reset` deliberately has no deadline and `unknown` has none to state.
  507. `attention[]` kinds:
  508. | `kind` | `scope` | Meaning |
  509. | ------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  510. | `stale` | `all` | The report is stale diagnostic data. `detail` names the last refresh, `fetch failed` plus `state.error` when a usage fetch failed, and any `state.reason`; no scope gets a `quota[]` row. |
  511. | `auth_required`, `rate_limited`, `unavailable`, `error` | `all` | The provider state status. `detail` is `state.error`, any `state.reason`, plus the retry-after instant when `state.retryAfter` is set. |
  512. | `no_quota` | `all` | The provider reported no measurable scope and no raw credit balance. Emitted when nothing else names it or when needed to preserve `state.authStatus`. |
  513. | `credits` | `all` | The provider reported a raw credit balance but no measurable scope. `detail` states that balance verbatim; no percentage or bound is derived from it. |
  514. | `jobs` | `all` | A PHI-safe sample of vendor job outcomes. `detail` is `sampled N · completed N · failed N · other N`. JSON also carries structured `jobs.{sampled,completed,failed,other}`. |
  515. | `unresolved_windows` | `all` | `quotaSemantics.unresolvedWindowIds`: unfamiliar vendor windows not folded into any bound. |
  516. | `untrusted_windows` | `all` | `state.untrustedWindowIds`: limits that could not be parsed authoritatively. |
  517. | `share` | `all` | A window is a used-share of another window, not an independent allowance. `detail` is `<id> of <parent>` plus ` · <percentUsed>` when that figure is present. It bounds no scope. |
  518. | `headroom_unknown` | scope | The scope reports no effective percentage for a reason other than a bound conflict. `detail` names the windows that block it and any finite runway verdict with its limiting window. |
  519. | `bound_conflict` | scope | A window the scope only inherits reads zero while the scope's own windows still report allowance. `detail` names both sides. The scope gets no `quota[]` row and no `exhaustion[]` row. |
  520. | `unmeasurable` | scope | Headroom is known but a bound blocks `runway`, `spendPriority`, or both. `detail` names which. |
  521. | `degraded_source` | `all` | A source was broken or unreadable while a sibling source answered: a superseded credential source, or Higgsfield's failed auxiliary `account transactions` / `generate list` read. `detail` is `<source> · <error>`. One row per source, only on a fresh reading. |
  522. | `reused` | `all` | A fresh reading was reused instead of asking the vendor again. `detail` is `last refreshed <refreshedAt>`. See [Fresh reuse](#fresh-reuse). |
  523. `remedy` carries `state.remedyCommand` when one exists, and situational agent-directed advice is still prepended to `help`.
  524. Two invariants hold for every report:
  525. - **Every requested provider appears at least once**, in `quota[]` or `attention[]`, except providers with positive evidence of absence, which default TOON omits and counts in a help line; `--full` and `--provider` name them. A provider that remains in the report with no `quota[]` row always states its `state.authStatus` - including a positive `usable` - as `(auth <status>)` in its `attention[]` detail. In an account-expanded report a provider is omitted only when every one of its lanes is absent.
  526. - **`quota[]` rows stay in provider-declaration order**, never sorted by any metric. A compact table with a `spendPriority` column must never read as a published ranking.
  527. The omission help line sits after any situational advice and before the tier hint:
  528. ```text
  529. 10 providers not set up are omitted; run `quota-axi --full` to list them
  530. ```
  531. One omitted provider uses the singular (`1 provider`, `is`, `it`). A machine with nothing set up still prints `quota[0]`, `exhaustion[0]`, and `attention[0]` plus that line, and still exits 1. `--full` prints the omitted rows and no omission line. Exit codes are otherwise unchanged.
  532. An unknown or stale scope deliberately gets **no** `quota[]` row: the absence of a number is the correct encoding of "no number", and the scope is named in `attention[]` instead.
  533. ### Output tiers
  534. `--full` adds; it never subtracts. Default TOON carries the three decision blocks; `--full` TOON adds the `providers[]`, `windows[]`, `scopeAudit[]`, `accounts[]`, and `attempts[]` audit blocks. Default `--json` carries the normalized model with derivation inputs demoted; `--full` restores them with **no renames and no re-nesting** - a demoted field is simply absent until `--full`, in the exact position and under the exact name it has there.
  535. | Demoted to `--full` in `--json` |
  536. | ---------------------------------------------------------------------------------------------------------------------------------------------- |
  537. | `providers[].label`, `providers[].source` |
  538. | `state.refreshedAt`, `state.sourcesTried` |
  539. | `windows[].percentUsed` (kept when the window carries `shareOf`, where it is the only figure), `windows[].startsAt`, `windows[].windowSeconds` |
  540. | `windows[].pace.timeRemainingPercent`, `elapsedPercent`, `cycleBasis`, `cycleSeconds`, `projectedExhaustedAt`, `projectionConfidence` |
  541. | `quotaSemantics.description` |
  542. | `effectiveAvailability[].pace.behindWindowIds`, `onPaceWindowIds` |
  543. | Account identity (`account`), account-lane `accountLocator`, and per-source `attempts` |
  544. Everything a consumer branches on stays in the default tier: `accountKey` and `accountKeys` on an account row; `state.status`, `stale`, `authStatus`, `error`, `reason`, `remedyCommand`, `retryAfter`, `untrustedWindowIds`, and `degradedSources`, plus `reused` and a reused reading's `refreshedAt`; window `pace.status`, `reason`, `reservePercentPoints`, `burnMultiple`, and `shareOf` together with that share window's `percentUsed`; `quotaSemantics.status` and `unresolvedWindowIds`; every scope's `effectivePercentRemaining`, `boundedBy`, `limitingWindowIds`, `boundConflict`, `runway`, `selection`, and pace `aheadWindowIds` / `unknownWindowIds` / `worstReservePercentPoints`; provider `jobs` counts; and sparse `notSetUp`. `credits` also stays, so a consumer can avoid misreading it as exhaustion.
  545. `notSetUp: true` is present only on a provider lane that has positive evidence of absence (the same `providerPresence` classification the human report uses). Every provider stays in `providers[]` on both default `--json` and `--full`; omitting entries would change downstream consumers that look a provider up by id. The field is additive, so `schemaVersion` stays 5, or 6 when a provider expands to multiple accounts. Default TOON is the only output that omits these providers.
  546. `--tui` renders from the complete in-memory model, so demotion never changes what the human report draws. Demotion happens only in the renderer (`quotaJsonReport` and `renderQuotaToon` in `src/render.ts`). Presence for an absence marker and for a TOON omission is classified in `quotaCommand` before redaction.
  547. ### Quota report shape
  548. | Object | Fields |
  549. | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  550. | Quota report | `providers` |
  551. | Provider report | `provider`, optional `accountKey`, `accountKeys` (every quota row), `windows`, `quotaSemantics`, `state`, optional `plan`, optional `credits`, optional `jobs`, and optional `notSetUp` |
  552. | Provider report with `--full` | Also `label`, `source`, optional `account` identity, optional `accountLocator`, and per-source `attempts` |
  553. | Account identity (`--full`) | Optional `email`, `organization`, `accountId`, and `identityStatus` |
  554. Account identity and per-source `attempts` are omitted unless `--full` is passed.
  555. Claude `identityStatus` is `verified` only when Anthropic returns an authoritative account identifier; `email` and `organization` are display-only and must not be used for duplicate detection.
  556. ### Provider `state`
  557. | Field | Description |
  558. | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
  559. | `status` | Provider status |
  560. | `stale` | Whether the provider report is stale |
  561. | `sourcesTried` | Sources tried for the provider (`--full`) |
  562. | `refreshedAt` | Optional refresh timestamp (`--full`) |
  563. | `error` | Optional error |
  564. | `retryAfter` | Optional retry-after state |
  565. | `reason` | Optional reason |
  566. | `remedyCommand` | Optional remedy command |
  567. | `untrustedWindowIds` | Optional identifiers for limits that could not be parsed authoritatively |
  568. | `authStatus` | Optional machine-readable local auth usability: `usable`, `expired_refreshable`, or `unusable`. Distinct from quota freshness and from human `error` prose. |
  569. | `degradedSources` | Optional `{ source, error? }` list of sources that failed or were superseded while a sibling answered, on a fresh reading; see the `degraded_source` row. |
  570. | `reused` | Optional `true` when this fresh reading was reused from the cache; `refreshedAt` then stays in default `--json` |
  571. When stale or unavailable quota is likely fixable by a one-time native secure-store grant, `state.reason` is `keychain_access_required`, `state.remedyCommand` supplies the runnable grant command (Copilot's includes `--provider copilot`), and for Claude, Cursor, and Muse JSON also includes an agent-directed `help` entry. That remedy is offered only for `keychain_prompt_required`; backend-specific consent behavior is described in [Provider notes](#provider-notes). A denied or timed-out Keychain outcome is reported as `keychain_access_denied` or `keychain_prompt_timeout` and stays silent no longer, but it does not advertise `--allow-keychain-prompt`. For Claude, macOS `security` exit 44 is cannot-reach (`keychain_unreachable`), not item-absent: it is not signed-out, and it does not retire the Claude cache. A successful metadata listing covering every keychain in the search list, with no matching or unrecognized Claude item, is the only evidence that establishes a missing Claude Keychain source; an empty, partial, or failed listing proves nothing and falls back to the exact profile-and-account read.
  572. When no Grok credential establishes usability but at least one still has a valid literal refresh token, `state.authStatus` is `expired_refreshable` and `state.status` is `unavailable` (not `auth_required`). Stored-expired bearers are first tested with bounded read-only liveness attempts; this classification stands only after the credential's own model catalog definitively rejects it or cannot decide, and an empirically live bearer reports fresh quota or `usable` instead. The `grok` remedy (`state.reason: credentials_expired`, `state.remedyCommand: grok`, plus an agent-directed JSON `help` entry telling the user to run the Grok CLI once) is emitted only when the same refreshable CLI candidate is rejected by both consumer quota and the official Grok Build model catalog. It survives the delegated `grok models` refresh, so it names the case where that delegate could not run or did not recover the session (see [Delegated credential refresh](#delegated-credential-refresh)). A transient failure does not trigger the remedy. If Grok CLI OIDC is refreshable and Pi is not usable, `state.error` is `Grok access token expired`. If only Pi `xai` OAuth is refreshable, `state.error` is `Pi xAI access token expired` and no Grok CLI remedy is emitted because Grok cannot refresh Pi-owned credentials. A Kimi soft expiry uses the same `credentials_expired` reason; its `pi` or `kimi` remedy is described in the [Kimi provider notes](#provider-notes). Default JSON exposes `authStatus`; for a provider shown in compact TOON without a `quota[]` row, a defined auth status appears as `(auth <status>)` in `attention[]`. Providers omitted because they are not set up follow [Default report blocks](#default-report-blocks). Source-appropriate advice is included only when a remedy exists. Full output shows the attempts: `model_auth_probe_live` means the credential's official model catalog accepted it but exposed no numeric quota. `attempts[].error: credentials_expired` marks a stored-expired credential that was not attempted.
  573. True Grok sign-out or definitive remote rejection uses `state.authStatus: unusable` with `state.status: auth_required` and `state.error: Grok sign-in required` (no `credentials_expired` reason). For official Grok Build OIDC and Pi OAuth, a rejection from the consumer Usage-page operation alone is not that verdict because those access tokens can have a different audience; the matching first-party model catalog must reject the same bearer too. `authStatus: unusable` by itself only means that no source established usability; for example, a Pi credential-resolution failure instead has `state.status: error`. Callers must branch on `authStatus`, `status`, and `reason`, not on human error prose alone, and must not treat `expired_refreshable` as logged out.
  574. When Grok Build or Pi `xai` OAuth passes its model-catalog probe after consumer-quota rejection, or a local Pi `xai` API key establishes model-only usability, and no sibling supplies consumer quota, `state.authStatus` is `usable`, windows stay empty, and `state.error` is `Grok model access available; quota unavailable` rather than sign-in required. Only transient consumer-quota failures and `expired_refreshable` soft expiry remain eligible for same-source stale fallback; a definitive sign-out (`auth_required`) retires the cached snapshot and reads the same with or without a cache. Model-only success does not inherit old quota windows. This is authenticated-but-unmeasurable, not a percentage or evidence of unlimited capacity.
  575. A provider with more than one credential source consults them in its fixed declared order and reports the one that works, so a broken store never speaks for a provider whose sibling store still answers. A store's own expiry field is advisory within that source, never a verdict or a reason to reorder sources: a stored-expired credential is still probed in its source's declared position because only the provider's own endpoint can establish that a credential is dead. The superseded source is not discarded: `state.degradedSources` names it on the fresh reading, and default TOON emits a `degraded_source` attention row for it. Pi auth readers reserve `missing` for an absent file or provider property; malformed stores and present non-object or structurally invalid entries are `invalid`. Handover is limited to credential problems - a transport, decoding, or server failure is about the request rather than the credential, so it is reported as-is instead of being retried on a second credential. When no source works the provider still reports its auth problem, and a source that only failed transiently outranks a definitive rejection so a rejected credential is never reported as a sign-out while a sibling's outage is unresolved. A present-but-unusable source is a failed credential rather than an absence: a set environment variable that is not a usable literal secret, or a Pi entry of the wrong shape, names a credential that exists, so it outranks an earlier plain absence in `state.error` and an `unavailable` diagnostic never names it. `preferCredentialFailure` in `src/providers/env-pi-credential.ts` owns that order for the env-plus-Pi adapters, and MiniMax and Z.AI apply the same rule in their own pipelines. New or migrated adapters route multi-credential selection through `src/providers/credential-selection.ts` instead of skipping a stored-expired credential. Codex, Kimi, Copilot, and Devin call it once per source so each provider's ownership-stability order stays authoritative. An `expired` resolution carries the stored token for the probe only; it is never logged or rendered. Pi entries are classified through `classifyPiAuthEntry` in `src/lib/pi-auth-store.ts`: only an absent file or provider property is `missing`, and a present non-object entry is `invalid`. Literal secrets for a new adapter go through `usableLiteralSecret` in `src/lib/secret.ts`. Claude's `env` source has distinct handover and failure-priority rules; see [Claude provider notes](#provider-notes).
  576. Adding a credential source:
  577. 1. Enumerate every source in an ownership-stability order declared by a named constant. Keep `absent`, `structurally_invalid`, `unsupported`, `read_error`, and `resolved` (stored-valid or stored-expired) distinct, and derive `credentialPresent` once from that resolution.
  578. 2. Separate local resolution from the bounded read-only liveness probe. Enroll stored-expired credentials instead of skipping them, never infer liveness from presence, and classify probe outcomes as `usable`, `live_no_quota`, `definitively_rejected`, or `transient`. Only a first-party 401/403 is an auth verdict.
  579. 3. Hand over only after definitive credential failure. An absent source is never degraded. A present-but-broken source superseded by a working sibling is degraded on fresh readings only. Inspect refresh-token presence only, and never read or exchange its value, except the Pi usability boolean described under [Safety guarantees](#safety-guarantees).
  580. 4. Add adapter regressions for primary healthy, stored-expired plus live sibling, structurally invalid present, absent source, all rejected, refreshable expired, and transient stops handover. Extend the cross-provider invariant table in `test/credential-contract.test.ts`. Env-plus-Pi adapters route through `src/providers/env-pi-credential.ts`.
  581. Claude credential failures without a usable access token preserve the precise `credentials_missing` or `credentials_invalid` error. A usage response with HTTP 401 reports `Claude sign-in required` only when it definitively establishes account authentication failure; the [Claude provider notes](#provider-notes) own the withheld-Keychain exception and cache effects. HTTP 403 is not sufficient authentication evidence because network policy and WAF denials use it too; it stays unavailable or stale rather than claiming sign-out.
  582. ### Quota windows
  583. | Field set | Fields |
  584. | --------- | ---------------------------------------------------------------------------------------------------------- |
  585. | Required | `id`, `label`, `kind` |
  586. | Optional | Percentages, `shareOf`, `startsAt`, reset fields, `windowSeconds`, credit-spend fields, and derived `pace` |
  587. Credit-spend fields include `spentUsd` and `limitUsd` for USD spend windows, and `limitCredits`, `usedCredits`, `remainingCredits`, and `creditUnit` for non-USD credit caps. The latter four appear only on the Codex `spend_control` window: `limitCredits` is the workspace-imposed cap in vendor credits, `usedCredits` is the amount consumed, `remainingCredits` is the amount left, and `creditUnit` is the vendor-supplied unit name (e.g. `credit`).
  588. Do not interpret a model window's percentage in isolation. `quotaSemantics.effectiveAvailability` reports the effective percentage for each understood scope, the complete `boundedBy` window set used to compute it, the currently limiting window IDs, an effective `runway` aggregate, and a per-scope [`selection`](#per-scope-selection-signal) signal. `all_models` applies to any model without a more specific scope; whether a matching `model:*` scope also includes account bounds is provider-specific. Grok uses the analogous `all_products` and `product:*` scopes.
  589. A model-specific `scope` names the model window or the shared model prefix when multiple period windows describe one Codex or MiniMax model.
  590. An inherited bound is only ever as good as the evidence that the vendor enforces it. When a scope's own windows all still report allowance while a window the scope merely inherits from a broader scope reports zero remaining, the two readings contradict each other, and quota-axi publishes that contradiction as `effectiveAvailability[].boundConflict` instead of resolving it. The scope's `status` stays `unknown` with no `effectivePercentRemaining`, and its `runway` and `selection` are `unknown` with both sides of the conflict named in `unmeasurableWindowIds`. This is a disclosure of uncertainty, not a claim that the scope is available - and it is deliberately not the opposite assertion either, because one live call proves the inherited bound was not enforced at that moment, not that it never binds. A zero on one of the scope's **own** windows is not a conflict: that is the scope's own meter reporting exhaustion, and it stands as `exhausted_now`, whether or not any bound reports a reset (see [Effective usable runway](#effective-usable-runway)).
  591. Codex is the provider this applies to today. The vendor reports a named model limit under `additional_rate_limits` / `rateLimitsByLimitId` - a separately metered budget alongside the base limit - and a base window at zero has been observed alongside that model's own windows visibly drawing down under successful calls. Claude, Grok, and Alibaba model scopes keep their established account bounds unchanged.
  592. `quotaSemantics.status` is `known` only when quota-axi understands the relationships needed for the reported scopes. A non-definitive availability entry omits `effectivePercentRemaining`. Unfamiliar vendor windows produce `partial` or `unknown` semantics and are named in `unresolvedWindowIds`; an empty provider report is `unknown` without inventing an unresolved window.
  593. Cursor's IDE windows (`included_usage`, `auto_usage`, `api_usage`, and optional `spend_limit`) all draw on the same plan billing cycle, so quota-axi treats them as jointly bounding and reports an `all_models` effective remaining equal to the lowest of them. That is the conservative reading: it never overstates headroom. Grok Bot weekly usage is a separate Cursor-account meter reported as its own `grok_bot` scope, so it never lowers IDE headroom and IDE windows never mask Grok Bot exhaustion. An unfamiliar Cursor window is not folded into either bound and does not create a bound of its own - it stays named in `unresolvedWindowIds` and turns the provider's semantics `partial` while the recognized-window bounds remain. GitHub Copilot's window relationships are still unknown, so it reports no effective remaining.
  594. Z.AI's `five_hour` and `weekly` usage windows jointly bound model usage and are reported as one `all_models` scope, while the `mcp_month` tool window is a separate resource reported as its own `tools` scope; a tool window near exhaustion therefore never lowers model headroom, and model windows never mask tool exhaustion. An unfamiliar or untrusted Z.AI window is not folded into either bound: it stays named in `unresolvedWindowIds`, turns the provider's semantics `partial`, and leaves both scopes non-definitive because it could add a bound to either.
  595. Kimi's weekly, five-hour, and monthly-total windows jointly bound model usage at `all_models` scope.
  596. The `/usages` payload gives `month_total` a reset time but no duration.
  597. Kimi documents the cycle itself: Kimi Code shares the Kimi membership's monthly total quota and is frozen at it "until the monthly quota resets" ([Kimi Code Membership Benefits](https://www.kimi.com/code/docs/en/kimi-code/membership.html)), and membership credits "refresh monthly according to your subscription cycle, not by calendar month", for monthly and annual memberships alike ([Kimi Help Center: Membership Credit Updates and Usage Rules](https://www.kimi.com/en/help/membership/membership-update-rules)).
  598. So `month_total` gets a `startsAt` one calendar month before its reported reset, with the day of month clamped into a shorter month (a 31 March reset starts on 28 or 29 February), which makes its pace, and with it the `all_models` runway and `spendPriority`, measurable.
  599. A `month_total` with no reported reset gets no start, so its pace stays `missing_cycle`; `month_code` is a share and gets no cycle either.
  600. The monthly code window is the code-typed share of that monthly total as the vendor serves it, not a cap of its own, so it is reported as a used share with no `percentRemaining` and bounds no scope: monthly headroom for code work is `month_total`'s.
  601. That window carries `shareOf: month_total` so default TOON can name it as an `attention[]` `share` row and `--tui` can print the used percent of the parent instead of a remaining bar or `?`. `shareOf` is the single share rule for interpretation, TOON, TUI, and `--json`: keep `percentUsed` because it is that window's only figure, never derive a remaining from a share, and never special-case a window id.
  602. `share` is an additive attention kind; `schemaVersion` is unchanged.
  603. An unfamiliar legacy limit, a declared map entry that carries no usable ratio, and an unparsed principal `usage` next to a valid map all stay named in `unresolvedWindowIds` - as `limit:<index>`, `usages:<key>`, or `usage` - and turn the provider's semantics `partial`.
  604. When one answer carries both the `usages` map and the principal `usage` with `limits[]`, a window that both shapes report takes the more-used figure, so `all_models` is bounded by the week that binds.
  605. An unrecognized `usages` key is not reported as a window.
  606. Alibaba's account `weekly` window is reported at `all_models` scope, while each `model:*` limit is kept only at its named model scope; a model limit never becomes an account-wide bound. OpenCode Go's rolling, weekly, and monthly windows are stacked plan caps ($12 per rolling 5 hours, $30 per week, $60 per month) that jointly bound Go-plan usage at `all_models` scope, so effective remaining is the minimum across them. A zeroed plan window blocks Go-plan requests, but the vendor's free-model fallback or an opted-in Zen balance may still serve past it, which the usage endpoint does not report. quota-axi reports no Zen balance, so that zeroed window still reads plan-exhausted and names the fallback only in prose. Only a payload-supplied 18,000-second rolling duration promotes the window to `five_hour`; a plan-declared duration stays `rolling`. Cursor, OpenCode Go, ElevenLabs, and Kimi renewal dates all step back through `calendarMonthsBefore` in `src/lib/time.ts`. Command Code's `five_hour` and `weekly` windows jointly pace **included monthly credits** and are reported as one `included_credits` scope only when both windows are present and trusted; extra pay-as-you-go credits can bypass those windows, so they are never an unconditional `all_models` bound. Devin's `daily` and `weekly` windows bound `included_quota` the same way: paid extra usage continues past them, the daily window reuses the `session` kind, and only an explicit `hideDailyQuota: true` omits the daily cap. A missing flag leaves the bound unresolved. `limited:false` is credit-only: leftover five-hour or weekly fields are omitted rather than treated as a bound. An unfamiliar or untrusted Command Code limit, including a non-empty organization spend-limit list whose schema is not independently established, stays named in `unresolvedWindowIds`, turns the provider's semantics `partial`, and withholds the `included_credits` scalar. MiniMax model-remains windows are kept at their named model scopes and never become an account-wide bound. MiMo has no quota windows or effective model scope until a provider-owned quota source exists. DeepSeek and OpenRouter expose balances or key caps as raw credit evidence; quota-axi does not infer model headroom or effective remaining from those amounts. ElevenLabs' single `characters` window is the subscription plan's **included character allowance** and is reported as an `included_characters` scope, never `all_models` and never a model scope: plans whose `can_extend_character_limit` is set bill usage past that allowance, so a zeroed window means the included allowance is spent rather than that requests are refused. Muse's `five_hour` and `weekly` subscription windows jointly bound every model at `all_models`, so effective remaining is the minimum across them. If either expected window is absent while the other remains - including a five-hour reset that has already passed, which is dropped rather than published live - that missing bound stays named in `unresolvedWindowIds` and the remaining window does not publish a definitive `all_models` percentage. A window of any other length, or an entry that carried no usable percentage, is likewise unresolved and turns the provider's semantics `partial` rather than being folded in. An omitted or null `subs_usage` on an active subscription is an established empty reading (plan, no windows), not an untrusted field. An inactive subscription reports no window. Higgsfield remaining credits are a generation-credit allowance at `included_credits` only when the first `account transactions` page shows a subscription-credits grant as its only positive-credit entry and the balance still reconciles with that grant plus the on-page entries newer than it (fractional credits included, within the vendor's 0.01-credit rounding precision); otherwise the raw `credits.remaining` balance is reported with no percentage. The vendor status payload has no reset, so no cycle is assumed: pace stays `unknown`, and runway reads `exhausted_now` at zero balance and `unknown` otherwise, naming `credits` in `unmeasurableWindowIds`. Job outcomes from `generate list` are published as counts only (`jobs.sampled` / `completed` / `failed` / `other`).
  607. Antigravity groups its Gemini windows (`gemini_5h`, `gemini_weekly`) and its Claude/GPT windows (`claude_gpt_5h`, `claude_gpt_weekly`) into two independent scopes, `gemini` and `claude_gpt`. Within each group the 5-hour and weekly windows jointly bound that group, so its effective remaining is the minimum across its named windows, and neither group's usage lowers the other's headroom. Gemini 4 Argon is its own quota on paid Pro plans, so its buckets are reported under their own `gemini_argon_*` ids (for example `gemini_argon_weekly`) and are not folded into the `gemini` bound. An unfamiliar Antigravity window - including a recognized group's unrecognized bucket such as `gemini_unknown` or an Argon bucket - is not folded into either bound: it stays named in `unresolvedWindowIds` and turns the provider's semantics `partial`, while a reading that exposes only model-config `model:*` windows resolves no group and stays `unknown`. Buckets identified as 5-hour or weekly by their vendor window, bucket ID, or display name receive fixed `windowSeconds` (18000 or 604800). With usable usage and vendor `resetsAt` evidence, these support cycle-average pace, `runway`, and `selection`; unknown-kind and model-config `model:*` windows receive no cycle length. A used window keeps a fixed reset from its first request; an untouched one reports a reset one full window ahead, which reads as zero elapsed time and zero usage. No history-based burn rate is reported; see [Pace signals](#pace-signals) for the calculation.
  608. For every stale provider report, raw windows remain available for diagnostics but effective availability is always `unknown` and omits `effectivePercentRemaining` and `limitingWindowIds`. Window pace is `unknown` with reason `stale`, and each effective pace summary, effective `runway`, and `selection` is also `unknown` with its unmeasurable bounds named. Routing agents must not treat a stale raw percentage as current headroom.
  609. ### Pace signals
  610. Each window may include a derived `pace` object that compares cumulative usage to elapsed cycle time using the response `generatedAt` clock:
  611. ```text
  612. timeRemainingPercent = 100 * (resetsAt - generatedAt) / cycleDuration
  613. reservePercentPoints = percentRemaining - timeRemainingPercent
  614. ```
  615. | `reservePercentPoints` | Meaning |
  616. | ---------------------- | ---------------------------------------------------------------------------- |
  617. | Negative | Usage is **ahead** of the reset clock (burning faster than linear); conserve |
  618. | Positive | Usage is **behind** the reset clock |
  619. | Within ±1.0 | `on_pace` deadband for API rounding noise |
  620. | Pace field | Meaning |
  621. | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
  622. | `status` | `ahead`, `on_pace`, `behind`, or `unknown` |
  623. | `reason` | Why pace is unknown (`stale`, `missing_usage`, `missing_cycle`, `invalid_cycle`, `future_cycle_start`, `expired_reset`, `unsupported_period`) |
  624. | `timeRemainingPercent` / `elapsedPercent` | Cycle progress from `generatedAt` |
  625. | `reservePercentPoints` | Signed residual capacity vs the linear clock |
  626. | `burnMultiple` | `percentUsed / elapsedPercent` when elapsed > 0 |
  627. | `projectedExhaustedAt` | Linear cycle-average exhaustion timestamp when defined |
  628. | `projectionConfidence` | `early` when elapsed < 10% of the cycle; otherwise `established` |
  629. | `cycleBasis` | `starts_at_resets_at` when both boundaries are trusted; otherwise `window_seconds` with `resetsAt` |
  630. | `cycleSeconds` | Trusted cycle duration used for the math |
  631. Pace is calculated only from trusted cycle evidence:
  632. - Prefer trusted `startsAt` + `resetsAt` pairs (Grok's provider-reported current period; Cursor's monthly billing cycle, whose start comes from the payload's cycle start or the previous renewal date).
  633. - Otherwise use provider-owned `windowSeconds` with `resetsAt` (Codex durations; Claude fixed 5h/7d; Kimi, Z.AI, and Antigravity fixed 5h/weekly).
  634. - Do not infer monthly, rolling, or unlabeled periods.
  635. Every projection quota-axi publishes is cycle-average. There is deliberately no `projectionBasis` field: its absence means `cycle_average`, and a future non-cycle-average basis would name itself.
  636. Default TOON keeps token cost low: `quota[]` puts `spendPriority` immediately after effective headroom and carries the runway verdict, its confidence, and the binding window's reset, while per-window rows and raw numeric reserve live in `--full`. Default `--json` keeps `pace.status`, `reason`, `reservePercentPoints`, and `burnMultiple`, and demotes the cycle-progress inputs those are derived from. Pace, runway, and `selection` are recomputed on every report from `generatedAt` and are not written to the quota cache.
  637. Each `effectiveAvailability` entry also carries a compact `pace` summary over **every** bounding window for that scope (not only the current lowest-remaining limiter): per-status window lists, including `aheadWindowIds` and `unknownWindowIds`, plus `worstReservePercentPoints` / `worstReserveWindowId` (most negative signed reserve among known-pace windows). Different windows keep their own reset horizons; quota-axi does not invent one synthetic reset for a scope. This is factual inspectable data, never a provider/model routing recommendation.
  638. `pace.worstReservePercentPoints` stays a single-window diagnostic and is deliberately not a scope-level comparative signal. The published per-scope comparative signal is [`selection`](#per-scope-selection-signal), which aggregates every bounding window instead of reporting one extreme.
  639. ### Effective usable runway
  640. `effectiveAvailability[].runway` is an optional, additive field derived from every authoritative `boundedBy` window using the report's single `generatedAt` clock. It is completion-risk evidence, not a score or recommendation.
  641. | `runway.status` | Meaning |
  642. | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  643. | `exhausted_now` | A bounding window reports zero remaining now. `usableRunwaySeconds` is `0`; `limitingWindowId` names that bound. Not reported when that zero is only an inherited bound the scope's own live windows contradict - see [`boundConflict`](#quota-windows). A vendor-reported zero stands even when no bound reports a `resetsAt`; the resetless rule below suppresses only reset-implying verdicts. |
  644. | `projected_exhaustion` | Every bound is measurable and one or more cycle-average projections exhaust before their own resets. The earliest one supplies `usableRunwaySeconds`, `projectedExhaustedAt`, `limitingWindowId`, and `projectionConfidence`. |
  645. | `through_reset` | Every measurable bound reaches its own current-cycle reset before projected exhaustion. There is deliberately no synthetic finite deadline or combined reset timestamp. |
  646. | `unknown` | A stale, missing, malformed, or otherwise unmeasurable authoritative bound prevents a sound aggregate conclusion, as does a disclosed [`boundConflict`](#quota-windows). `unmeasurableWindowIds` names the blockers. |
  647. In default TOON the finite-runway detail moves to `exhaustion[]`; `runway` and `projectionConfidence` stay as the `runway` and `confidence` columns of the scope's `quota[]` row, and `unmeasurableWindowIds` becomes an `attention[]` row naming the blocked signals.
  648. `usableRunwaySeconds` is nonnegative and is present only for finite results. `projectionConfidence` is `early` or `established`. Zero observed usage with a valid current cycle proves `through_reset` under that same cycle-average basis. Named model or product windows are additional bounds only for their applicable scopes, so they can become the effective limiting window without changing other scopes.
  649. A bounding window with no `resetsAt` at all has not been triggered yet (e.g. a Claude `five_hour` window before its first request this window) rather than being a data gap. When that untriggered window also reports zero usage (100% remaining, 0% used), it is treated as fully available rather than a data gap, so while any bounding window of the scope reports a reset it stays excluded from `unmeasurableWindowIds` and never forces `runway.status: unknown` by itself; the report's other bounding windows still determine the aggregate. When no bounding window reports a `resetsAt` at all, the scope has no current cycle to derive a reset-implying verdict from, so `runway.status` is `unknown` instead of `through_reset` or `projected_exhaustion`, every bound is named in `unmeasurableWindowIds`, and only `effectivePercentRemaining` still publishes. A bound reporting zero remaining still makes the scope `exhausted_now`, because that verdict needs no cycle. The same runway treatment applies to a fresh named-model window when its scope's enclosing account bounds independently establish runway and it explicitly reports 0% used and 100% remaining with a valid reset no more than its declared window duration plus five minutes ahead, making its inferred cycle start slightly later than the report snapshot (`pace.reason: future_cycle_start`): that unopened model window has no exhaustion projection yet. The five-minute ceiling bounds request latency and clock skew; a reset beyond it is implausible cycle evidence and remains unmeasurable. Its 100% can still contribute to `effectivePercentRemaining` as a headroom bound. quota-axi never synthesizes a `resetsAt` or starts the countdown client-side. A missing `resetsAt` paired with any other usage shape (unknown usage, or nonzero usage without an active clock) is a real data gap, not "not yet triggered," and still fails closed into `unmeasurableWindowIds` - alongside stale data, missing usage percent, an expired or malformed `resetsAt` that is actually present, and a missing projection when usage is nonzero and the cycle is known. Likewise, a future cycle remains unmeasurable unless it is a named-model window with independently measurable enclosing account bounds, both usage fields explicitly prove that it is wholly unused, its positive declared duration is available, and its reset falls within that bounded cycle-ahead interval.
  650. ### Per-scope selection signal
  651. `effectiveAvailability[].selection` is an optional, per-scope object published for every scope quota-axi reports, including `unknown` and stale ones. It is the primary published selection signal: one scalar per scope, comparable across scopes, providers, and accounts. Consumers that need to distinguish accounts can request the optional account identity with `--full`.
  652. In default TOON the scalar is the `spendPriority` column of the scope's `quota[]` row - there is no separate `selection[]` block, at any tier, because the column already carries it. An unmeasurable scalar renders the literal `unknown`, never `0`: `0` is exact utilization, a completely different claim.
  653. | Field | Meaning |
  654. | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  655. | `status` | `known` when at least one bounding window is measurable, every other bound is an untriggered zero-use window, and no [`boundConflict`](#quota-windows) is disclosed; otherwise `unknown` |
  656. | `spendPriority` | The clamped scope scalar. Present only when `status` is `known` |
  657. | `unmeasurableWindowIds` | The bounding windows that blocked the scalar. Present only when a named bound made the scope `unknown` |
  658. For each bounding window `w` of the scope:
  659. ```text
  660. S_w = percentRemaining_w - burnMultiple_w * timeRemainingPercent_w
  661. gap_w = S_w / timeRemainingPercent_w
  662. scopeMetric = SUM(gap_w * cycleSeconds_w) / SUM(cycleSeconds_w)
  663. ```
  664. `S_w` is the percentage points of that window's paid allowance projected to reach reset unused if the observed burn continues. Dividing by `timeRemainingPercent_w` makes windows on different reset clocks comparable, and weighting by `cycleSeconds_w` keeps a short session window from dominating a weekly or monthly one. The result is clamped to `[-100, +100]`.
  665. | `spendPriority` | Meaning |
  666. | --------------- | --------------------------------------------------------------------------------------------------------------------------- |
  667. | Positive | Paid allowance is on track to reach reset **unused**, so spending here reclaims allowance that would otherwise be forfeited |
  668. | `0` | Exact utilization: the scope is projected to finish its cycle with nothing left over and nothing overdrawn |
  669. | Negative | Overdrawn against the reset clock |
  670. A higher `spendPriority` therefore marks the scope where spending recovers the most paid allowance that would otherwise expire unused. At `burnMultiple` 1, `S_w` reduces exactly to that window's `reservePercentPoints`; the metric generalizes reserve to projected forfeiture at the observed burn pace.
  671. Any bounding window without usable pace makes the **whole scope** unmeasurable: `status` is `unknown`, no scalar is emitted, and `unmeasurableWindowIds` names the blockers. An unknown window is never assumed healthy and never treated as zero. A window whose remaining cycle time has effectively run out is unmeasurable rather than infinite. The one case where an absent `burnMultiple` is not a gap is a window with zero elapsed cycle time and zero usage: nothing can have been consumed yet, so its observed burn is `0` and the scope stays measurable.
  672. A bounding window with no `resetsAt` at all has not been triggered yet (e.g. a Z.AI `five_hour` window before its first request this window, whose vendor omits the reset while the window is idle) rather than being a data gap. Under the same rule as the runway aggregate, when that untriggered window also reports zero usage (100% remaining, 0% used) it is treated as fully available and excluded from the weighted mean instead of blocking the scalar, so the scope's other bounding windows still determine `spendPriority`. When every bounding window is untriggered there is no measurable cycle to weight, so the scope publishes no scalar and `spendPriority` renders the literal `unknown`. A missing `resetsAt` paired with any other usage shape (unknown usage, or nonzero usage without an active clock), and a present-but-unparseable `resetsAt`, remain real data gaps that fail closed into `unmeasurableWindowIds`.
  673. `selection` is derived per report from the same `generatedAt` clock as `pace` and `runway`, and is not cached. `summarizeEffectiveSelection` in `src/pace.ts` is its only implementation, and `SELECTION_SCALAR_KEY` in `src/types.ts` is the only spelling of the published field name. `worstReservePercentPoints` is a single-window diagnostic and is not this scalar.
  674. **This is data, not routing.** quota-axi still never routes, ranks a winner, orders providers preferentially, proxies, logs in, or changes provider quota state. `selection` is a derived comparative _data_ signal computed entirely from figures quota-axi already reports; any routing, ranking, or preference is the consumer's decision. It is also advisory only: it never overrides `runway`, which remains the hard completion-risk evidence a consumer checks against its task horizon.
  675. ### Quota enums
  676. | Name | Values |
  677. | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
  678. | Provider statuses | `fresh`, `stale`, `unavailable`, `auth_required`, `rate_limited`, or `error` |
  679. | Provider sources | `oauth`, `pi:openai-codex`, `pi:openai-codex-*` sibling keys, `cli-rpc`, `cli`, `api`, `web`, `cache`, or `unavailable` |
  680. | Current provider adapter sources | `oauth`, `pi:openai-codex`, `pi:openai-codex-*` sibling keys, `cli-rpc`, `cli`, `api`, `web`, `cache`, and `unavailable` |
  681. | Window kinds | `session`, `weekly`, `monthly`, `model`, `credits`, or `unknown` |
  682. | Window pace statuses | `ahead`, `on_pace`, `behind`, or `unknown` |
  683. | Effective pace statuses | `ahead`, `on_pace`, `behind`, `mixed`, or `unknown` |
  684. | Effective runway statuses | `exhausted_now`, `projected_exhaustion`, `through_reset`, or `unknown` |
  685. | Effective selection statuses | `known` or `unknown` |
  686. | Pace projection confidence | `early` or `established` |
  687. | Pace cycle basis | `starts_at_resets_at` or `window_seconds` |
  688. | Quota relationship statuses | `known`, `partial`, or `unknown` |
  689. | Source attempt statuses | `success`, `failed`, or `skipped` |
  690. Source attempts can include `credentialPresent` when a source is not genuinely absent, including when a read failure prevents a more precise classification. They can also carry an explicit `degraded` flag that overrides the derived classification in either direction: `false` when a non-success attempt is not a broken credential source, and `true` when a skipped source was itself unreadable without establishing that a credential is present. Otherwise fresh reports derive `state.degradedSources` from failed attempts and skipped attempts with `credentialPresent`.
  691. ### Provider windows
  692. | Provider | Windows and capabilities |
  693. | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  694. | Claude | Can report `five_hour`, `seven_day`, optional `seven_day_opus`, and optional `extra_usage` windows. Claude's OAuth usage `utilization` values, and scoped-limit `percent` values, are percent used; quota-axi stores them as `percentUsed` (while `extra_usage.utilization` remains its vendor-defined used-credit percentage). Trusted session/weekly/model windows emit fixed `windowSeconds` (18,000 or 604,800) for pace; `extra_usage` does not invent a monthly duration. |
  695. | Claude scoped `limits` | When the account's usage response includes a scoped `limits` list, quota-axi surfaces every active window it describes instead, including model-scoped ones (e.g. Fable) as a `model:<slug>` window with the same trusted weekly duration. |
  696. | Codex | Identifies exact 18,000-second and 604,800-second periods as `five_hour` and `weekly`, regardless of source slot; periods without a duration retain their positional identity. Additional model- or feature-scoped limits use `model:<id>:5h` / `model:<id>:7d`, and code-review limits use `code_review_five_hour` / `code_review_weekly`. Unfamiliar durations remain honest `<hours>h` windows instead of being classified as known periods. Duplicate derived IDs are preserved with `_2`, `_3`, and later suffixes. Workspace-imposed credit caps from `spend_control.individual_limit` appear as `spend_control` (`credits`, “workspace credit cap”), even without plan windows. Used and remaining percentages derive from the reported credit totals when the limit is positive and both totals are valid; otherwise the reported percentages are retained and missing values stay unknown. `spend_control.reached: true` marks this cap exhausted. When the cap is the sole quota evidence, it bounds `all_models`. When rate-limit windows also appear, the cap remains published but is excluded from effective availability: included usage and subsequent credit-funded usage are not modeled as a simultaneous minimum or a combined allowance. Its reported reset is retained without inventing a cycle duration. Optional credit balance data can also appear. |
  697. | Cursor | Can report `included_usage`, `auto_usage`, `api_usage`, and optional `spend_limit` windows from `GetCurrentPeriodUsage`, plus an optional `grok_bot` weekly window from the same dashboard service's `GetSandUsageStatus` RPC. Their effective-availability interpretation is documented in [Quota windows](#quota-windows). Monthly labels alone are not trusted cycle evidence, but the billing cycle is: the monthly windows take `startsAt` from a reported `billingCycleStart`, or - with only `billingCycleEnd` - from the previous renewal date one calendar month earlier (clamped to the last day of that month), so pace uses `starts_at_resets_at`. With neither field the cycle stays unresolved; no fixed 30-day duration is invented. The Grok Bot window uses the sand payload's own `currentPeriodStart` / `nextResetTimestampUtc` pair when present, and is omitted when that RPC is missing, non-finite, or a pooled enterprise allowance. |
  698. | GitHub Copilot | Can report quota snapshot windows such as `chat`, `completions`, and `premium_interactions`; when the first-party endpoint exposes entitlement but no numeric quota windows, quota-axi reports a fresh provider state with an empty `windows` list rather than inventing percentages. Pace stays `unknown` without trusted cycle boundaries. |
  699. | Grok | With a consumer-compatible Grok session or Pi `xai` OAuth bearer, can report the shared `credits`-identified current-period window (kind `weekly`/`monthly` from the decoded period type, otherwise `credits`; labeled `week`/`month` accordingly), optional product-scoped `product:<slug>` windows with the same kind, the current-period `startsAt` and reset, and optional prepaid credit balance from the consumer Usage-page operation. Official Grok Build OAuth and Pi OAuth can remain valid for their model catalogs while that separate operation rejects their audience; in that case quota-axi reports usable auth with no windows rather than inventing a SuperGrok percentage. A Pi `xai` API key likewise establishes model usability only. Top-level `credits.remaining` is prepaid/on-demand balance only; it is not subscription remaining and does not bound the period windows used for effective availability. Pace prefers the startsAt/resetsAt pair. |
  700. | Grok proto3 zero | For the exact consumer operation only, an omitted usage float is the official proto3 zero when a valid weekly or monthly current period proves the config is present; quota-axi reports `0` used and `100` remaining rather than deriving usage from money. |
  701. | Kimi | Reports every window the `/usages` payload actually supplies: the current `usages` map (`five_hour`, `weekly`, `month_total`, `month_code` from `limit_5h`/`limit_7d`/`limit_month_total`/`limit_month_code`), the legacy principal `weekly` object plus every valid self-described `limits[]` entry in wire order, or both. Kimi Code can send both shapes in one answer, and their figures for the same window can disagree: a live answer carried the principal `usage` at 92% used and `limit_7d` at 0% for the same week. When both shapes report a window, quota-axi reports the more-used figure, so the window never overstates headroom. A declared principal `usage` that this reader cannot parse next to a valid map is named `usage` in `state.untrustedWindowIds`, so the reading is partial and the principal is never dropped silently. Trusted 5h/weekly durations are 18,000s and 604,800s; `month_total` has the [monthly cycle](#quota-windows). Only a legacy limit whose normalized duration is exactly 18,000s is identified as `five_hour`; future limits remain `limit:<index>` unknown windows. The map's ratio is read from `used_ratio` only. Absent map entries stay absent, a declared map entry with no usable ratio is named `usages:<key>` in `state.untrustedWindowIds` rather than dropped, and an unrecognized map key is not a window. `month_code` stays a distinct window but carries only `percentUsed` plus `shareOf: month_total`, because it is a share of `month_total` rather than its own budget. An authenticated `/usages` body that declares no quota-bearing field at all (`usages` absent/null/`{}`, `usage` absent/null, `limits` absent/null/`[]`, no key besides the vendor's own `goods_version`/`boosterWallet`) is a Free-tier account's established-empty reading, not `schema_invalid`: it still consults the sibling Kimi Code CLI source, and if nothing yields windows, quota-axi reports fresh with no windows and a usable auth status instead of an error. A body that declares a quota field this reader cannot parse still fails as `schema_invalid`. |
  702. | Z.AI | Can report the Coding Plan `five_hour` and `weekly` usage windows (with trusted 18,000s and 604,800s durations) plus the `mcp_month` tool window, whose duration is not invented. Token and credit limits are both identified by the endpoint's own `unit`/`number` magic values (`3`/`5` and `6`/`1`) rather than array position; any other limit, or a repeat of an already reported one, degrades to an untrusted `limit:<index>` unknown window named in `state.untrustedWindowIds`. |
  703. | Antigravity (`agy`) | On macOS and Linux, can report `gemini_5h`, `gemini_weekly`, `claude_gpt_5h`, `claude_gpt_weekly`, and `gemini_argon_*` buckets from the installed CLI's structured `agy -p "/quota" --output-format json` response (a bounded read, not an agent session), falling back to an already-running Antigravity app or `agy` loopback quota summary when the CLI is unavailable. If only model config quota is exposed, quota-axi reports model-scoped `model:<slug>` windows instead of inventing grouped windows. See [Quota windows](#quota-windows) for grouped bounds and cycle evidence. |
  704. | Alibaba | Reads the local `bl` CLI's Alibaba Coding Plan Token Plan usage; reports the plan name and weekly remaining percentage and reset time from the CLI's JSON output, plus any named model limits as separate `model:<name>` windows. Repeated limits for the same model remain separate with suffixed IDs such as `model:<name>:2`. |
  705. | OpenCode Go | Using the credential sources documented in [Security Posture](#provider-credential-sources), reports the provider's rolling, weekly, and monthly usage windows as stacked plan caps that jointly bound Go-plan usage at `all_models` scope. It applies the plan's declared cycle lengths ($12 per rolling 5 hours, $30 per week, $60 per calendar month) when the payload carries no duration of its own: rolling and weekly windows gain trusted 18,000s and 604,800s durations, and the monthly window derives a start one calendar month before its reported reset (day-of-month clamped); a payload-supplied duration still wins, so pace, runway, and selection are measurable. A zeroed plan window blocks Go-plan requests, but the vendor's free-model fallback or an opted-in Zen balance may still serve past it. |
  706. | Command Code | Reads local Command Code API keys and reports the exact aggregate credit balance (`monthlyCredits` + `purchasedCredits` + `freeCredits`, unit `credits`) plus `five_hour` and `weekly` rolling windows from Command Code's undocumented first-party `GET /alpha/whoami?limits=1` and `GET /alpha/billing/credits` endpoints. Those windows use trusted 18,000s and 604,800s durations and jointly bound the `included_credits` scope, not `all_models`, only when both are present and trusted. `limited:false` omits leftover rolling fields so the report stays credit-only with empty `windows`. No monthly percentage or 30-day reset is invented. Pay-as-you-go/Enterprise-style responses with no rolling windows stay fresh and auth-usable with empty `windows`, and their balance is surfaced as a `credits` attention row rather than `no_quota`. The `/alpha` account endpoints are not a documented public API; unrecognized limits fail closed as untrusted/partial. |
  707. | MiniMax | Reports Token Plan `model_remains` windows, or a balance in `credits.remaining` with unit `usd` on the global `api.minimax.io` host and `cny` on the China `api.minimaxi.com` host. Model-window IDs are `model:<slug>:5h` or `model:<slug>:7d` for the trusted 18,000-second and 604,800-second durations, and `model:<slug>:window:<label>` for any other or undetermined duration; all share the `model:<slug>` scope. Absent numeric observations remain absent, and no account-wide bound is inferred. A `model_remains` row with no recognized window fields degrades to an untrusted `limit:<index>` unknown window named in `state.untrustedWindowIds`. |
  708. | MiMo | Reads the local `MIMO_API_KEY` first, then Pi's `auth.json` Xiaomi entries (`xiaomi` plus the `xiaomi-token-plan-sgp`/`cn`/`ams` clusters) as one `pi:<entry>` source each, so the report names the entry that answered and keeps a present-but-unusable entry visible as a credential rather than an absence. No first-party read-only quota endpoint is established, so a usable credential reports an empty fresh window set rather than fabricated model headroom. |
  709. | DeepSeek | Reports `credits.remaining` from the USD total with unit `usd`, or, when no representable USD total exists, from the CNY total with unit `credits`; quota-axi does not infer model headroom or effective remaining from those amounts. |
  710. | OpenRouter | Reads a local OpenRouter/Pi API key and the first-party key endpoint. A finite key cap is reported as a raw `key-limit` credit amount; unlimited keys are reported without an invented cap, and no model headroom is inferred. |
  711. | ElevenLabs | Reads the deliberately exported `ELEVENLABS_API_KEY` and reports one `characters` window from the subscription plan's included allowance (`character_count` / `character_limit`) via the documented first-party `GET /v1/user/subscription`. `resetsAt` comes from `next_character_count_reset_unix`; the cycle start is that reset stepped back by the vendor's declared `character_refresh_period`, and an unrecognized period leaves the cycle - and therefore pace, runway, and selection - unknown rather than assuming one. Only `monthly_period` maps onto the `monthly` window kind; the longer declared periods stay `unknown`. A zero or absent `character_limit` reports no window instead of a percentage, and so does a response whose reported reset has already passed: those counters describe a finished cycle, so the live reading fails closed the same way the stale-cache path does. The window bounds `included_characters`, never `all_models`. |
  712. | Devin | Reads `WINDSURF_API_KEY` when it is non-blank, otherwise `$XDG_DATA_HOME/devin/credentials.toml` (`~/.local/share/devin/credentials.toml`, or `%APPDATA%\devin\credentials.toml` on Windows). One read-only Connect-JSON `POST` to `https://server.codeium.com/exa.seat_management_pb.SeatManagementService/GetUserStatus` reports `weekly` and, when `planInfo.hideDailyQuota` is explicitly false, `daily` remaining percents with the vendor's reset timestamps. An absent flag leaves the daily cap unresolved, not omitted as on Max. The daily window reuses the existing `session` kind, so the published window-kind enum is unchanged: its id is `daily`, its label is `day`, and `windowSeconds` is 86,400. Weekly is `weekly` / `week` / 604,800. Both bound `included_quota`, because paid extra usage continues past a zeroed window. `overageBalanceMicros` is the extra-usage USD balance and is never turned into a percentage. A body whose `billingStrategy` is not `BILLING_STRATEGY_QUOTA` publishes no windows. An unrecognized `api_server_url` is not contacted. |
  713. | Devin proto3 zero | For `GetUserStatus` only, an omitted `dailyQuotaRemainingPercent` or `weeklyQuotaRemainingPercent` is 0 remaining when that window's reset timestamp is present, because proto3 JSON omits zero-valued scalars. When both the percent and reset are missing on a quota plan with an expected cap, that window is untrusted and the combined bound is withheld. |
  714. | Muse | Reads the Muse CLI's sign-in credential - `auth.json`'s `providers.meta.access_token` on Linux, the macOS Keychain item its `storage: "keychain"` records point to - then an exported `META_API_KEY`, and reports the subscription's `five_hour` (`subs_usage.window` when `window_duration_mins` is 300) and `weekly` (`subs_usage.weekly`) windows from `used_percent` and epoch-second `resets_at`, via `POST https://api.meta.ai/muse-code/key` - the request the Muse CLI makes at startup. Their effective-availability interpretation is documented in [Quota windows](#quota-windows). A window of any other length is named `window` with its own duration; an entry without a usable `used_percent` is named in `untrustedWindowIds`; an omitted or null `subs_usage` on an active subscription stays absent (plan still published) rather than untrusted or filled with 0%; an inactive subscription reports no window. Because that endpoint also issues an API key, requests are rate-bounded per credential; see [Muse provider notes](#provider-notes). |
  715. | Higgsfield | Reads the local `higgsfield` CLI: `account status --json` for plan and remaining credits, `account transactions --json` for a subscription-credits grant that supplies the allowance only when it is that page's sole positive credit and the balance reconciles with it plus the newer on-page entries, and `generate list --json` for a PHI-safe job-status rollup. Status has no limit or reset field, so a percentage is published only from a matching grant whose page also reconciles the balance, and pace stays unknown. Email on the status payload is ignored and never published. Job ids, prompts, and URLs are discarded; only `jobs.sampled` / `completed` / `failed` / `other` counts remain. The `credits` window bounds `included_credits`, never `all_models`. |
  716. ### Model catalog and `models`
  717. `quota-axi models [--intelligence high|medium|low] [--sort runway] [--provider ...] [--json|--full]` joins a reviewed catalog of native Claude, Codex, Grok, Kimi, MiniMax, and MiMo models to the provider's effective quota evidence. MiMo has catalog names for discovery, but no quota windows are established, so its model rows remain unevidenced. It queries catalog-backed providers by default and accepts only those providers in an explicit models scope. Cursor, Copilot, Z.AI, Alibaba, OpenCode Go, DeepSeek, OpenRouter, Antigravity, Command Code, Devin, Muse, and Higgsfield report quota but have no reviewed catalog entries yet, so they are not `models` providers. ElevenLabs meters speech characters rather than model usage, so it is not a `models` provider by construction.
  718. Catalog buckets are coarse editorial classifications relative to the current frontier, not scores. They are curated from public provider material and public leaderboards, including [Artificial Analysis](https://artificialanalysis.ai/) as an informing source, with a documented provenance string so a stale catalog is detectable rather than silently refreshed. quota-axi does not reproduce Artificial Analysis scores, has no runtime Artificial Analysis dependency, and never commits an Artificial Analysis key. `scripts/refresh-model-kb.ts` is a maintainer-only review aid: it may use a private `AA_API_KEY` to suggest changes, but it never writes the catalog.
  719. Every models response includes `catalog.version` and `catalog.provenance`; callers must treat catalog freshness and unmapped `unmatchedWindowIds` as explicit unknowns, never as missing evidence. A model row exposes the applicable effective quota scope and provider state. When no model-specific scope is known, the provider account scope remains the evidence rather than an invented model limit.
  720. Default model order is deterministic and non-preferential: provider, then `accountKey` in an account-expanded report, then model ID. `--sort runway` is an explicit, evidence-preserving comparator only: finite `usableRunwaySeconds` descend, then `through_reset`, then `exhausted_now`, with unknown evidence last. Equal evidence appears in `sort.tieGroups`; no hidden score or model, provider, harness, credential, or route recommendation is implied. The comparator registry is intentionally extensible for a future separately sourced `cost` comparator, which is not shipped in v1.
  721. ### `auth --json` shape
  722. | Object | Fields |
  723. | -------------------- | ------------------------------------------------------------------------------ |
  724. | Auth report | `generatedAt`, `schemaVersion` (`1`, or `2` when account-expanded), and `auth` |
  725. | Provider auth report | `provider`, optional `accountKey`, and `sources` |
  726. | Auth source entry | `source`, optional `path`, `status`, and optional `error` |
  727. Auth source entries can include `credentialPresent` when a source is not genuinely absent, including when a read failure prevents a more precise classification.
  728. | Name | Values |
  729. | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  730. | Auth source statuses | `available`, `missing`, `invalid`, `expired`, `skipped`, or `error` |
  731. | Auth source names | `env`, `oauth-file`, `keychain`, `auth-json`, `auth-env`, `apps-json`, `copilot-cli:keychain`, `gh:hosts.yml`, `state-vscdb`, `cli-keychain`, `cli-authfile`, `cli-rpc`, `pi:openai-codex`, `pi:openai-codex-*` sibling keys, `pi:kimi-coding`, `pi:xai`, `pi:zai`, `pi:commandcode`, `kimi-code-cli`, `pi:opencode-go`, `opencode:opencode.db`, `opencode:auth.json`, `minimax:config.json`, `pi:minimax`, `env:MINIMAX_API_KEY`, `env:MIMO_API_KEY`, `pi:xiaomi`, `pi:xiaomi-token-plan-sgp`, `pi:xiaomi-token-plan-cn`, `pi:xiaomi-token-plan-ams`, `pi:deepseek`, `env:DEEPSEEK_API_KEY`, `pi:openrouter`, `env:OPENROUTER_API_KEY`, `bl-cli`, `loopback`, `env:COMMAND_CODE_API_KEY`, `env:COMMANDCODE_API_KEY`, `commandcode-cli`, `omp:commandcode`, `env:ELEVENLABS_API_KEY`, `muse:auth.json`, `env:META_API_KEY`, `env:WINDSURF_API_KEY`, `file:credentials.toml`, and `higgsfield-cli` |
  732. ## Security Posture
  733. ### Provider credential sources
  734. | Provider | Credential sources read |
  735. | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  736. | Claude | `CLAUDE_CODE_OAUTH_TOKEN` when it is set to a usable literal token; `$CLAUDE_CONFIG_DIR/.credentials.json` or `~/.claude/.credentials.json` (on macOS, not read when a nonempty secure-storage selector is set); on macOS, the discovered Claude Code Keychain value for the selected profile, pinned to Claude Code's validated current-user account, with `--allow-keychain-prompt` or, after a service-and-account-scoped non-secret access marker exists, on plain calls |
  737. | Codex | `$CODEX_HOME/auth.json` or `~/.codex/auth.json`, then Pi's `$PI_CODING_AGENT_DIR/auth.json` `openai-codex` subscription OAuth entry and any sibling `openai-codex-*` entries in that same file (default `~/.pi/agent/auth.json`), before the read-only CLI fallback; `$QUOTA_AXI_CODEX_BINARY` can pin that fallback to an absolute executable path |
  738. | Cursor | Cursor editor: `$CURSOR_STATE_DB` when set or the platform Cursor state database path. Cursor CLI (`cursor-agent`), macOS: identity from `$CURSOR_CLI_CONFIG` or `~/.cursor/cli-config.json` plus the `cursor-access-token` / `cursor-user` Keychain value with `--allow-keychain-prompt` or an account-scoped marker; Linux: only `accessToken` from `$CURSOR_CLI_CONFIG` or `${XDG_CONFIG_HOME:-~/.config}/cursor/auth.json` |
  739. | GitHub Copilot | `$GITHUB_COPILOT_APPS_JSON` when set or the local Copilot apps auth file; on macOS and Windows, the Copilot CLI's secure-store item for the default `~/.copilot/config.json` selection (Keychain service `copilot-cli`, or Credential Manager target `<host>:<login>.copilot-cli`) with `--allow-keychain-prompt` or a selection-scoped marker; then the selected host's `oauth_token` from the GitHub CLI's `hosts.yml` (`$GH_CONFIG_DIR`, else `$XDG_CONFIG_HOME/gh`, else `%AppData%\GitHub CLI` on Windows, else `~/.config/gh`): `github.com` unless `QUOTA_AXI_COPILOT_HOST` names a `*.ghe.com` host |
  740. | Grok | Grok CLI session auth from `$GROK_AUTH_JSON`, inline `$GROK_AUTH`, `$GROK_AUTH_PATH`, or `$GROK_HOME/auth.json` / `~/.grok/auth.json`, plus Pi's independent `$PI_CODING_AGENT_DIR/auth.json` `xai` entry (default `~/.pi/agent/auth.json`) for OAuth or literal API-key model auth |
  741. | Kimi | Pi's `$PI_CODING_AGENT_DIR/auth.json` (default `~/.pi/agent/auth.json`) for a literal `kimi-coding` API key or OAuth access token first, then an official Kimi Code CLI access token from the slot `$KIMI_CODE_HOME/config.toml` names (default `$HOME/.kimi-code/`), falling back to `credentials/kimi-code.json` when it names none. Stored-expired tokens are probed; rejected refreshable expiry is soft, not sign-out |
  742. | Z.AI | Pi's `$PI_CODING_AGENT_DIR/auth.json` (default `~/.pi/agent/auth.json`) for a literal Coding Plan `api_key` entry under `zai`, then opencode's `auth.json` (`$XDG_DATA_HOME/opencode/auth.json` when set, `%LOCALAPPDATA%\opencode\auth.json` on Windows, otherwise `~/.local/share/opencode/auth.json`) for a literal key under `zai-coding-plan`, `zai`, `z-ai`, `z.ai`, `zhipu`, or `zhipuai` |
  743. | Antigravity | No credential files; prefers the installed CLI's bounded, noninteractive structured `/quota` read (`agy -p "/quota"`, a bounded read, not an agent session), falling back to discovering already-running Antigravity or `agy` processes and reading their 127.0.0.1 read-only loopback endpoints |
  744. | Alibaba | The local `bl` CLI (`bl usage token-plan --output json`); quota-axi never reads Alibaba credential files or exchanges refresh data |
  745. | OpenCode Go | OpenCode 2.x's SQLite database (`$XDG_DATA_HOME/opencode/opencode.db` when set, `%LOCALAPPDATA%\opencode\opencode.db` on Windows, otherwise `~/.local/share/opencode/opencode.db`; `OPENCODE_DB` overrides the file name, resolved against that directory) first, read-only, for the `credential` table's `opencode-go` row OpenCode itself would select (active, then newest) when its value is a literal `{type: "key"}` key; source `opencode:opencode.db`. OAuth and external values are `invalid`. Then, for 1.x installs and as the fallback, the same directory's `auth.json` for a literal `opencode-go` key with `opencode` fallback; source `opencode:auth.json`. A non-release OpenCode channel's `opencode-<channel>.db` is reached through `OPENCODE_DB`. When `QUOTA_AXI_OPENCODE_GO_PI_AUTH` is `1` or `true`, Pi's `$PI_CODING_AGENT_DIR/auth.json` (default `~/.pi/agent/auth.json`) literal `opencode-go` `api_key` entry is read before both. This is opt-in so an unscoped run does not read an unrelated Pi store. The database is read with `sqlite3 -readonly`; quota-axi never writes it or launches OpenCode. If `

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.