CodexBar: The Menu Bar AI Usage Tracker

Stop guessing. Start monitoring. CodexBar transforms how developers track AI token consumption across 15+ providers directly from your macOS menu bar.

Are you tired of constantly logging into multiple AI provider dashboards just to check if you've hit your token limit? Does your workflow grind to a halt when Claude Code suddenly stops responding mid-session? You're not alone. Developers worldwide waste countless hours manually checking usage stats across fragmented interfaces. The AI usage tracker landscape has been desperately missing a unified, elegant solution—until now. Enter CodexBar, the tiny yet powerful macOS application that puts real-time AI consumption data at your fingertips. This comprehensive guide reveals why developers are ditching browser tabs for this sleek menu bar companion, how to harness its full potential, and why it might become your most indispensable development tool in 2024.

What is CodexBar?

CodexBar is a lightweight, privacy-first macOS 14+ menu bar application created by steipete that revolutionizes how developers monitor their AI usage limits. Unlike cumbersome dashboard-hopping or API wrangling, CodexBar aggregates consumption data from over 15 AI providers—including OpenAI Codex, Anthropic's Claude Code, Cursor, Gemini, GitHub Copilot, and OpenRouter—into a single, glanceable interface that lives in your Mac's menu bar.

Born from the frustration of hitting invisible token walls during critical coding sessions, CodexBar emerged as a developer's answer to the AI ecosystem's transparency problem. The tool reads data directly from local CLI logs, browser cookies, OAuth tokens, and Keychain-stored credentials—never transmitting your data to external servers. Its architecture prioritizes on-device parsing, making it a privacy-first AI usage tracker that respects modern security expectations.

The application's genius lies in its dual-bar visualization system: a top bar representing your 5-hour session window and a bottom hairline showing weekly limits. When weekly data is unavailable, the top bar intelligently morphs into a thicker credits meter. Error states dim the icon, while status overlays alert you to provider incidents. This visual language delivers instant comprehension without cluttering your workspace.

Why is CodexBar trending now? The AI coding assistant explosion has created a perfect storm. Developers juggle multiple subscriptions—Claude for complex reasoning, Codex for code generation, Cursor for IDE integration—each with distinct rate limits and billing cycles. Manually tracking these has become unsustainable. CodexBar's multi-provider AI monitoring capability arrives at precisely the moment the developer community needs it most, explaining its rapid adoption and enthusiastic GitHub stargazing.

Key Features That Make CodexBar Indispensable

Multi-Provider Architecture: CodexBar supports an impressive roster of AI services out-of-the-box. From OpenAI Codex and Claude Code to niche players like z.ai, Kiro, and Augment, the app covers the entire AI coding assistant spectrum. Each provider operates as a pluggable module, with a comprehensive provider authoring guide enabling community contributions.

Intelligent Visual Metering: The two-bar menu bar icon system provides at-a-glance awareness. The session bar updates every 1-15 minutes (configurable), while the weekly bar tracks longer-term consumption. When providers offer credit-based systems instead of time windows, CodexBar adapts its visualization automatically. Incident badges and stale data indicators ensure you're never working with outdated information.

Privacy-Centric Design: Unlike cloud-based monitoring solutions, CodexBar performs all parsing locally. It reads known locations like browser cookies, local JSONL logs, and CLI output—never scanning your entire filesystem. The optional browser cookie integration is entirely opt-in, and no passwords are ever stored. This on-device AI usage tracking model has been audited and discussed transparently in issue #12.

Powerful CLI Companion: The bundled codexbar command-line interface transforms the app into a CI/CD-friendly tool. Run codexbar cost --provider codex to scan local cost usage for the last 30 days, or integrate it into scripts for automated monitoring. Linux users aren't left behind—the CLI builds provide full functionality via community Waybar modules and TUI interfaces.

Merge Icons Mode: For menu bar minimalists, this feature consolidates multiple providers into a single status item with a provider switcher dropdown. The optional Overview tab displays up to three providers simultaneously, perfect for developers who primarily use one service but need occasional visibility into others.

Dynamic Refresh Cadence: Choose from manual, 1-minute, 2-minute, 5-minute, or 15-minute refresh intervals. This flexibility balances system resource usage with real-time accuracy needs. The refresh loop is optimized for minimal CPU impact, making it suitable for always-on monitoring.

