AI CLI Usage Checker
Check remaining quota and usage for AI coding assistants: Claude Code, OpenAI Codex, Gemini CLI, and Z.AI.
Uses the cclimits npm package.
When to Use This Skill
- •User asks "how much quota do I have left?"
- •User asks "check my usage" or "am I rate limited?"
- •User wants to know which AI tool has capacity
- •Before starting a large task, to verify quota availability
- •User asks about token limits or remaining requests
Running the Command
bash
# Check all tools (detailed) npx cclimits # Compact one-liner (5h window) npx cclimits --oneline # Compact one-liner (7d window) npx cclimits --oneline 7d # Check specific tools npx cclimits --claude npx cclimits --codex npx cclimits --gemini npx cclimits --zai # JSON output (for scripting) npx cclimits --json
Credential Locations
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 |
Setup (One-Time)
If credentials are missing, run the corresponding CLI tool to authenticate:
bash
claude # Login to Claude Code codex login # Login to OpenAI Codex gemini # Login to Gemini CLI export ZAI_KEY=your-key # Add to ~/.zshrc
Output Interpretation
Quota Windows
Most tools use rolling windows:
- •5-hour window: Short-term rate limit
- •7-day window: Weekly quota limit
Percentage Used
- •0-50%: Plenty of capacity
- •50-70%: Moderate usage, plan accordingly
- •70-90%: High usage, may want to switch tools
- •90-100%: Near limit, expect rate limiting
Status Icons
| Icon | Meaning |
|---|---|
| ✅ | Under 70% - plenty of capacity |
| ⚠️ | 70-90% - moderate usage |
| 🔴 | 90-100% - near limit |
| ❌ | 100% or unavailable |
Gemini Tiers
Gemini models are grouped by quota tier (models in same tier share quota):
| Tier | Models |
|---|---|
| 3-Flash | gemini-3-flash-preview |
| Flash | gemini-2.5-flash, gemini-2.5-flash-lite, gemini-2.0-flash |
| Pro | gemini-2.5-pro, gemini-3-pro-preview |
Example Output
Compact One-liner (--oneline)
code
Claude: 4.0% (5h) ✅ | Codex: 0% (5h) ✅ | Z.AI: 1% ✅ | Gemini: ( 3-Flash 7% ✅ | Flash 1% ✅ | Pro 10% ✅ )
Detailed Output (default)
code
🔍 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 (GLM-4)
==================================================
✅ Connected
Token Quota:
Used: 1%
Remaining: 99%
(10,000 / 1,000,000 tokens)
Troubleshooting
"No credentials found"
- •Run the CLI tool to authenticate (see Setup section)
- •For Z.AI, ensure environment variable is set
"Token expired"
- •Claude: Run
claudeto re-authenticate - •Codex: Run
codex login - •Gemini: Run
gemini(or wait for auto-refresh)
API errors
- •Check internet connectivity
- •Verify the CLI tool works directly
- •Check if the service is down
Package Info
npm package: cclimits GitHub: cruzanstx/cclimits
Requires: Node.js 16+ and Python 3.10+