<div align="center">
<img src="docs/wordmark.svg" alt="QOTA" height="44">
**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.
<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
<img alt="Rust" src="https://img.shields.io/badge/rust-stable-orange?logo=rust">
<img alt="TUI: Ratatui" src="https://img.shields.io/badge/TUI-Ratatui-1abc9c">
<img alt="Platforms" src="https://img.shields.io/badge/macOS%20%7C%20Linux%20%7C%20Windows-lightgrey">
<img src="docs/dashboard.png" alt="QOTA dashboard: accounts rail, provider quota groups with usage bars, and a live status panel" width="100%">
</div>
---
## Why QOTA
Provider quota windows reset at different times. QOTA puts current headroom, reset times,
and account errors in one local terminal dashboard.
| 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.
```sh
cargo install qota
```
### Homebrew
```sh
brew install pr656d/tap/qota
```
### GitHub release binary
Download the archive for your platform from
[GitHub Releases](https://github.com/pr656d/qota/releases), extract it, then place `qota` on
your `PATH`. Verify the archive checksum published with that release before using it.
## First use
```sh
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.
```text
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)
```sh
cargo install qota
qota setup
qota
```
### Homebrew (macOS / Linux)
```sh
brew install pr656d/tap/qota
qota setup
qota
```
### GitHub Releases (Prebuilt Binaries)
Download prebuilt platform archive from [GitHub Releases](https://github.com/pr656d/qota/releases), extract `qota` binary into your `PATH`:
```sh
qota setup
qota
```
### Source build, available now
Source builds require stable Rust and Cargo. Check first:
```sh
cargo --version
```
If `cargo` is missing on macOS or Linux, install Rust with
[rustup](https://rust-lang.org/tools/install/), then load Cargo into this shell:
```sh
```
From this checkout:
```sh
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:
```sh
./target/release/qota
```
To install this source build into Cargo's bin directory:
```sh
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:
```sh
qota
qota setup
```
Automation:
```sh
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`](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:
```sh
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](https://github.com/router-for-me/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.
```text
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`.
```json
{
"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
```sh
cargo fmt --check
cargo test
cargo clippy -- -D warnings
cargo build --release
graphify update .
```
Built with [Ratatui](https://github.com/ratatui/ratatui) and
[crossterm](https://github.com/crossterm-rs/crossterm). Quota transport by
[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI).
## License
[MIT](LICENSE)