ai-usage

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

# 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:

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)

Claude: 4.0% (5h) ✅ | Codex: 0% (5h) ✅ | Z.AI: 1% ✅ | Gemini: ( 3-Flash 7% ✅ | Flash 1% ✅ | Pro 10% ✅ )

Detailed Output (default)

🔍 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 claude to 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+