Check quota/usage for AI coding CLI tools: Claude Code, OpenAI Codex, 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
- Auto-refreshes expired tokens (Gemini OAuth, Antigravity OAuth)
- 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 --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# Single window (5h or 7d); Copilot shows its monthly premium-request quota as (mo)
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: 35% (8 models) ✅ | 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: 35% (8 models)
# With reset countdowns (--resets / --timeremaining) - ↻5h-reset/7d-reset; Antigravity shows its earliest model reset
Claude: 4.0%/10.0% ✅ ↻2h15m/3d17h | Codex: 0%/2% ✅ ↻1h05m/6d23h | Z.AI: 1% (5h) ✅ ↻3h02m | Antigravity: 3% (20 models) ✅ ↻10m
# --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
Model Quotas:
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) or macOS Keychain |
| Codex | ~/.codex/auth.json |
| 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 ~/.bashrcThe 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. - Cursor / Windsurf: Not supported yet as they do not provide public quota APIs.
- Python 3.9+
requestslibrary (optional, falls back to urllib)
MIT