quota-axi

Report local agent-provider quota windows and model quota evidence.

You do not need quota-axi installed globally - invoke it with

npx -y quota-axi

quota-axi is data only: it never routes, recommends a provider, model, harness, credential, or route, proxies, intercepts, logs in, imports browser cookies, or mutates provider state. Default output has no ordering preference. The explicit

models --sort runway

comparator only orders quota evidence, preserves ties, and is never a recommendation. It reads local provider auth sources and calls first-party provider quota, usage, billing, or entitlement endpoints; it never launches the Claude, Grok, Pi, or Kimi CLIs, so it cannot spend the quota it measures.

When to use

Use quota-axi whenever you need local quota headroom before deciding whether it is safe to keep working on a provider, when the user asks about usage, rate limits, or remaining quota, or when comparing supported local provider headroom side by side.

Workflow

Run
```
npx -y quota-axi
```
for compact TOON output covering supported providers' quota windows.

Scope to one provider with

--provider claude

or to a subset with

--provider cursor,copilot,grok,kimi

Pass
```
--json
```
for the normalized machine-readable model instead of TOON. Read
```
quotaSemantics.effectiveAvailability
```
rather than treating a model window in isolation: account windows can bound every model, and
```
boundedBy
```
names every window included in the effective percentage. Read
```
effectiveAvailability[].runway
```
first for completion-risk evidence across every authoritative bound:
```
projected_exhaustion
```
supplies the earliest finite
```
usableRunwaySeconds
```
,
```
projectedExhaustedAt
```
, limiting window, and confidence;
```
through_reset
```
deliberately has no synthetic deadline;
```
exhausted_now
```
is zero runway; and
```
unknown
```
names unmeasurable bounds instead of inventing a conclusion. Read each window's
```
pace
```
(and the effective scope's pace summary) for diagnostics. Default TOON omits raw numeric reserve;
```
--json
```
and
```
--full
```
retain it. If relationship status is
```
partial
```
or
```
unknown
```
, do not infer one. Stale reports keep raw windows for diagnostics, but effective availability, pace, and runway are always unknown; never route from a stale raw percentage as though it were current headroom. Default output has no ordering preference. For a provider-native model evidence join, use
```
npx -y quota-axi models --intelligence high --json
```
. This catalog covers Claude, Codex, Grok, and Kimi only; its buckets are coarse editorial classifications, not scores. Its response includes catalog provenance and unmatched model windows.
```
--sort runway
```
is an explicit, documented quota-evidence comparator, not a provider, model, harness, credential, or route recommendation; inspect
```
sort.tieGroups
```
rather than treating equal evidence as a preference.
Pass
```
--full
```
to include account identity, per-source attempts, and raw reserve diagnostics.
Run
```
npx -y quota-axi auth
```
to check local auth-source availability without printing secret values.
On macOS, Claude Keychain value reads are pinned to the same validated current-user account Claude Code selects and are skipped by default until the user grants access once. If quota output reports
```
reason: keychain_access_required
```
, tell your user to run
```
quota-axi --allow-keychain-prompt
```
once and approve Keychain access ("Always Allow"). After that successful grant, plain
```
quota-axi
```
calls reuse the existing Keychain access marker, scoped to both profile and account, to refresh live Claude quota without requiring the flag. Legacy markers are not reused, so an upgrade may require this one-time grant again.
For Grok, read
```
state.authStatus
```
before any logout wording.
```
expired_refreshable
```
means a local session still looks signed in but short-lived access expired. Only when quota-axi also emits
```
reason: credentials_expired
```
/
```
remedyCommand: grok
```
should you tell your user to open the Grok CLI once; Pi-only expiry has no Grok remedy because Grok cannot refresh Pi-owned credentials. Do not treat soft expiry as full sign-out, and do not ask quota-axi to refresh credentials - it never launches Grok or Pi or writes auth files.
```
authStatus: usable
```
with empty windows means model auth is present (Grok CLI and/or Pi
```
xai
```
) while consumer credit windows are unknown - not logged out. Reserve true sign-in recovery for
```
authStatus: unusable
```
/
```
Grok sign-in required
```
.
For a managed Codex installation, set
```
QUOTA_AXI_CODEX_BINARY
```
to its absolute executable path. quota-axi uses that exact executable for auth inspection and the read-only app-server fallback, and fails closed if the override is invalid. Codex OAuth availability follows the access token, not id_token expiry alone.
For Kimi, quota-axi prefers a literal Pi-managed
```
kimi-coding
```
API key from
```
$PI_CODING_AGENT_DIR/auth.json
```
(default
```
~/.pi/agent/auth.json
```
). If it is unavailable, quota-axi may reuse a fresh official Kimi Code CLI access token from
```
$KIMI_CODE_HOME/credentials/kimi-code.json
```
(default
```
$HOME/.kimi-code/credentials/kimi-code.json
```
) without refreshing or writing credentials. Grok also reads that same Pi auth file for an independent
```
xai
```
OAuth or literal API-key entry and treats Grok as usable when either the Grok CLI session or Pi
```
xai
```
credential is valid.

Usage

usage: quota-axi [quota|auth|models] [flags]
commands[3]:
  (none)=quota, auth, models
output:
  Default TOON reports local quota evidence. models is a deterministic data join; --sort runway is explicit opt-in ordering. --tui renders a live human terminal report instead (q quits).
flags[11]:
  --provider <claude,codex,cursor,copilot,grok,kimi>, --json, --full, --tui, --refresh <30s-24h>, --once, --allow-keychain-prompt, --intelligence <high|medium|low>, --sort <runway>, --help, -v/--version
examples:
  quota-axi
  quota-axi --provider claude
  quota-axi --provider cursor,copilot,grok,kimi
  quota-axi --json
  quota-axi --full
  quota-axi --tui
  quota-axi --tui --refresh 1m
  quota-axi --tui --once
  quota-axi auth
  quota-axi models --intelligence high
  quota-axi models --sort runway

Tips

Output is TOON-encoded and token-efficient by default; pass
```
--json
```
only when you need the normalized schema.
Exit code 0 means at least one provider returned data (fresh or stale); exit code 1 means every provider failed; exit code 2 means a usage error.
Percentages are not comparable across providers - quota-axi never claims one provider's percentage equals another's.
Claude
```
--full
```
output exposes the authoritative OAuth profile
```
account.uuid
```
as
```
account.accountId
```
when Anthropic returns one; otherwise the account identity is explicitly marked unverified rather than inferred.
The quota cache at
```
~/.cache/quota-axi/quotas.json
```
only ever holds normalized non-secret snapshots. Fresh provider reports with no windows clear stale provider snapshots instead of caching empty quota. Claude local expiry metadata is advisory when an access token exists: the existing read-only usage request decides validity. Missing or invalid credentials without a usable token and HTTP 401/403 retire Claude cache; only transient failures may use bounded, reset-pruned stale data. The Claude Keychain access marker lives alongside it, is scoped by hashed profile and account hashes, and contains no credential values or raw account name.

quota-axi

NPX Install

Tags

SKILL.md Content

quota-axi

When to use

Workflow

Usage

Tips