codexbar skill

---
name: codexbar
description: Monitor AI provider usage limits and costs using CodexBar CLI. Track Codex, Claude, Cursor, Gemini, and other AI service quotas, session limits, and cost metrics.
---

# CodexBar Skill

## Purpose

This skill provides command-line access to CodexBar's monitoring capabilities for AI service usage limits, quotas, and costs. Monitor your AI provider usage (Codex, Claude, Cursor, Gemini, etc.) directly from Claude Code without needing the menu bar app.

## When to Use This Skill

Trigger this skill when:
- User wants to check AI service usage limits
- User needs to monitor session or weekly quotas
- User wants to track AI provider costs
- User asks about remaining credits or tokens
- User needs to verify provider status or incidents

Example user requests:
- "Check my Codex usage"
- "How many Claude credits do I have left?"
- "Show my AI provider costs this month"
- "What's my current Cursor quota?"
- "codexbar status"

## Supported Providers

CodexBar monitors:
- **Codex** - OpenAI Codex (Claude Code) session + weekly usage
- **Claude** - Anthropic Claude (session + weekly limits)
- **Cursor** - Cursor editor plan + usage
- **Gemini** - Google Gemini quotas
- **Antigravity** - Antigravity usage
- **Droid (Factory)** - Factory usage + billing
- **Copilot** - GitHub Copilot usage
- **z.ai** - z.ai quota + MCP windows
- **Kimi** - Kimi weekly quota + rate limits
- **Kiro** - Kiro monthly credits
- **Vertex AI** - Google Cloud Vertex AI token costs
- **Augment** - Augment credits tracking
- **Amp** - Amp Free usage
- **JetBrains AI** - JetBrains AI monthly credits

## Installation

### macOS (Menu Bar App + CLI)
```bash
brew install --cask steipete/tap/codexbar
```

### Linux (CLI Only)
```bash
brew install steipete/tap/codexbar
```

Or download from [GitHub Releases](https://github.com/steipete/CodexBar/releases)

## CLI Commands

### Check Usage Status
```bash
codexbar status
```
Returns JSON with current usage for all enabled providers.

### Cost Tracking
```bash
# Show Codex costs (last 30 days)
codexbar cost --provider codex

# Show Claude costs (last 30 days)
codexbar cost --provider claude
```

### Provider-Specific Queries
The CLI reads from known provider locations:
- Browser cookies (Chrome, Firefox, Safari)
- OAuth credentials (Keychain)
- Local CLI configurations
- Log files (JSONL for Codex/Claude)

## Output Format

Status output (JSON):
```json
{
  "providers": {
    "codex": {
      "session": {
        "used": 1234,
        "limit": 5000,
        "remaining": 3766,
        "resets_in": "4h 23m"
      },
      "weekly": {
        "used": 12345,
        "limit": 50000,
        "remaining": 37655,
        "resets_in": "2d 5h"
      }
    },
    "claude": {
      "session": {...},
      "weekly": {...}
    }
  }
}
```

Cost output (JSON):
```json
{
  "provider": "codex",
  "period": "last_30_days",
  "total_cost": 42.50,
  "total_tokens": 1234567,
  "breakdown": [
    {
      "date": "2025-01-26",
      "cost": 2.30,
      "tokens": 45678
    }
  ]
}
```

## Configuration

CodexBar stores settings in:
- macOS: `~/Library/Application Support/CodexBar/`
- Provider credentials: System Keychain
- Browser cookies: Read-only access

Enable/disable providers in Settings → Providers (menu bar app).

## Workflow

```
User Request
    ↓
Determine Command Type:
  - status: Check quotas
  - cost: Track spending
    ↓
Execute codexbar CLI
    ↓
Parse JSON Output
    ↓
Present Results to User
```

## Implementation Details

### Core Operations

#### `get_status(provider=None)`
- Calls `codexbar status`
- Filters by provider if specified
- Returns parsed JSON with usage data

#### `get_costs(provider, days=30)`
- Calls `codexbar cost --provider <name>`
- Returns cost breakdown from local logs
- Supports: codex, claude

#### `format_usage(status_json)`
- Formats status output for user display
- Shows session/weekly meters
- Displays reset countdowns

### Provider Detection
CodexBar auto-detects enabled providers from:
- Environment variables (API keys)
- Browser sessions (cookies)
- OAuth credentials (Keychain)
- Local CLI tools (codex, claude, gemini)

### Usage in Claude Code

When user invokes this skill, Claude should:
1. Parse request for specific provider or command
2. Execute appropriate `codexbar` CLI command
3. Parse JSON output
4. Format results in readable table/summary
5. Highlight warnings (low credits, approaching limits)

## Error Handling

- If CodexBar not installed: Suggest installation via Homebrew
- If provider not enabled: Guide to Settings → Providers
- If credentials missing: Show provider-specific auth instructions
- If status stale: Suggest manual refresh in menu bar

## Privacy & Permissions

CodexBar requires:
- **Full Disk Access** (optional): For Safari cookies/local storage
- **Keychain Access**: For OAuth credentials, API tokens, browser cookie decryption
- **Files & Folders**: When provider CLIs access project directories

All parsing happens on-device. No data sent to external services.

## Slash Command Integration

Support `/codexbar` command:
```
/codexbar status
/codexbar cost codex
/codexbar cost claude
/codexbar check cursor
```

## Related Resources

- Repository: https://github.com/steipete/CodexBar
- Documentation: https://github.com/steipete/CodexBar/tree/main/docs
- CLI Reference: https://github.com/steipete/CodexBar/blob/main/docs/cli.md

## Credits

Inspired by [ccusage](https://github.com/ryoppippi/ccusage) - Cost usage tracking for AI providers.