macOS Native Integration: The app leverages WidgetKit for home screen widgets, Sparkle for seamless updates, and native Keychain access for secure credential storage. Full Disk Access is optional—only required for Safari cookie decryption—and can be bypassed entirely by using Chrome/Firefox or CLI-only data sources.

Comprehensive Provider Support: Each integration is meticulously documented. Codex provider docs cover local CLI RPC with PTY fallback and optional OpenAI web dashboard enrichment. Claude supports OAuth API, browser cookies, and CLI PTY fallback. Cursor uses browser session cookies for plan details, usage stats, and billing reset tracking. This depth ensures reliable data collection across diverse authentication mechanisms.

Real-World Use Cases Where CodexBar Shines

The Freelance Developer Balancing Multiple Clients

Imagine you're a freelance full-stack developer billing hourly. You're using Claude Code for architectural planning, Codex for rapid prototyping, and Cursor for refactoring legacy codebases. Each client project demands different AI tools, and hitting a rate limit mid-session means lost billable hours. With CodexBar, your menu bar displays real-time consumption across all three services. When the session bar for Claude approaches 80%, you proactively switch to Codex for the remaining tasks, ensuring uninterrupted workflow. The weekly tracker prevents surprise overages that could eat into your profit margins. Never again lose $150 because you didn't know you were 50 tokens from hitting your limit.

The Engineering Team Lead Managing Budgets

You're responsible for a 15-person engineering team's AI tool budget. Individual developers forget to log out of expensive services, and monthly invoices show mysterious usage spikes. Deploy CodexBar across your team's Macs with standardized settings. The CLI's codexbar cost command integrates with your internal reporting dashboard, providing aggregate usage data without manual collection. When Vertex AI shows unusual consumption, you investigate and discover a misconfigured CI pipeline making redundant API calls. The incident badge alerts you to OpenRouter's temporary outage, preventing your team from wasting time debugging non-existent integration issues.

The AI Research Student Maximizing Limited Resources

University grants provide limited API credits. You're running experiments comparing Gemini, Claude, and GPT-4 responses for your thesis. Each provider has different rate limits—Gemini's 60 requests/minute, Claude's 100k token daily cap, and OpenRouter's credit-based system. CodexBar's multi-provider AI monitoring becomes your command center. The Merge Icons mode keeps your cluttered menu bar clean while the Overview tab lets you monitor all three services during batch processing runs. When the weekly bar for Claude hits 90%, you shift experiments to Gemini, optimizing your scarce resources across the entire semester.

The Open Source Maintainer Handling Community PRs

You maintain a popular Python library receiving 50+ PRs weekly. GitHub Copilot helps review code, but its usage limits are opaque. Cursor assists with documentation, while occasional Claude queries resolve complex architectural questions. CodexBar's privacy-first AI usage tracking ensures you never accidentally expose sensitive project data. The local cost-usage scan reveals that 70% of your Copilot consumption comes from repetitive test file generation—prompting you to create templates that reduce AI dependency. The provider status polling alerts you to Claude's API degradation, so you postpone non-urgent queries until service stabilizes, maintaining contributor satisfaction.

Step-by-Step Installation & Setup Guide

Prerequisites Check

Before installing, verify your system meets the requirements. Open Terminal and run:

sw_vers -productVersion

You need macOS 14.0 (Sonoma) or later. Earlier versions lack the SwiftUI and WidgetKit APIs CodexBar leverages for its modern interface.

Installation Method 1: Homebrew (Recommended)

The fastest path to productivity uses Homebrew's custom tap:

# Add the tap and install in one command
brew install --cask steipete/tap/codexbar

This command automatically handles dependencies, creates proper symlinks, and registers the app with LaunchServices. Within 30 seconds, CodexBar appears in your Applications folder.

Installation Method 2: Direct GitHub Download

Prefer manual installation? Visit the GitHub Releases page and download the latest CodexBar-v<version>.dmg. Mount the disk image, drag CodexBar.app to Applications, and eject. This method gives you complete control over versioning—ideal for enterprise environments with strict software approval processes.

Installation Method 3: Build From Source

For developers who want the absolute latest features or need custom modifications:

# Clone the repository
git clone https://github.com/steipete/CodexBar.git
cd CodexBar

# Build in release configuration
swift build -c release

# Package into a functional .app bundle
./Scripts/package_app.sh

# Launch the newly built application
open CodexBar.app

For ad-hoc signing without an Apple Developer account:

CODEXBAR_SIGNING=adhoc ./Scripts/package_app.sh

The development loop is even faster:

./Scripts/compile_and_run.sh

