tracker

Unified local usage tracker for Claude, Grok, Codex, Gemini, OpenAI, and Z.ai.

See every subscription's quota in one terminal command — no more logging into each account, checking usage, and logging out.

Why

If you juggle multiple AI accounts, checking "who still has quota?" is a ritual: log in, read a usage page, log out, repeat. tracker reuses the credentials the official CLIs already wrote (or a pasted API key) and answers the question in one command.

• tracker / tracker list — dashboard for all accounts at once
• Refresh-if-stale collection (cached when fresh, network when not)
• Honors usage-endpoint 429 backoff so you keep last-known bars
• Auto-detects API keys by shape (sk-ant-, xai-, AIza, sk-, GLM id.secret)
• Optional Discord webhook that posts and edits one live message
• tracker status names the account with the most quota left, so you don't have to eyeball five sets of bars
• Bars adapt to the terminal width instead of wrapping in a narrow pane

Read-only observability for the CLI sessions you already use. Token refresh for Claude/Grok/Codex writes rotated grants back to the provider CLI file so you are not forced into a re-login loop.

Screenshot

Claude  (2)
  work  you@example.com  [api · 12s ago]
  ├ 5h     ████░░░░░░░░░░░░░░░░  20%  resets in 21m
  ├ 7d     █████████████░░░░░░░  63%  resets in 3d0h
  └ Sonnet ██████████░░░░░░░░░░  48%  resets in 2d23h

  personal  me@example.com  [cached · 3m ago]
  ├ 5h ██████████████████░░  91%  resets in 44m
  └ 7d ██████████████████░░  88%  resets in 1d23h

Grok  (2)
  main  you@example.com  5  [api · 40s ago]
  ├ wk   █░░░░░░░░░░░░░░░░░░░   5%  resets in 6d20h
  ├ mo   ░░░░░░░░░░░░░░░░░░░░   2%  resets in 27d23h
  └ last  2026-08-01

  spare  alt@example.com  5  [cached · 2m ago]
  ├ wk   ████████████████████ 100%  resets in 1d16h
  ├ mo   ░░░░░░░░░░░░░░░░░░░░   0%  resets in 27d23h
  ├ qta  no quota  out of credits
  └ last  2026-07-30

Codex  (1)
  chatgpt  you@example.com  plus  [api · 25s ago]
  ├ 5h ███████░░░░░░░░░░░░░  34%  resets in 2h9m
  └ wk ██████████████░░░░░░  71%  resets in 3d23h

Gemini  (1)
  aistudio  [api · 1m ago]
  ├ key     valid
  ├ models  47
  └ e.g.    gemini-2.5-pro, gemini-2.5-flash

OpenAI  (1)
  platform  [api · 1m ago]
  └ key  blocked  insufficient_quota

Z.ai  (1)
  glm-coding  pro  [api · 30s ago]
  ├ 5h  ██░░░░░░░░░░░░░░░░░░  12%  resets in 2h58m
  ├ wk  █████░░░░░░░░░░░░░░░  24%  120K/500K  resets in 3d23h
  └ mcp ██████░░░░░░░░░░░░░░  28%  resets in 11d23h

tracker status compresses the same data to one line, and names the account with the most headroom left:

2 Claude · 2 Grok · 1 Codex · 1 Gemini · 1 OpenAI · 1 Z.ai · max 7d: 88% · 1 Grok blocked
  best: Grok main  95% free

Demo data is synthetic (scripts/generate_screenshots.py); no real account is ever rendered into the docs.

Install

uv tool install ai-quota-tracker    # recommended — isolated, on PATH
# or:
pipx install ai-quota-tracker
# or:
pip install ai-quota-tracker

tracker --help

The distribution is ai-quota-tracker; the command and import package are both tracker.

From source

git clone https://github.com/SakethKanchi/tracker.git
cd tracker
uv tool install .          # installs the `tracker` CLI
# or:  pip install .
tracker --help

Editable install for development:

uv sync
uv run tracker list
# or
pip install -e .

Requirements

• Python 3.11+
• For subscription windows: the official provider CLI already logged in (Claude Code, Grok, Codex)
• For API-key accounts: a valid key from Anthropic / xAI / Google AI Studio / OpenAI platform / Z.ai (GLM Coding Plan)

Quick start

