qota 0.2.0

Local AI quota dashboard powered by CLIProxyAPI
qota-0.2.0 is not a library.

Every AI coding subscription you pay for — one terminal dashboard.

Live quota windows for Claude, Codex, and Antigravity. Multiple accounts per provider. No provider CLI, no API key, no Node.js. Just OAuth and a local sidecar.

Why QOTA

Provider quota windows reset at different times. QOTA puts current headroom, reset times, and account errors in one local terminal dashboard.

Question QOTA answers it with
Which account has headroom now? Accounts rail, grouped by provider, live status per account
Am I close to a limit? HEALTHY and CRITICAL states, used and remaining bars
When does quota return? Local reset times, not raw UTC timestamps
Did an account fail? ATTENTION panel while healthy accounts remain visible
Can automation use this? qota list --json and qota poll versioned reports

Use QOTA before a long session, while managing several accounts, or as a quota input for an orchestrator. qota poll --interval 60 --background keeps ~/.podium/usage.json current.

Install

Choose one supported installation method.

Cargo

Requires stable Rust and Cargo.

cargo install qota

Homebrew

brew install pr656d/tap/qota

GitHub release binary

Download the archive for your platform from GitHub Releases, extract it, then place qota on your PATH. Verify the archive checksum published with that release before using it.

First use

qota setup
qota

qota setup opens a provider picker. Choose Claude, Codex, Antigravity, or any combination, then complete OAuth in the browser. QOTA downloads and verifies its local CLIProxyAPI sidecar during setup.

You need an interactive terminal, browser access for OAuth, internet access for provider calls, and at least one supported provider account. You do not need Node.js, a provider CLI, or an API key.

Dashboard

Run qota with no arguments.

  • Accounts rail: provider-grouped accounts with live, partial, or error status.
  • Quota groups: provider-reported windows, usage bars, remaining percentage, local reset time.
  • Status: provider account counts, ATTENTION items, last refresh time.
r          Refresh live quotas
n  /  +    Add or re-authenticate an account
Tab        Cycle panel focus
↑ ↓        Move selection
PgUp/PgDn  Scroll
?          Help overlay
q          Quit

Mouse support includes account and provider selection, footer actions, and compact-layout scrolling.

Install

Cargo (crates.io)

cargo install qota
qota setup
qota

Homebrew (macOS / Linux)

brew install pr656d/tap/qota
qota setup
qota

GitHub Releases (Prebuilt Binaries)

Download prebuilt platform archive from GitHub Releases, extract qota binary into your PATH:

qota setup
qota

Source build, available now

Source builds require stable Rust and Cargo. Check first:

cargo --version

If cargo is missing on macOS or Linux, install Rust with rustup, then load Cargo into this shell:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

From this checkout:

cargo build --release
./target/release/qota setup

setup opens a full-screen provider picker. Select Claude, Codex, Antigravity, or any combination, then press Enter. Only then does qota start provider OAuth in the browser.

After OAuth succeeds:

./target/release/qota

To install this source build into Cargo's bin directory:

cargo install --path . --locked
qota setup
qota

Cargo installs the binary to its configured bin directory, commonly ~/.cargo/bin. Add that directory to PATH if qota is not found.

What you need

  • a qota binary (release asset, or a source build as above);
  • an interactive terminal for the dashboard and setup;
  • internet access plus a browser for provider OAuth and the first-run sidecar download;
  • a Claude, Codex, and/or Antigravity account.

You do not need Node.js, a provider CLI, an API key, or (with a release binary) Rust and Cargo. qota downloads and verifies its local sidecar during setup.

Commands

Interactive:

qota
qota setup

Automation:

qota list
qota list --json
qota list --provider claude
qota list --provider codex
qota list --provider antigravity
qota poll --interval 60
qota poll --once --json
qota poll --interval 60 --background

list --json writes one versioned report to stdout. poll atomically writes the same report to ~/.podium/usage.json.

Agent Skill

To enable AI agents to check live provider quota headroom and subscription status, use the reusable QOTA skill:

  • Skill Specification: skills/qota/SKILL.md
  • Registration: Copy or symlink skills/qota/ into your agent skills directory (e.g. ~/.claude/skills/qota, ~/.gemini/config/skills/qota, ~/.codex/skills/qota, or .agents/skills/qota).

For scripts, select OAuth providers without opening the picker:

qota setup --providers claude
qota setup --providers codex
qota setup --providers antigravity
qota setup --providers claude,codex,antigravity

Set QOTA_CPA_BIN to an existing CLIProxyAPI executable to skip its download.

How it works

QOTA does not shell out to provider CLIs or request API keys. It uses a local CLIProxyAPI sidecar, which holds OAuth credentials and exposes each provider's usage endpoint. QOTA normalizes those responses into one report shape and renders them locally.

provider OAuth  ─▶  CLIProxyAPI (local sidecar)  ─▶  QOTA  ─▶  TUI + usage.json

During setup QOTA downloads CLIProxyAPI, shows transfer progress, verifies its published SHA-256 checksum, then extracts it. Rerunning setup preserves the local management key and supports account add and re-authentication flows.

OAuth pages belong to providers. QOTA confirms provider selection before opening a browser, keeps the TUI active during OAuth, shows safe provider status, and masks typed sidecar replies.

Providers

Claude

Subscription usage for the selected local OAuth account: rolling 5-hour and 7-day windows, plus model-specific weekly windows when supplied.

Codex

ChatGPT WHAM usage for the selected local OAuth account. Every returned rolling window is rendered, including 5-hour and 7-day windows when supplied.

Antigravity

Antigravity quota summary: provider-defined shared pools for Gemini, Claude, and GPT models. Disabled buckets are omitted. QOTA renders the group and window Antigravity returns; remaining percentage and reset time come from that summary.

If an Antigravity value differs from its /usage panel, confirm both use the same account and Code Assist project.

JSON report

Every account fails independently. Invalid credentials, network failures, and malformed provider responses appear in errors; healthy accounts remain in accounts.

{
  "version": 1,
  "generatedAt": "2026-07-23T12:00:00.000Z",
  "accounts": [
    {
      "provider": "antigravity",
      "accountId": "account-1",
      "accountLabel": "personal@example.com",
      "fetchedAt": "2026-07-23T12:00:00.000Z",
      "windows": [
        {
          "key": "Gemini Models:gemini-weekly",
          "label": "Weekly Limit",
          "group": "Gemini Models",
          "groupDescription": "Models within this group: Gemini Flash, Gemini Pro",
          "percentUsed": 1.92,
          "remainingPercent": 98.08,
          "resetsAt": "2026-07-23T18:00:00.000Z"
        }
      ]
    }
  ],
  "errors": []
}

Privacy and local data

QOTA stores its local sidecar configuration and OAuth files under ~/.qota/ with private permissions. It never prints provider tokens, management keys, credential files, or raw provider responses. Nothing leaves the machine except provider calls made through the sidecar.

Development

cargo fmt --check
cargo test
cargo clippy -- -D warnings
cargo build --release
graphify update .

Built with Ratatui and crossterm. Quota transport by CLIProxyAPI.

License

MIT