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](https://www.npmjs.com/package/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 |
|