ai-usage

A single-file, zero-dependency terminal dashboard for your AI plan usage — subscription rate-limit windows, local token activity, and estimated API-equivalent spend, side by side for every AI coding tool you use.

⚡  AI POWER GRID  // plan telemetry                                    ⣴ live

ESTIMATED API-EQUIVALENT  (subscription usage; not an invoice)
24h       $186.74   136.0M tokens
Tracked   $3,351.93   3.6B tokens
Input 11.3M · Cached 3.6B · Output 10.8M · Reasoning 547.0K

╭──────────────────────────────────────────────────────────────╮
│ ◆ Claude  plan Fable 5                              ● 2s ago │
│  5 hour            ━━━━━━━────────────────────────   37.0%   │
│    63.0% left · resets in 1h 9m · Thu 8:00 PM                │
│  7 day             ━━━━━━──────────────────────────   31.0%  │
│    69.0% left · resets in 3d 7h · Mon 2:00 AM                │
╰──────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────╮
│ ◈ Codex  plan Prolite                               ● 1s ago │
│  5 hour            ━━──────────────────────────────    8.0%  │
│    92.0% left · resets in 4h 28m · Thu 11:19 PM              │
│    → 70% in ~2.4h · 90% in ~3.1h                             │
╰──────────────────────────────────────────────────────────────╯

One Python file. No pip installs. No telemetry. Everything stays on your machine.

Supported providers

Providers are auto-detected — install the CLI or set the env var, and the panel appears.

Provider	Detected by	What you get
Claude Code	claude CLI	5-hour + 7-day plan windows, live via status-line collector; session context, real session cost
Codex (OpenAI)	codex CLI	5-hour + 7-day plan windows via local app-server; per-response token ledger from session transcripts
Grok CLI (xAI)	grok CLI	Weekly plan window + subscription tier from local logs; per-turn token ledger
Gemini CLI (Google)	~/.gemini	Per-response token ledger (input/cached/output/thoughts) from local chat sessions
Qwen Code	~/.qwen	Same as Gemini CLI (it's a fork with the same session format)
OpenRouter	OPENROUTER_API_KEY	Credits used %, remaining balance, key limits
Z.ai (GLM Coding Plan)	ZAI_API_KEY or ZHIPU_API_KEY	5-hour / weekly quota windows from the quota API (beta — endpoint is undocumented)
DeepSeek	DEEPSEEK_API_KEY	Account balance by currency
Kimi / Moonshot	MOONSHOT_API_KEY or KIMI_API_KEY	Available / voucher / cash balance

All rate-limit windows get trend sparklines, burn-rate, safe-pace, and projected-exhaustion estimates once the dashboard has collected some history.

Requirements

• Python 3.10+ (standard library only)
• macOS or Linux (uses fcntl/termios; on Windows use WSL)

Install

mkdir -p ~/.local/share/ai-usage ~/.local/bin
curl -fsSL https://raw.githubusercontent.com/ppinkhasov/ai-usage/main/ai_usage.py \
  -o ~/.local/share/ai-usage/ai_usage.py
printf '#!/usr/bin/env bash\nexec /usr/bin/env python3 "$HOME/.local/share/ai-usage/ai_usage.py" "$@"\n' \
  > ~/.local/bin/ai-usage
chmod +x ~/.local/bin/ai-usage

Make sure ~/.local/bin is on your PATH, then check what was detected:

ai-usage doctor

Claude Code setup (one command)

Claude's rate limits are only visible inside a running session, so ai-usage installs a tiny status-line collector: Claude Code invokes it after every response, and it caches only the numeric rate-limit fields.

ai-usage doctor --fix

This sets statusLine in ~/.claude/settings.json (backing up the old file) and doubles as a nice status line inside Claude Code itself. Send one message in any Claude session to seed the data.

API-key providers

Just export the key(s) — the provider appears on the next launch:

export OPENROUTER_API_KEY="..."   # OpenRouter credits
export ZAI_API_KEY="..."          # Z.ai GLM Coding Plan quotas
export DEEPSEEK_API_KEY="..."     # DeepSeek balance
export MOONSHOT_API_KEY="..."     # Kimi/Moonshot balance

Keys are read from the environment at poll time, sent only to that provider's official API over HTTPS, and are never written to disk.

Codex, Grok, Gemini CLI, and Qwen Code need no setup — their local session files are discovered automatically.

Usage

ai-usage                    # live dashboard (auto-detected providers)
ai-usage --once             # print one snapshot and exit
ai-usage --json             # one JSON snapshot (for scripts)
ai-usage --provider claude,codex,grok    # choose providers explicitly
ai-usage --details --graph  # start with details + token graphs on

Dashboard keys

Key	Action
q	quit
r	force refresh
space	pause / resume polling
d	toggle details (context, cost, sessions, trends)
g	toggle token graphs
t	cycle graph metric: rate → cumulative → context → output → cost ($/bucket) → spend (cumulative $)
1–4	graph range: 15m / 1h / 6h / 24h
c	compact one-line-per-provider mode
h	help

More commands

ai-usage statusline               # one-line summary for tmux/starship status bars
ai-usage export --range 24h      # token ledger as CSV (or --format jsonl)
ai-usage --check                  # exit 1 on warning, 2 on critical usage
ai-usage --check --watch --timeout 3600   # block until a threshold crossing
ai-usage reset                    # wipe local caches (keeps config)
ai-usage doctor                   # show detection status for every provider

--check is cron/CI-friendly; --warn and --critical (default 70/90%) set the thresholds, also via AI_USAGE_WARN / AI_USAGE_CRITICAL.

Config file

Persist defaults in ~/.config/ai-usage/config.json:

{
  "provider": "all",
  "details": true,
  "graph": true,
  "metric": "spend",
  "range": "6h",
  "warn": 70,
  "critical": 90,
  "interval": 15
}

How the $ estimate works

The ESTIMATED API-EQUIVALENT section prices your subscription usage at standard API list rates — subscriptions aren't billed per token, so this is a legibility tool, not an invoice. Accuracy varies by provider:

Provider	Cost basis	Accuracy
Claude	Real cost reported by Claude Code per session	exact
Codex	Full token splits from transcripts × OpenAI list prices	high
Gemini	Full token splits from chat files × Google list prices	high
Grok	Output estimated from streamed characters (~4 chars/token); prior context priced as cache-read	rough
Qwen	OAuth tier is free — tracked in tokens, unpriced	—

Price tables live at the top of ai_usage.py (OPENAI_PRICES, GROK_PRICES, GEMINI_PRICES) — easy to update when providers change list prices.

Privacy & data handling

• Local only. Caches live in ~/.cache/ai-usage/ and contain numeric counters (token counts, percentages, timestamps, model ids, session ids) — never prompt or response text.
• No telemetry. The only network calls are to providers you explicitly enabled by setting their API key, plus nothing at all for the local-CLI providers.
• No secrets cached. API keys are read from the environment per request. The Claude collector strips everything except rate-limit numbers, token counts, and cost.
• ai-usage reset deletes all cached data.

Uninstall

rm -f ~/.local/bin/ai-usage
rm -rf ~/.local/share/ai-usage ~/.cache/ai-usage ~/.config/ai-usage

If you ran doctor --fix, also remove the statusLine entry from ~/.claude/settings.json.

License

MIT