CodexBar Development Goals: Real-Time AI Monitoring Through Privacy-First macOS Architecture

CodexBar development goals center on delivering immediate visibility into AI coding rate limits via a lightweight, extensible macOS menu-bar application that respects user privacy and supports cross-platform automation.

The CodexBar project, maintained by steipete, is a macOS 14+ application designed to eliminate unexpected API throttling by displaying live usage metrics directly in the system menu bar. These development goals—spanning real-time monitoring, privacy preservation, and robust testability—are encoded directly into the repository’s modular Swift architecture and command-line tooling.

Real-Time AI Usage Visibility

A primary CodexBar development goal is making AI-coding limits tangible through live status indicators. The application displays usage meters, reset countdowns, and cost/credit information for dozens of providers directly in the macOS menu bar.

This visibility goal is implemented in Sources/CodexBar/StatusItemController.swift, which manages the NSStatusItem presentation without creating a Dock presence. The architecture leverages a background timer system that feeds refreshed data into UsageStore, ensuring the UI reflects current API consumption without polling overhead.

Privacy-First Design Principles

CodexBar adopts a strict privacy-first architecture that reuses existing OAuth sessions, browser cookies, or API keys rather than storing credentials. The codebase never persists passwords, reading only the minimal data required to fetch usage statistics.

This approach is documented in the repository’s README and enforced through the provider abstraction layer in Sources/CodexBarCore/Providers/Providers.swift. By integrating with existing authentication flows rather than implementing proprietary credential management, the project minimizes attack surface and respects user data sovereignty.

Minimal UI Footprint

The project emphasizes a "tiny menu bar app" philosophy that stays out of the user’s way. CodexBar runs exclusively as a menu-bar icon with no Dock or application switcher presence, featuring an optional "Merge Icons" mode that condenses multiple provider statuses into a single composite view.

This minimal footprint is achieved through NSApplication activation policies configured in the app delegate, while the StatusItemController handles dynamic menu generation for individual providers or the merged icon state.

Extensible Provider Architecture

Scalability drives the CodexBar development goals through a clean separation of concerns across modular layers:

• CodexBarCore: Handles background fetching, parsing, and data models
• CodexBar: Manages the macOS UI and status items
• CodexBarWidget: Implements widget extensions and snapshots

New AI providers are added by conforming to the provider protocol in Sources/CodexBarCore/Providers/Providers.swift, which centralizes supported service enumeration. The data flow moves from background fetchers through UsageStore to the UI layer, enabling parallel provider updates without blocking the main thread.

Cross-Platform CLI and Automation

Beyond the GUI, CodexBar development goals include robust automation support through a bundled codexbar CLI. The command-line interface enables scripting, CI integration, and Linux desktop environment support (including Waybar and GNOME extensions).

The CLI entry point resides in Sources/CodexBarCLI/main.swift, exposing commands for provider configuration, status queries, and cost analysis. This dual-interface approach ensures developers can monitor API limits whether running locally on macOS or automated on Linux servers.

Robust Test-Driven Development

Code quality goals mandate Swift 6 concurrency compliance, a sharded XCTest suite, and automated lint/format checks. The development workflow outlined in docs/DEVELOPMENT.md requires strict concurrency safety and parallel test execution to maintain reliability across the asynchronous provider fetch operations.

The Scripts/compile_and_run.sh utility encapsulates this workflow, building the project, executing the sharded test suite, and launching the GUI for manual verification.

Key Implementation Files

Several critical files embody the CodexBar development goals:

• Sources/CodexBarCore/Providers/Providers.swift – Central enumeration of supported providers illustrating extensibility
• Sources/CodexBar/StatusItemController.swift – Implements the menu-bar status item and UI visibility controls
• Sources/CodexBarCLI/main.swift – Entry point for the bundled codexbar CLI tool
• Scripts/compile_and_run.sh – Development script enforcing build, test, and launch standards
• docs/architecture.md – Documents the modular layer separation and data flow
• docs/DEVELOPMENT.md – Outlines Swift 6 concurrency requirements and sharded testing

CLI Automation Examples

The following commands demonstrate the project’s automation and cross-platform goals:

# List all configured providers

codexbar config providers

# Enable Grok provider and set API key securely

codexbar config enable --provider grok
printf '%s' "$GROK_API_KEY" | codexbar config set-api-key --provider grok --stdin

# Check current OpenAI usage

codexbar status --provider openai

# Run cost analysis for specific providers

codexbar cost --provider codex
codexbar cost --provider claude

# Launch the GUI during development

open CodexBar.app

Summary

The CodexBar development goals establish a framework for transparent AI resource management:

• Real-time visibility via menu-bar indicators showing usage meters and reset timers
• Privacy preservation through session reuse and zero password persistence
• Minimal footprint through menu-bar-only operation with optional icon merging
• Extensible architecture separating core logic from UI via CodexBarCore and provider protocols
• Automation support through the codexbar CLI and Linux desktop integrations
• Code quality enforced by Swift 6 concurrency, sharded XCTest suites, and automated linting

Frequently Asked Questions

How does CodexBar maintain user privacy while accessing AI provider data?

CodexBar reuses existing OAuth sessions, browser cookies, or API keys stored in system keychains rather than persisting passwords in its own storage. The provider implementations in Sources/CodexBarCore/Providers/ read only the minimal data required for usage statistics, never storing credentials locally beyond the macOS Secure Enclave or Keychain access granted by the user.

What makes CodexBar extensible to new AI providers?

The architecture separates provider-specific logic into the CodexBarCore layer, where Providers.swift defines a protocol-based interface. Adding support for a new service requires implementing this protocol to handle authentication headers and parsing usage JSON, without modifying the UI code in CodexBar or CodexBarWidget. This modularity allows contributors to add providers through isolated PRs.

Can CodexBar be used on Linux without the macOS GUI?

Yes. The codexbar CLI bundled with the application supports full functionality on Linux, including provider configuration, status queries, and cost analysis. The CLI is compatible with automation scripts and desktop environment integrations like Waybar, making it suitable for CI/CD pipelines and Linux development workstations.

What testing standards does the CodexBar project enforce?

The project requires Swift 6 concurrency compliance throughout the codebase, utilizing actors and structured concurrency to prevent data races. Tests run via a sharded XCTest suite configured in Scripts/compile_and_run.sh, allowing parallel execution of provider tests. Additionally, automated linting and formatting checks gate all contributions to maintain consistent code style.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}