Check quota/usage for AI coding CLI tools: Claude Code, OpenAI Codex, OpenCode Zen, Google Gemini CLI, Google Antigravity, Z.AI, OpenRouter, Kimi K2 (Moonshot AI), Synthetic.new, and GitHub Copilot. It also supports checking keys used by Aider and Continue.
- Auto-discovers credentials from standard locations
- Zero-config Claude quota — reads Claude Code's own local usage cache (
~/.claude.json), no login required; also discovers Claude Desktop OAuth on Windows - Auto-refreshes expired tokens (Gemini OAuth, Antigravity OAuth)
- Native Codex quota discovery via the installed app-server (read-only, with WHAM fallback)
- Zero-config OpenCode Zen discovery across OpenCode, Pi, and OMP
- Multiple output formats: detailed, JSON, compact one-liner
- Caching support for fast statusline integration
- Cross-platform: macOS and Linux support
# Run directly without installing
npx cclimits
# Or install globally
npm install -g cclimits
cclimitsRequires: Python 3.9+ installed on your system.
# Clone and symlink
git clone https://github.com/cruzanstx/cclimits.git
ln -s $(pwd)/cclimits/lib/cclimits.py ~/.local/bin/cclimits
# Or just download
curl -o ~/.local/bin/cclimits https://raw.githubusercontent.com/cruzanstx/cclimits/main/lib/cclimits.py
chmod +x ~/.local/bin/cclimitscclimits # Check all tools (detailed)
cclimits --claude # Claude only
cclimits --codex # Codex only
cclimits --opencode-zen # OpenCode Zen only
cclimits --opencode-zen --opencode-zen-browser # Include opt-in browser billing
cclimits --gemini # Gemini only
cclimits --zai # Z.AI only
cclimits --openrouter # OpenRouter only
cclimits --kimi # Kimi only
cclimits --antigravity # Google Antigravity only
cclimits --synthetic # Synthetic.new only
cclimits --copilot # GitHub Copilot only
cclimits --json # JSON output
cclimits --oneline # Compact one-liner (5h window)
cclimits --oneline 7d # Compact one-liner (7d window)
cclimits --oneline both # Compact one-liner (5h/7d combined)
cclimits --oneline --noemoji # Color-coded text instead of emojis
cclimits --oneline --resets # Append reset countdowns (alias: --timeremaining)
# Caching (for statusline integration)
cclimits --oneline --cached # Use cache if fresh (<60s)
cclimits --oneline --cache-ttl 30 # Custom TTL in seconds
cclimits --no-stale-fallback # Don't serve stale cache on API errors
cclimits --no-cache-write # Read-only observer mode (never writes the cache)# Single window (5h or 7d); Copilot shows its monthly premium-request quota as (mo); Antigravity reports per-family quota groups
Claude: 4.0% (5h) ✅ | Codex: 0% (5h) ✅ | Z.AI: 1% (5h) ✅ | Gemini: ( 3-Flash 7% ✅ | Flash 1% ✅ | Pro 10% ✅ ) | OpenRouter: $47.91 ✅ | Kimi: $49.59 ✅ | Antigravity Gemini: 12.2% (5h) ✅ | Antigravity Claude/GPT: 0% (5h) ✅ | Copilot: 20% (mo) ✅
# Both windows (--oneline both) - shows 5h/7d combined (Z.AI: 5h-tokens%/monthly-MCP-tools%)
Claude: 4.0%/10.0% ✅ | Codex: 0%/2% ✅ | Z.AI: 1%/16% ✅ | OpenRouter: $47.91 ✅
# During Z.AI peak hours (Mon-Fri 06:00-10:00 UTC; weekends are off-peak) a ⚡3x quota-rate marker appears
Z.AI: 1% (5h) ✅ ⚡3x
# No emoji mode (--noemoji) - colorizes percentages directly (green/yellow/red)
Claude: 4.0% (5h) | Codex: 0% (5h) | Z.AI: 1% (5h) | OpenRouter: $47.91 | Antigravity Gemini: 12.2% (5h) | Antigravity Claude/GPT: 0% (5h)
# With reset countdowns (--resets / --timeremaining) - ↻5h-reset/7d-reset
Claude: 4.0%/10.0% ✅ ↻2h15m/3d17h | Codex: 0%/2% ✅ ↻1h05m/6d23h | Z.AI: 1% (5h) ✅ ↻3h02m | Antigravity Gemini: 12.2%/2.2% ✅ ↻1h42m/4h52m | Antigravity Claude/GPT: 0%/0.3% ✅ ↻4h59m/6d17h
# --resets in both mode also shows Z.AI's monthly MCP-tools reset as the second countdown
Z.AI: 1%/16% ✅ ↻3h28m/5d10hStatus icons: ✅ ok · --cached) are suffixed with their age, e.g. (cached 42s).
Exception: Gemini with an expired token or no credentials is hidden from check-all output entirely — Gemini CLI is retired, so the token generally can't be refreshed (nor credentials recreated) and the ⏰/🔑 row would be permanent noise. --gemini and --json still show the real state.
🔍 AI CLI Usage Checker
2025-12-31 21:30:00
==================================================
Claude Code
==================================================
🔑 Auth: Bearer token
✅ Connected
5-Hour Window:
Used: 15.2%
Remaining: 84.8%
Resets in: 3h 24m
7-Day Window:
Used: 42.0%
Remaining: 58.0%
Resets in: 4d 12h
==================================================
OpenAI Codex
==================================================
🔑 Auth: OAuth (ChatGPT)
✅ Connected
📊 Plan: pro
5h Window:
Used: 8%
Remaining: 92%
Resets in: 2h 15m
==================================================
Gemini CLI
==================================================
🔑 Auth: OAuth (Google Account)
✅ Connected
📊 Tier: standard
Quota by Tier:
3-Flash: 7.0% used, 93.0% remaining
Flash: 1.0% used, 99.0% remaining
Pro: 10.0% used, 90.0% remaining
==================================================
Z.AI (5h shared - GLM-4.x)
==================================================
✅ Connected
📊 Plan: max
Token Quota:
Used: 1%
Remaining: 99%
Resets in: 4h 30m
Quota Rate: 1x off-peak — peak in 1h 30m
MCP Tools (monthly):
Used: 650 / 4,000
Remaining: 3,350
Resets in: 6d 1h
search-prime: 625
web-reader: 13
zread: 12
==================================================
OpenRouter
==================================================
✅ Connected
Balance: $47.91
Total Used: $2.09
==================================================
Kimi K2 (Moonshot AI)
==================================================
✅ Connected
Balance (USD):
Total: $49.5889
Cash: $3.0000
Voucher: $46.5889
==================================================
Google Antigravity
==================================================
✅ Connected
📦 Project: my-cloud-code-project
📊 Tier: free
Quota Groups (Gemini and Claude/GPT models draw from separate pools):
Antigravity Gemini
5-Hour Window:
Used: 12.2%
Remaining: 87.8%
Resets in: 1h 42m
7-Day Window:
Used: 2.2%
Remaining: 97.8%
Resets in: 4h 52m
Antigravity Claude/GPT
5-Hour Window:
Used: 0.0%
Remaining: 100.0%
Resets in: 4h 59m
7-Day Window:
Used: 0.3%
Remaining: 99.7%
Resets in: 6d 17h
Model Quotas (per-model detail):
Models: 8
Tightest: 65% remaining
Average: 83% remaining
Model Remaining Reset
-------------------------------- ---------- ----------------
claude-opus-4-5-thinking 65% 2026-05-30T18:00:00Z
claude-sonnet-4-6 71% 2026-05-30T18:00:00Z
gemini-3-flash 88% 2026-05-30T18:00:00Z
==================================================
Synthetic.new
==================================================
✅ Connected
Subscription:
Used: 0 / 1,500 (0%)
Remaining: 1,500
Renews in: 4h 59m
5-Hour Rolling:
Used: 0 / 1,500 (0%)
Remaining: 1,500
Next tick: 0h 1m
Weekly Credits:
Remaining: $72.00 / $72.00 (100%)
Next regen: 2h 53m (+$1.44)
==================================================
GitHub Copilot
==================================================
🔑 Auth: ~/.config/github-copilot/apps.json
👤 Account: octocat
✅ Connected
📊 Plan: individual
Premium Requests (monthly):
Used: 60 / 300 (20%)
Remaining: 240
Resets in: 26d 2h (2026-09-01)
(chat, completions: unlimited)
| Icon | Meaning |
|---|---|
| ✅ | Under 70% - plenty of capacity |
| 70-90% - moderate usage | |
| 🔴 | 90-100% - near limit |
| ❌ | 100% or unavailable |
Credentials are auto-discovered from these locations:
| Tool | Location |
|---|---|
| Claude | ~/.claude/.credentials.json (Linux), macOS Keychain, or Claude Desktop OAuth (Windows, read-only). Zero-config fallback: ~/.claude.json cached usage (fresh snapshots only, no auth needed) |
| Codex | Installed codex app-server --stdio (preferred, read-only); ~/.codex/auth.json is used only by the legacy fallback |
| OpenCode Zen | OpenCode auth.json, Pi auth.json, OMP agent.db / .env, or $OPENCODE_API_KEY (read-only) |
| Gemini | ~/.gemini/oauth_creds.json (auto-refreshes) |
| Z.AI | $ZAI_KEY or $ZAI_API_KEY environment variable |
| OpenRouter | $OPENROUTER_API_KEY environment variable |
| Kimi | $MOONSHOT_API_KEY environment variable |
| Antigravity | ~/.gemini/antigravity-cli/antigravity-oauth-token (auto-refreshes); fallback $ANTIGRAVITY_REFRESH_TOKEN / $ANTIGRAVITY_ACCESS_TOKEN |
| Synthetic.new | $SYNTHETIC_API_KEY environment variable |
| Copilot | ~/.config/github-copilot/apps.json (or hosts.json), gh CLI ~/.config/gh/hosts.yml, or $GITHUB_TOKEN / $GH_TOKEN |
If credentials are missing, run the corresponding CLI tool to authenticate:
claude # Login to Claude Code
codex login # Login to OpenAI Codex
gemini # Login to Gemini CLI
agy -p hello # Login to Google Antigravity (prompts for OAuth)
export ZAI_KEY=your-key # Add to ~/.zshrc or ~/.bashrc
export OPENROUTER_API_KEY=your-key # Add to ~/.zshrc or ~/.bashrc
export MOONSHOT_API_KEY=your-key # Add to ~/.zshrc or ~/.bashrc
export SYNTHETIC_API_KEY=your-key # Add to ~/.zshrc or ~/.bashrcOpenCode Zen validation uses only the usage endpoint and does not perform
inference. Its API-key balance is not exposed by that endpoint. On Linux,
cclimits can optionally reuse an already authenticated opencode.ai browser
session read-only for billing with --opencode-zen-browser; it never starts
login or changes browser profiles. This opt-in browser discovery is available
only on Linux and is disabled by default.
The agy CLI writes its OAuth tokens to ~/.gemini/antigravity-cli/antigravity-oauth-token; cclimits reads that file and auto-refreshes the access token via Google's OAuth endpoint. As a fallback (e.g. shared CI machines without the agy install), set ANTIGRAVITY_REFRESH_TOKEN (or ANTIGRAVITY_ACCESS_TOKEN) in your environment.
For Gemini token auto-refresh to work, cclimits needs OAuth client credentials. It will automatically extract these from your Gemini CLI installation. If that fails, set environment variables:
# Extract from Gemini CLI (run once to get values)
grep -E "CLIENT_(ID|SECRET)" ~/.npm/_npx/*/node_modules/@google/gemini-cli-core/dist/src/code_assist/oauth2.js
# Then add to ~/.zshrc or ~/.bashrc
export GEMINI_OAUTH_CLIENT_ID="..."
export GEMINI_OAUTH_CLIENT_SECRET="..."cclimits can monitor usage for "Bring Your Own Key" (BYOK) tools by checking the underlying provider directly:
- Aider / Continue: If you use these with an API key (OpenAI, Anthropic, OpenRouter, Gemini), simply set the corresponding environment variable (e.g.,
OPENROUTER_API_KEY) and runcclimits --openrouter(or the relevant flag) to check your balance/quota.
Note on Integrated Providers:
- GitHub Copilot: Supported via the undocumented
copilot_internal/userendpoint that the Copilot editor plugins themselves use (there is still no supported public API). Any GitHub token for an account with a Copilot subscription works — editor sign-in files, gh CLI, or a plainGITHUB_TOKEN. A token whose account has no Copilot subscription is hidden from check-all output (visible with--copilotor--json). The check consumes no premium requests. - Codex: Prefers the installed
codex app-server --stdioaccount/rateLimits/readRPC and falls back to the legacy WHAM endpoint only when native quota is unavailable. Use--no-cache-writefor a pure observer invocation. - OpenCode Zen: Existing keys are discovered from OpenCode, Pi, and OMP without changing their files; the same key across harnesses is shown as one identity. Browser billing discovery is opt-in via
--opencode-zen-browser, Linux-only, and requires an already authenticated browser session that cclimits can read without modifying the profile. - Cursor / Windsurf: Not supported yet as they do not provide public quota APIs.
- Python 3.9+
requestslibrary (optional, falls back to urllib)
MIT