quota-axi

name	quota-axi
description	Report local Claude, Codex, Cursor, GitHub Copilot, Grok, and Kimi quota windows via the quota-axi CLI - remaining effective usable runway, percentages, reset times, cycle-average pace vs the reset clock, and provider status read from local auth sources, with no routing, provider mutation, or default ordering preference. Use before deciding whether it is safe to keep spending a provider's quota, when the user asks about usage, rate limits, pace, or remaining quota, or when comparing local provider headroom.
user-invocable	false
author	Kun Chen (kunchenguid)
metadata	{"hermes":{"tags":["quota","rate-limits","pace","claude","codex","cursor","copilot","grok","kimi","cli"],"category":"observability"}}

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

1. Run npx -y quota-axi for compact TOON output covering supported providers' quota windows.
2. Scope to one provider with --provider claude or to a subset with --provider cursor,copilot,grok,kimi.
3. 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.
4. Pass --full to include account identity, per-source attempts, and raw reserve diagnostics.
5. Run npx -y quota-axi auth to check local auth-source availability without printing secret values.
6. 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 once and approve Keychain access ("Always Allow"). After that successful grant, plain 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.

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.