codexbar-menubar-ai-usage-tracker

CodexBar Menu Bar AI Usage Tracker

Skill by 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)

brew install --cask steipete/tap/codexbar

GitHub Releases

Download the latest .dmg from:

https://github.com/steipete/CodexBar/releases/latest

CLI Only (macOS/Linux)

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

# 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

# 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

# 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

# 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

codexbar config enable --provider cursor

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

OpenRouter

Authentication: API token

# 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

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

Gemini

Authentication: OAuth via Gemini CLI credentials

codexbar config enable --provider gemini

# Uses gcloud OAuth, no browser cookies required

GitHub Copilot

Authentication: GitHub device flow

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

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

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

#!/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

#!/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

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

# 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

# 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

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

# 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

# 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