How to Integrate CodexBar into Your Workflow: A Complete Guide

Integrate CodexBar into your workflow by installing the macOS menu-bar app or standalone CLI, configuring AI providers via codexbar config commands, and consuming real-time usage data through the UI, terminal, or automated scripts.

CodexBar is a lightweight macOS 14+ application that continuously monitors AI coding provider usage limits—tracking tokens, credits, reset timers, and cost spends—directly from your menu bar. Whether you prefer a visual always-on interface or headless automation, the tool offers multiple integration paths through its SwiftUI-based app, command-line interface, and WidgetKit extension. This guide covers the practical steps to embed CodexBar into your daily development and CI/CD pipelines using the exact implementation details found in the steipete/CodexBar repository.

Installation: App vs. CLI

You can integrate CodexBar as a visual menu-bar utility or as a standalone command-line tool depending on your environment.

Full macOS Application (includes UI, CLI, and widgets):

brew install --cask codexbar

CLI-only Installation (for Linux or headless macOS):

brew install steipete/tap/codexbar

The CLI executable is located in Sources/CodexBarCLI and provides the codexbar command used throughout this guide. The menu-bar application in Sources/CodexBar wraps this core functionality in a SwiftUI interface managed by AppDelegate.

Enable and Configure AI Providers

CodexBar uses a modular provider system defined in Sources/CodexBarCore to fetch usage data from services like OpenAI, Claude, and Codex RPC. Enable only the providers you need to minimize API calls and memory footprint.

List available providers:

codexbar config providers

Enable specific providers (e.g., Claude and OpenAI):

codexbar config enable --provider claude
codexbar config enable --provider openai

Configuration changes are written to SettingsStore and persisted in ~/.config/codexbar/config.json. The UsageFetcher in the data-fetching layer reads these toggles to adjust refresh cadence and feature flags automatically.

Secure API Key Management

Store provider credentials securely using the CLI's built-in key management, which trims whitespace and sets restrictive file permissions automatically.

Store an OpenAI API key:

printf '%s' "$OPENAI_API_KEY" | \
  codexbar config set-api-key --provider openai --stdin

Store a Claude token without enabling the provider immediately:

printf '%s' "$CLAUDE_TOKEN" | \
  codexbar config set-api-key --provider claude --stdin --no-enable

Keys are stored securely and accessed by the ProviderUsage probes in Sources/CodexBarCore during background refresh cycles.

Consuming Usage Data

CodexBar exposes three primary interfaces to consume data: the menu-bar UI, the CLI, and the WidgetKit extension in Sources/CodexBarWidget.

Command-line status checks:

# Concise status for all enabled providers

codexbar status

# Detailed usage for a single provider

codexbar usage --provider claude

# Export cost data for analysis

codexbar cost --provider openai --output openai_costs.csv

Scripting and CI integration:

The CLI returns structured data suitable for automation. For example, abort a CI job if quota exceeds 80%:

#!/usr/bin/env bash
OVER_LIMIT=$(codexbar status | grep -E '(80%|90%|100%)' || true)
if [[ -n $OVER_LIMIT ]]; then
  echo "⚠️ Quota limit reached:" $OVER_LIMIT
  exit 1
fi

The data flow follows this architecture: UsageFetcher (probes) → UsageStore (thread-safe state) → UI controllers/CLI commands. Swift 6 strict concurrency ensures all state is Sendable, with background fetches hopping to MainActor only when updating the UI.

Customizing the Interface

Open Settings → Providers in the menu-bar UI to toggle per-provider icons, bar styles, reset-time display, and merge-icon mode. These settings ripple immediately to both the UI and CLI because SettingsStore broadcasts changes to the fetching layer.

The presentation layer in Sources/CodexBar handles the status item, pop-over UI, and icon rendering, while Sources/CodexBarWidget provides desktop widgets for macOS.

Summary

• Install via Homebrew Cask for the full macOS experience or the tap formula for CLI-only Linux/macOS usage.
• Configure providers using codexbar config enable and codexbar config set-api-key to populate SettingsStore and ~/.config/codexbar/config.json.
• Consume data through the menu-bar UI, codexbar status CLI commands, or exported CSV files for spreadsheet analysis.
• Automate by parsing CLI output in shell scripts; the tool exits with standard codes suitable for CI pipelines.
• Customize visual preferences in the Settings UI, which automatically sync to the core data layer.

Frequently Asked Questions

Does CodexBar require macOS 14 or newer?

Yes. CodexBar targets macOS 14+ exclusively and uses Swift 6 strict concurrency throughout. The codebase avoids deprecated AppKit APIs in favor of SwiftUI and modern Observable patterns, requiring the latest runtime.

Can I use CodexBar without the menu-bar app?

Absolutely. The Sources/CodexBarCLI module provides a fully functional codexbar executable that operates independently of the UI. Install via brew install steipete/tap/codexbar to use only the command-line interface on macOS or Linux.

How does CodexBar handle data concurrency?

The architecture separates concerns between Sources/CodexBarCore (data fetching) and presentation layers (UI/CLI/Widget). All state is Sendable and stored in UsageStore, which is thread-safe. Background probes publish ProviderUsage models that consumers access without blocking the main thread.

Where is my configuration stored?

Settings are persisted to ~/.config/codexbar/config.json and managed by SettingsStore. API keys are stored with restrictive file permissions separate from the main configuration. Both the UI and CLI read from and write to this location, ensuring consistency across interfaces.

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