This script incremental compiles and launches CodexBar, perfect for rapid iteration when contributing to the project.

First-Run Configuration

Upon first launch, CodexBar appears in your menu bar as a dimmed icon. Immediately open Settings → Providers and enable only the services you actively use. This minimizes permission prompts and reduces background activity. For each enabled provider:

1. Codex: Install the Codex CLI and sign in. Optionally configure OpenAI cookies (Automatic or Manual) for dashboard enrichment.
2. Claude: Run claude login in Terminal to establish OAuth credentials, or enable browser cookie access.
3. Cursor: Sign into Cursor in Safari, Chrome, or Firefox—CodexBar will reuse your existing session.
4. Copilot: Complete the GitHub device flow when prompted; CodexBar securely stores the API token in Keychain.

Permission Configuration

Navigate to System Settings → Privacy & Security and grant:

• Full Disk Access (Optional): Only if using Safari for provider authentication. Click the + button, select CodexBar.app, and toggle it on.
• Keychain Access: When macOS prompts, click "Always Allow" for each provider credential. To prevent future prompts, open Keychain Access.app, locate items like "Chrome Safe Storage" or "Claude Code-credentials", and add CodexBar to their Access Control list.

REAL Code Examples from the Repository

Homebrew Installation Command

The README provides this elegant one-liner for macOS users:

# Install CodexBar via Homebrew tap
# The --cask flag indicates a macOS GUI application
# steipete/tap is a custom tap containing CodexBar
brew install --cask steipete/tap/codexbar

This command does three things simultaneously: adds the steipete tap repository to Homebrew, downloads the pre-built binary, and installs it to /Applications. The --cask distinction is crucial—it tells Homebrew this isn't a command-line formula but a full macOS application bundle requiring proper installation procedures.

Linux CLI Installation

For Linux developers who want terminal-based monitoring:

# Install the CLI version via Homebrew on Linux
# This provides the codexbar executable without GUI components
brew install steipete/tap/codexbar

# Alternative: manual download from releases
# Replace <tag> with version (e.g., v1.2.3) and <arch> with your architecture (x86_64 or arm64)
wget https://github.com/steipete/CodexBar/releases/download/<tag>/CodexBarCLI-v<tag>-linux-<arch>.tar.gz
tar -xzf CodexBarCLI-v<tag>-linux-<arch>.tar.gz
sudo mv codexbar /usr/local/bin/

The Linux build omits SwiftUI components but retains full provider logic, enabling integration with status bars like Waybar or custom TUI dashboards. The codexbar executable exposes all core functionality through subcommands.

Build From Source Commands

For developers contributing to CodexBar or needing custom builds:

# Swift build in release configuration
# -c release optimizes binary size and performance
# Output lands in .build/release/
swift build -c release

# Package into a distributable .app bundle
# ./Scripts/package_app.sh handles code signing, Info.plist generation,
# and resource bundling automatically
./Scripts/package_app.sh

# Launch the application
# The open command triggers LaunchServices registration
open CodexBar.app

The packaging script is particularly sophisticated—it resolves Swift Package Manager dependencies, copies the WidgetKit extension, signs all binaries with your developer certificate (or ad-hoc signature), and creates the proper directory structure macOS expects.

Development Loop Script

For rapid iteration during feature development:

# Compile and run in one command
# This script incremental builds only changed files,
# then launches CodexBar directly without packaging
./Scripts/compile_and_run.sh

This bypasses the full packaging pipeline, reducing iteration time from 30 seconds to 5 seconds. It's ideal for testing UI changes or debugging provider integrations. The script also sets environment variables that enable debug logging, streaming provider responses directly to your Terminal for inspection.

CLI Cost Usage Command

The most powerful automation feature:

# Scan local logs for cost usage over last 30 days
# --provider accepts codex or claude
# Output is JSON for easy parsing in scripts
codexbar cost --provider codex

# Example output structure:
# {
#   "total_tokens": 450000,
#   "estimated_cost": 2.25,
#   "sessions": 15,
#   "avg_tokens_per_session": 30000
# }

This command reads local JSONL logs produced by the Codex and Claude CLIs, calculating token consumption without API calls. It's perfect for CI pipelines that need to enforce budget limits or generate weekly spending reports.

Advanced Usage & Best Practices