# 1. Import from a logged-in CLI
claude                 # or: grok login --oauth  /  codex (ChatGPT sign-in)
tracker add claude     # or: tracker add grok  /  tracker add codex

# 2. Or paste an API key — provider is auto-detected
tracker add sk-ant-api03-...     # Claude
tracker add xai-...              # Grok
tracker add AIza...              # Gemini
tracker add sk-proj-...          # OpenAI platform
tracker add 0f8c….AbCd…          # Z.ai / Zhipu GLM Coding Plan

# Or let tracker find an already-wired GLM Coding Plan key
# ($Z_AI_API_KEY, or $ANTHROPIC_AUTH_TOKEN + a z.ai base URL, or
#  the env block of ~/.claude/settings.json):
tracker add zai
# same thing via flag form:
tracker --add "AIzaSy..."

# 3. See everything
tracker                # same as: tracker list
tracker list --refresh # force network pass
tracker status         # one-line aggregate

Commands

tracker -h and every tracker <command> -h end in a block of copy-pasteable examples, so the reference is in the tool as well as here.

Providers

Naming an account

remove, sync --label, and log take a selector: a label, an email, a provider name, provider:label, or an account id (in full, or a unique prefix of 8+ characters).

tracker remove codex                    # by provider
tracker remove you@example.com          # by label or email
tracker remove codex:you@example.com    # when one email has two accounts
tracker remove 9f3c1a20                 # by account id, shown in error output
tracker remove codex zai                # several at once
tracker remove you@example.com --all    # every account that selector names

Labels are not unique — one email commonly has both a Grok and a Codex account — so an ambiguous selector is reported with the exact alternatives and their short ids instead of silently picking one. With several selectors, all of them are resolved before anything is deleted: one bad selector aborts the whole command rather than half-removing your accounts.

Removing an account deletes its credential file, usage samples, token history, rate-limit events and fetch state. It is not reversible, and re-adding the account starts its history over.

Codex auth notes

Codex ChatGPT refresh tokens are single-use. After a successful refresh, tracker writes the rotated tokens back to both its credential store and ~/.codex/auth.json so the Codex CLI is not left with a dead grant (refresh_token_reused). Do not copy auth.json across machines while both sides keep refreshing.

How freshness works

Every account always gets a row so rate-limits never hide the rest of your fleet.

Discord (optional)

Post the same dashboard into a channel and auto-edit it every few minutes:

# ~/.config/tracker/webhook.json  (chmod 600)
{"url": "https://discord.com/api/webhooks/…", "interval_sec": 300}

tracker webhook --once   # smoke test
tracker webhook          # long-running poller

Full setup (including systemd user unit): docs/discord-webhook.md.

Data locations

Credentials are local only. See SECURITY.md.

Architecture

Provider collectors → SQLite → rich TUI (and optional Discord embed).

Details: docs/architecture.md
Original design notes: docs/superpowers/specs/2026-07-28-tracker-design.md

Prior art

• realiti4/claude-swap (cswap) — Claude multi-account switcher + usage UI; endpoint/backoff patterns informed this project
• ryoppippi/ccusage — local session token accounting across agent CLIs

tracker is provider-agnostic and intentionally does not auto-switch accounts (that can come later on top of the same store).

Troubleshooting

FAQ

Does this switch accounts for me? No. It is deliberately read-only observability. Auto-switching can be built on top of the same store later.

Does it send my data anywhere? No. Everything is local: credentials in ~/.config/tracker/, history in a local SQLite file. The only outbound calls are to the providers themselves, plus your own Discord webhook if you enable it.

Will this get my account banned? It calls the same usage endpoints the official CLIs call, with the same credentials, less often than an active session would. That said, it is unofficial — see the disclaimer.

Why is the PyPI name different? tracker and ai-usage-tracker are both taken on PyPI, so the distribution is ai-quota-tracker. The command and import package are still tracker.

Contributing

See CONTRIBUTING.md. Bug reports welcome — please redact emails, tokens, and webhook URLs.

# regenerate README screenshots after TUI changes
PYTHONPATH=src python scripts/generate_screenshots.py

License

MIT © 2026 sakethkanchi

Disclaimer

This project is unofficial and not affiliated with Anthropic, xAI, or Discord. Provider APIs and CLI credential formats can change; if something breaks, open an issue with a sanitized repro.