# How to Integrate CodexBar into Your Workflow: A Complete Guide

> Integrate CodexBar into your workflow with our guide. Install the macOS app or CLI, configure AI providers, and access usage data easily. Streamline your coding now.

- Repository: [Peter Steinberger/CodexBar](https://github.com/steipete/CodexBar)
- Tags: how-to-guide
- Published: 2026-07-07

---

**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):

```bash
brew install --cask codexbar

```

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

```bash
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:

```bash
codexbar config providers

```

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

```bash
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:

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

```

Store a Claude token without enabling the provider immediately:

```bash
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:**

```bash

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

```bash
#!/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.