A small CLI that reports claude / codex / cursor / copilot subscription usage in (near) real time, using only the credentials each tool already stores locally. It deliberately requires no extra permissions. It does not decrypt browser cookies and does not need Full Disk Access. It reads the macOS Keychain for the Claude Code item, and for the Cursor CLI item cursor-access-token only when cursor-agent is installed and state.vscdb has no access token.
| Provider | Credential source | API |
|---|---|---|
| codex | ~/.codex/auth.json (plaintext) |
chatgpt.com/backend-api/wham/usage |
| claude | macOS Keychain item Claude Code-credentials |
api.anthropic.com/api/oauth/usage |
| cursor | ~/Library/Application Support/Cursor/User/globalStorage/state.vscdb (read-only). If it has no access token and cursor-agent is installed, Keychain cursor-access-token |
cursor.com/api/usage-summary |
| copilot | ~/.config/github-copilot/apps.json (plaintext) |
api.github.com/copilot_internal/user |
Tokens are never refreshed or rewritten. On auth failure (401) the tool tells you to re-login with the provider's own CLI/IDE (codex login / claude / Cursor IDE or agent login / VS Code Copilot).
A provider you don't use (tool not installed, or installed but not logged in) is shown as a quiet dim – not configured line, never as a ⚠ warning, and does not affect the exit code — so the same command works unchanged across machines with different toolsets. Genuine failures (parse errors, 401, network) still surface as ⚠. The exit code is non-zero only when a genuine error occurred and nothing succeeded. With --json, a not-configured provider is {"provider": "...", "notConfigured": true}. The account (email/login) is shown only in --json; the formatted output omits it to avoid leaking it in a shared terminal or screenshot.
go build -o aiquota ./cmd/aiquota
./aiquota # all providers, formatted (ANSI color on a TTY)
./aiquota --json # machine-readable JSON
./aiquota --style emoji # plain text with 🟢🟡🔴 signals (for launchers that ignore ANSI)
./aiquota --proj # also print the end-of-window projection (proj NN%)
./aiquota codex cursor # selected providers only
./aiquota --claude-account <name> # pin the Claude Keychain accountExample output (color is shown here as the leading 🔵🟢🟡🔴; on a TTY it is ANSI bar color instead):
codex · plus
🔵 5h limit [██▏░░░░░░░░░░░░░░│░░░░░░] 9.0% · pace 69% resets 1h32m
🟢 Weekly limit [████▏│░░░░░░░░░░░░░░░░░░] 17.0% · pace 20% resets Jun 24 09:12
cursor · pro
🟢 Plan (total) [█████▍░│░░░░░░░░░░░░░░░░] 22.2% · $9.64 / $43.36 pace 30% resets Jun 27 14:01
🔵 Auto models [█░░░░░░│░░░░░░░░░░░░░░░░] 4.1% · pace 30% resets Jun 27 14:01
🔴 Named/API models [███████│███████████▉░░░░] 82.7% · pace 30% resets Jun 27 14:01
copilot · business
🟢 Premium [████████████████████▍░░│] 85.0% · 255 / 300 pace 97% resets 22h9m
⚪ Chat (unlimited)
⚪ Completions (unlimited)
Bars are 24 cells wide and the boundary cell is drawn as a partial block (▏▎▍▌▋▊▉), so the fill resolves to ~0.5 percentage points instead of the 6.25 a 16-cell whole-block bar quantized to.
These are flat-rate, use-it-or-lose-it quotas, so the color answers "are you on track to get your money's worth before it resets?" — not just "how full is the bar?". Each meter is colored by its usage projected to the reset (if you keep this pace, how much you'll have used when the window resets; --proj prints it as proj NN%):
- 🔵 blue — tracking to finish well under the cap. You're paying for headroom you won't touch: use more or lose it.
- 🟢 green — on track to use most of the window.
- 🟡 yellow — tracking to run out somewhat early.
- 🔴 red — tracking to run out well before reset, or so close to the cap that the headroom won't cover the window still ahead.
The │ inside each bar is the pace marker: how far the current reset window has elapsed (pace NN%), replacing the cell it lands on. The bigger the gap with the filled bar to its left, the more you're leaving on the table (the blue case); filled past the marker means you're burning faster than time. Early in a window (before ~20–25% elapsed) the projection is too noisy to trust, so a meter with no clock or a barely-started window falls back to plain "how full" coloring.
Install the binary first:
go install github.com/kohii/aiquota/cmd/aiquota@latestAny launcher that runs a command works (Raycast Script Command, Alfred,
SwiftBar/xbar). Launchers show plain monospace text and ignore ANSI color, so
use --style emoji: the bars, pace markers, and reset times stay, and a leading
🔵🟢🟡🔴 conveys the same pace-based level the ANSI color otherwise would (🔵 use
more or lose it · 🟢 on track · 🟡 running out a bit early · 🔴 nearly spent;
⚪ marks uncapped or unreported quotas). Because every line starts with a
same-width glyph, the bars stay aligned even though emoji are full-width.
#!/bin/bash
# @raycast.schemaVersion 1
# @raycast.title AI Usage
# @raycast.mode fullOutput
# @raycast.packageName aiquota
# @raycast.icon 📊
export PATH="$HOME/go/bin:$PATH"
exec aiquota --style emojiA native React/TS Raycast extension was prototyped but removed: its
Listview turned each meter into a large card and lost the CLI's at-a-glance density and pace marker.--style emojibrings the color back to the compact text view, keepinginternal/renderthe single source of truth.
See docs/design.md for the investigation, data sources, and design decisions.
go test ./...Each provider's normalization logic is a pure function (parse.go) tested against fixtures derived from real API response shapes.
Inspired by CodexBar (MIT) by Peter Steinberger. CodexBar was used as a reference for where each provider exposes usage (file paths, endpoints, cookie/token shapes); no source code was copied — this is an independent Go implementation intentionally pared down to the lowest-privilege local path for a single Mac.