# Codexbar Menubar AI Usage Tracker

> Monitor AI coding assistant usage limits and token resets in the macOS menu bar with CodexBar

- Skill: `aradotso/codexbar-menubar-ai-usage-tracker` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aradotso/codexbar-menubar-ai-usage-tracker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aradotso/codexbar-menubar-ai-usage-tracker/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aradotso (https://skillmd.com/u/aradotso)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aradotso/codexbar-menubar-ai-usage-tracker

---


# CodexBar Menu Bar AI Usage Tracker

> Skill by [ara.so](https://ara.so) — Codex Skills collection.

CodexBar is a macOS menu bar application that displays real-time usage statistics for AI coding assistants including OpenAI Codex, Claude, Cursor, Gemini, Copilot, and 25+ other providers. It shows token limits, credit balances, reset countdowns, and provider status without requiring separate logins. Built with Swift for macOS 14+, it includes both a GUI app and CLI for scripting.

## Installation

### Homebrew (Recommended)

```bash
brew install --cask steipete/tap/codexbar
```

### GitHub Releases

Download the latest `.dmg` from:
```
https://github.com/steipete/CodexBar/releases/latest
```

### CLI Only (macOS/Linux)

```bash
# macOS/Linux CLI via Homebrew
brew install steipete/tap/codexbar

# Or download tarballs from releases:
# CodexBarCLI-v<version>-macos-arm64.tar.gz
# CodexBarCLI-v<version>-linux-x86_64.tar.gz
```

### First Launch

1. Open CodexBar from Applications
2. Go to Settings → Providers
3. Enable the providers you use (Codex, Claude, Cursor, etc.)
4. Authenticate via the supported methods for each provider

## Requirements

- **macOS**: 14+ (Sonoma) for GUI app
- **Linux**: CLI only
- **Permissions** (optional, per provider):
  - Full Disk Access: for Safari cookie access
  - Keychain: for browser cookie decryption and OAuth tokens

## Configuration

### Using the GUI

Settings → Providers shows all available providers with toggles. Each provider has specific auth requirements listed in its documentation.

### Using the CLI

Configuration lives in `~/.codexbar/config.json`:

```bash
# List all providers
codexbar config providers

# Enable a provider
codexbar config enable --provider grok

# Disable a provider
codexbar config disable --provider cursor

# Set API key from environment variable
printf '%s' "$OPENROUTER_API_KEY" | codexbar config set-api-key --provider openrouter --stdin

# Set API key directly (not recommended for scripts)
codexbar config set-api-key --provider deepseek --api-key "sk-xxxxx"

# Set API key without enabling
printf '%s' "$VENICE_API_KEY" | codexbar config set-api-key --provider venice --stdin --no-enable
```

The `set-api-key` command:
- Trims input whitespace
- Sets restrictive file permissions on config
- Enables the provider by default (use `--no-enable` to prevent)

## Key Commands

### CLI Usage

```bash
# Show usage for a specific provider
codexbar usage --provider codex

# Check cost/usage for last 30 days (local scan)
codexbar cost --provider codex
codexbar cost --provider claude
codexbar cost --provider both

# Refresh all enabled providers
codexbar refresh

# Show app version
codexbar version

# Configuration commands
codexbar config providers
codexbar config enable --provider <name>
codexbar config disable --provider <name>
codexbar config set-api-key --provider <name> --stdin
```

### Exit Codes

- `0`: Success
- `1`: General error
- `2`: Authentication/configuration error
- `3`: Network/API error

## Provider Configuration Examples

### OpenAI Codex

**Authentication**: OAuth API or local Codex CLI

```bash
# Enable Codex provider
codexbar config enable --provider codex

# Optional: Add OpenAI web dashboard cookies for extras
# (code review remaining, usage breakdown, credits history)
# Configure via Settings → Providers → Codex → OpenAI cookies
```

### Claude (Anthropic)

**Authentication**: OAuth API, browser cookies, or CLI PTY fallback

```bash
# Enable Claude
codexbar config enable --provider claude

# Uses OAuth by default
# Falls back to browser cookies or Claude CLI if needed
```

### Cursor

**Authentication**: Browser session cookies

```bash
codexbar config enable --provider cursor

# Requires browser cookies from cursor.sh
# Shows plan, usage, and billing resets
```

### OpenRouter

**Authentication**: API token

```bash
# Set API key from environment
printf '%s' "$OPENROUTER_API_KEY" | codexbar config set-api-key --provider openrouter --stdin

# Or configure in GUI: Settings → Providers → OpenRouter
```

### DeepSeek

**Authentication**: API key

```bash
# Set API key securely
printf '%s' "$DEEPSEEK_API_KEY" | codexbar config set-api-key --provider deepseek --stdin
```

### Gemini

**Authentication**: OAuth via Gemini CLI credentials

```bash
codexbar config enable --provider gemini

# Uses gcloud OAuth, no browser cookies required
```

### GitHub Copilot

**Authentication**: GitHub device flow

```bash
codexbar config enable --provider copilot

# Uses GitHub device flow + Copilot internal usage API
```

## Swift Integration

CodexBar is built with Swift. To integrate provider parsing or usage tracking:

### Reading Configuration

```swift
import Foundation

struct CodexBarConfig: Codable {
    var providers: [String: ProviderConfig]
}

struct ProviderConfig: Codable {
    var enabled: Bool
    var apiKey: String?
}

func loadConfig() throws -> CodexBarConfig {
    let configPath = FileManager.default.homeDirectoryForCurrentUser
        .appendingPathComponent(".codexbar/config.json")
    let data = try Data(contentsOf: configPath)
    return try JSONDecoder().decode(CodexBarConfig.self, from: data)
}

// Usage
do {
    let config = try loadConfig()
    if config.providers["codex"]?.enabled == true {
        print("Codex provider is enabled")
    }
} catch {
    print("Failed to load config: \(error)")
}
```

### Calling CLI from Swift

```swift
import Foundation

func runCodexBarCLI(args: [String]) throws -> String {
    let process = Process()
    process.executableURL = URL(fileURLWithPath: "/opt/homebrew/bin/codexbar")
    process.arguments = args
    
    let pipe = Pipe()
    process.standardOutput = pipe
    
    try process.run()
    process.waitUntilExit()
    
    let data = pipe.fileHandleForReading.readDataToEndOfFile()
    return String(data: data, encoding: .utf8) ?? ""
}

// Get usage for a provider
do {
    let output = try runCodexBarCLI(args: ["usage", "--provider", "codex"])
    print(output)
} catch {
    print("CLI error: \(error)")
}
```

## Common Patterns

### Scripting Cost Tracking

```bash
#!/bin/bash
# Track AI coding costs daily

LOG_FILE="$HOME/ai-usage-log.txt"
DATE=$(date +%Y-%m-%d)

echo "=== $DATE ===" >> "$LOG_FILE"
codexbar cost --provider both >> "$LOG_FILE" 2>&1

# Alert if cost exceeds threshold
COST=$(codexbar cost --provider codex | grep -o '\$[0-9.]*' | head -1 | tr -d '$')
if (( $(echo "$COST > 50.0" | bc -l) )); then
    echo "Warning: Codex cost ($COST) exceeds $50" | mail -s "AI Cost Alert" user@example.com
fi
```

### Automated Provider Enablement

```bash
#!/bin/bash
# Enable all providers from environment

PROVIDERS=(
    "codex:$OPENAI_API_KEY"
    "openrouter:$OPENROUTER_API_KEY"
    "deepseek:$DEEPSEEK_API_KEY"
    "venice:$VENICE_API_KEY"
)

for entry in "${PROVIDERS[@]}"; do
    IFS=: read -r provider key <<< "$entry"
    if [ -n "$key" ]; then
        printf '%s' "$key" | codexbar config set-api-key --provider "$provider" --stdin
        echo "Enabled $provider"
    fi
done
```

### Menu Bar Icon Modes

CodexBar supports two display modes:

**Individual Icons** (default):
- One menu bar icon per enabled provider
- Each shows provider-specific usage bar

**Merge Icons Mode**:
- Single menu bar icon with all providers
- Click to switch between providers
- Enable in Settings → Display → Merge Icons

### Refresh Cadence

```bash
# Set refresh interval via GUI: Settings → Refresh
# Options: manual, 1m, 2m, 5m, 15m

# Or edit ~/.codexbar/config.json:
{
  "refreshInterval": 300  // 5 minutes in seconds
}
```

## Troubleshooting

### "Full Disk Access required" for Safari cookies

1. Open **System Settings** → **Privacy & Security** → **Full Disk Access**
2. Add `CodexBar.app`
3. Restart CodexBar

Alternative: Use Chrome/Brave/Arc cookies or API keys instead.

### Keychain prompts for browser cookies

1. Open **Keychain Access.app**
2. Search for "Chrome Safe Storage" (or your browser)
3. Double-click → **Access Control** tab
4. Click **+** and add `CodexBar.app`
5. Save and restart CodexBar

### Keychain prompts for Claude OAuth

1. Open **Keychain Access.app**
2. Search for "Claude Code-credentials"
3. Double-click → **Access Control** tab
4. Click **+** and add `CodexBar.app`
5. Save and restart CodexBar

### Provider shows "stale" or "error"

```bash
# Check provider status via CLI
codexbar usage --provider <name>

# Force refresh
codexbar refresh

# Check logs (GUI app)
# Console.app → search for "CodexBar"

# Verify authentication
codexbar config providers
```

### CLI not found after Homebrew install

```bash
# Ensure Homebrew bin is in PATH
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify installation
which codexbar
codexbar version
```

### "Permission denied" on config file

```bash
# Fix permissions
chmod 600 ~/.codexbar/config.json
```

### Provider authentication issues

**Codex/OpenAI**:
- Ensure `openai` CLI is installed and authenticated: `openai auth login`
- Or configure API key in Settings

**Claude**:
- Install Claude CLI: `brew install anthropics/claude/claude`
- Authenticate: `claude auth login`

**Cursor**:
- Sign in to cursor.sh in browser
- CodexBar will read session cookies

**Gemini**:
- Install `gcloud` CLI
- Authenticate: `gcloud auth login`

## Advanced Usage

### Local Cost Scanning

CodexBar can scan local JSONL logs for Codex and Claude usage over the last 30 days:

```bash
# Scan Codex local logs
codexbar cost --provider codex

# Scan Claude local logs
codexbar cost --provider claude

# Scan both
codexbar cost --provider both
```

Logs locations:
- **Codex**: `~/Library/Application Support/Code/User/globalStorage/openai.codex/logs/`
- **Claude**: `~/Library/Application Support/Claude/claude_desktop_config.json` (log path)

### Provider Status Polling

CodexBar polls provider status pages and shows incident badges:

- Green: Operational
- Yellow: Degraded performance
- Red: Outage
- Overlay indicator on menu bar icon

Configure in Settings → Status Polling.

### Widgets (macOS)

CodexBar includes WidgetKit widgets for supported providers:

1. Right-click Desktop → Edit Widgets
2. Search "CodexBar"
3. Add provider widgets to desktop or Notification Center

Supported: Codex, Claude, Cursor, Copilot, OpenRouter

### Notifications

Enable quota notifications in Settings:

- Session quota warnings
- Weekly reset notifications
- Optional confetti effect on reset 🎉

## Environment Variables

```bash
# Provider API keys (examples)
export OPENAI_API_KEY="sk-proj-xxxxx"
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
export OPENROUTER_API_KEY="sk-or-xxxxx"
export DEEPSEEK_API_KEY="sk-xxxxx"
export VENICE_API_KEY="xxxxx"
export MOONSHOT_API_KEY="sk-xxxxx"
export ZAI_API_TOKEN="xxxxx"
export WARP_API_TOKEN="xxxxx"

# Set all at once
cat > ~/.codexbar.env << 'EOF'
export OPENROUTER_API_KEY="sk-or-xxxxx"
export DEEPSEEK_API_KEY="sk-xxxxx"
EOF

source ~/.codexbar.env
```

## Resources

- **Documentation**: `docs/` directory in repository
- **Provider details**: `docs/providers.md`
- **CLI reference**: `docs/cli.md`
- **Development guide**: `docs/DEVELOPMENT.md`
- **Architecture**: `docs/architecture.md`
- **Issue tracker**: GitHub Issues with labels (see `docs/ISSUE_LABELING.md`)

## Privacy & Security

- **No password storage**: CodexBar reuses browser sessions, OAuth tokens, and API keys
- **On-device parsing**: Usage data stays local
- **Restrictive permissions**: Config file has `600` permissions
- **Known locations only**: Reads specific config files, not filesystem crawling
- **Open source**: Full audit available at `github.com/steipete/CodexBar`

See privacy discussion: [Issue #12](https://github.com/steipete/CodexBar/issues/12)