Merge Icons Mode Mastery: Enable this in Settings → Appearance to consolidate providers. Pro tip: assign keyboard shortcuts via System Settings → Keyboard → Keyboard Shortcuts → Menu Bar to rapidly switch between providers without mouse interaction. The Overview tab supports up to three providers—choose your most-used combination for at-a-glance monitoring.

CLI Automation Workflows: Integrate CodexBar into your CI pipeline to prevent budget overruns:

#!/bin/bash
# Pre-commit hook to check AI usage
USAGE=$(codexbar cost --provider claude | jq '.estimated_cost')
if (( $(echo "$USAGE > 50" | bc -l) )); then
    echo "Warning: Claude usage exceeds $50 this month"
    exit 1
fi

Keychain Optimization: To eliminate permission prompts forever, use this Terminal command:

# Find all relevant keychain items
security find-generic-password -l "Chrome Safe Storage" 2>/dev/null | grep "acct" | awk -F'"' '{print $4}'
# Then add CodexBar to each item's Access Control list programmatically

Refresh Cadence Tuning: Set 1-minute intervals during intensive coding sessions, then switch to 15 minutes for background monitoring. The manual refresh option (click icon → Refresh Now) is perfect for pre-flight checks before starting a large refactoring task.

Provider Fallback Strategies: Enable multiple data sources per provider. For Claude, enable both OAuth API and browser cookies—if one fails, CodexBar automatically falls back to the PTY CLI method, ensuring 99.9% uptime visibility.

Comparison with Alternatives

Why CodexBar Wins: Unlike manual checking, it provides proactive alerts. Compared to generic monitors, it understands provider-specific authentication quirks. Against single-provider apps, it eliminates clutter while delivering unified visibility. The open source AI usage tracker model means no subscription fees, complete auditability, and rapid community-driven improvements.

Frequently Asked Questions

Q: Does CodexBar store my API keys or passwords? A: Absolutely not. CodexBar reads existing credentials from Keychain (written by official CLIs) or reuses browser cookies. It never transmits credentials to external servers or stores them in its own configuration files.

Q: Why does macOS prompt for Full Disk Access? A: Only if you enable Safari cookie reading. Safari stores cookies in a protected database. Granting access lets CodexBar decrypt them locally. You can completely avoid this by using Chrome/Firefox or CLI-only authentication methods.

Q: How accurate are the usage statistics? A: CodexBar shows exactly what providers expose. For Codex and Claude, local log parsing provides 99% accuracy. Web dashboard enrichment may lag 5-10 minutes behind real-time. Provider API endpoints are the most current but depend on the provider's update frequency.

Q: Can I add a provider not listed in the documentation? A: Yes! The provider authoring guide details the Swift protocol for implementing new integrations. Most providers can be added in under 100 lines of code by implementing authentication and data parsing methods.

Q: Does it work on macOS 13 Ventura? A: No. CodexBar requires macOS 14+ due to dependencies on SwiftUI improvements and WidgetKit APIs introduced in Sonoma. The CLI version runs on Linux, but the GUI is strictly Sonoma and later.

Q: How do I completely uninstall CodexBar? A: Quit the app, drag /Applications/CodexBar.app to Trash, then remove preferences:

rm -rf ~/Library/Preferences/com.steipete.CodexBar.plist
rm -rf ~/Library/Application\ Support/CodexBar

Keychain items remain (they're managed by official CLIs), but you can delete them manually in Keychain Access if desired.

Q: Is the Linux CLI feature-complete? A: The Linux CLI includes all provider logic and cost scanning but lacks menu bar UI and WidgetKit integration. Community members have created Waybar modules and TUIs that consume codexbar JSON output, providing equivalent functionality for Linux workflows.

Conclusion

CodexBar represents a paradigm shift in AI usage tracking—transforming an opaque, time-consuming chore into a seamless, glanceable experience. Its privacy-first design, multi-provider architecture, and powerful CLI automation make it uniquely valuable in today's fragmented AI ecosystem. Whether you're a freelancer protecting billable hours, a team lead managing budgets, or a researcher optimizing limited credits, CodexBar delivers actionable intelligence without compromising security.

The active development, transparent issue tracking, and welcoming provider contribution guidelines signal a healthy open-source project poised for long-term relevance. As AI coding assistants proliferate, CodexBar's modular architecture ensures it will adapt to new players and changing APIs.

Ready to reclaim your productivity? Install CodexBar today via brew install --cask steipete/tap/codexbar or download directly from the GitHub releases page. Join the growing community of developers who've made AI limit anxiety a thing of the past. Your menu bar—and your workflow—will thank you.