# What Kind of Output Does CodexBar Generate?

> Discover the real-time AI data CodexBar displays. Get insights into usage metrics, credit balances, cost estimates, and dynamic status icons in a native macOS menu-bar interface.

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

---

**CodexBar generates a native macOS menu-bar interface that renders real-time AI provider data as interactive SwiftUI cards, featuring usage metrics, credit balances, cost estimates, and dynamic status icons within an NSMenu.**

CodexBar is a macOS menu-bar application developed in the steipete/CodexBar repository that transforms raw API responses from AI providers into structured visual output. Unlike simple text logs, the **CodexBar output** consists of rich SwiftUI components embedded within native AppKit menus, providing immediate visual feedback on usage quotas and spending across services including OpenAI, Anthropic Claude, and Mistral.

## Native macOS Output Components

The application produces three distinct output layers that work together to create a cohesive user experience.

### Dynamic Status-Item Icon

The primary output starts with a status-item icon located in the macOS menu bar. According to the source code in `Sources/CodexBar/StatusItemController+IconObservation.swift`, this icon dynamically changes color to reflect quota warnings, alerting users when they approach usage limits without requiring menu interaction.

### Interactive SwiftUI Menu Cards

When users click the status icon, CodexBar builds a native `NSMenu` populated with `UsageMenuCardView` instances. Each card is constructed using SwiftUI but hosted within AppKit via `NSHostingView`, creating a hybrid architecture that leverages modern declarative syntax while maintaining native macOS menu behavior. The `UsageMenuCardView.Model.make` method defined in [`Sources/CodexBar/MenuCardView.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/MenuCardView.swift) (lines 310-337) assembles these cards from provider snapshots, account metadata, and usage statistics.

### Live-Updating Subtitles and Actions

The output includes real-time subtitle updates that refresh while the menu remains open, driven by the `StatusItemMenuPersistentActionDelegate` protocol. This mechanism, implemented in [`Sources/CodexBar/StatusItemMenu.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/StatusItemMenu.swift), allows the UI to reflect the latest API responses without forcing users to close and reopen the menu.

## Anatomy of the Usage Menu Card Output

Each menu card contains several structured sections that organize complex API data into scannable visual elements.

### Header and Provider Identification

The card header displays the provider name, user email address, and optional plan tier through the `UsageMenuCardHeaderView` component. This section provides immediate context about which AI service account the data represents.

### Metrics Visualization with Warning Markers

The `MetricRow` component (lines 559-585 in [`Sources/CodexBar/MenuCardView.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/MenuCardView.swift)) renders horizontal progress bars for metrics like "Tokens used" or "Requests left." These rows support visual warning markers at specified percentage thresholds—typically 80% and 90%—and include detailed left/right text showing absolute values alongside percentages.

### Credits and Cost Visualizations

CodexBar outputs financial data through specialized components. The `CreditsBarContent` (lines 774-822) displays remaining credits with scaled progress bars and copy-to-clipboard overlays. Meanwhile, `ProviderCostContent` (lines 321-345 and 506-525) renders estimated token costs, daily and weekly spending comparisons, and contextual hints about billing cycles.

### Usage Notes and Placeholder States

When providers return incomplete data or when accounts lack usage history, the `UsageNotesContent` (lines 536-544) displays free-form notes or placeholder text explaining the data absence.

## Implementing CodexBar Output in Code

To generate these interface elements programmatically, the codebase follows a model-view architecture that separates data preparation from visual rendering.

### Creating a Usage Card Model

First, initialize the view model using the factory method in [`MenuCardView.swift`](https://github.com/steipete/CodexBar/blob/main/MenuCardView.swift):

```swift
let model = UsageMenuCardView.Model.make(
    Input(
        provider: .openai,
        snapshot: usageSnapshot,
        account: accountInfo,
        metadata: providerMetadata,
        // …other required fields…
    )
)

let card = UsageMenuCardView(model: model, width: 320)

```

This pattern creates a configured `UsageMenuCardView` ready for embedding in the menu.

### Adding Cards to the Status Menu

The `StatusItemMenu` class handles the integration between SwiftUI and AppKit:

```swift
let menu = StatusItemMenu()
menu.addItem(
    NSMenuItem(title: "", action: nil, keyEquivalent: "")
        .then { $0.view = NSHostingView(rootView: card) }
)

```

This technique, found in [`Sources/CodexBar/StatusItemMenu.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/StatusItemMenu.swift) (lines 15-38), creates empty menu items and assigns SwiftUI views to their `view` property, bypassing the standard text-based menu item limitations.

### Enabling Live Refresh Delegates

To support live subtitle updates, implement the persistent action delegate:

```swift
class MyRefreshDelegate: StatusItemMenuPersistentActionDelegate {
    func performPersistentRefreshAction(in menuID: ObjectIdentifier) {
        usageStore.refreshAllProviders()
    }
    // …other delegate methods…
}
menu.persistentActionDelegate = MyRefreshDelegate()

```

This delegate pattern, defined around lines 18-35 in [`StatusItemMenu.swift`](https://github.com/steipete/CodexBar/blob/main/StatusItemMenu.swift), triggers background refreshes while the menu remains visible.

### Rendering Metric Rows with Visual Alerts

For individual metric visualization with threshold warnings:

```swift
MetricRow(
    metric: UsageMenuCardView.Model.Metric(
        id: "tokens",
        title: "Tokens",
        percent: 73,
        percentStyle: .left,
        warningMarkerPercents: [80, 90],
        workdayMarkerPercents: [],
        cardStyle: false
    ),
    title: "Tokens",
    progressColor: .blue
)

```

This component from [`Sources/CodexBar/MenuCardView.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/MenuCardView.swift) (lines 559-584) generates the progress bars with colored warning indicators seen in the final output.

## Summary

- **CodexBar output** consists of a dynamic status-item icon, interactive SwiftUI menu cards, and live-updating subtitles that provide real-time AI provider monitoring.
- The architecture combines **SwiftUI** views with **AppKit** `NSMenu` hosting to create native macOS interface elements that display usage metrics, credit balances, and cost estimates.
- Key implementation files include [`MenuCardView.swift`](https://github.com/steipete/CodexBar/blob/main/MenuCardView.swift) for card construction, [`StatusItemMenu.swift`](https://github.com/steipete/CodexBar/blob/main/StatusItemMenu.swift) for menu management, and `StatusItemController+IconObservation.swift` for icon behavior.
- The system supports **visual warning markers** at configurable thresholds and maintains **live data updates** without requiring menu reopening.

## Frequently Asked Questions

### What determines the color of the CodexBar status icon?

The icon color changes based on quota warnings and usage thresholds defined in `Sources/CodexBar/StatusItemController+IconObservation.swift`. When usage approaches predefined limits—typically 80% or 90% of available credits or tokens—the icon shifts color to provide immediate visual alerts in the menu bar.

### How does CodexBar display SwiftUI content inside a native macOS menu?

The application creates standard `NSMenuItem` instances but assigns SwiftUI views to their `view` property using `NSHostingView`, as implemented in [`Sources/CodexBar/StatusItemMenu.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/StatusItemMenu.swift) (lines 15-38). This hybrid approach allows modern SwiftUI card layouts to function within the traditional AppKit menu infrastructure.

### Can the output display custom warning thresholds for different metrics?

Yes, the `MetricRow` component supports the `warningMarkerPercents` parameter, which accepts an array of percentage values where visual warning indicators should appear. According to the implementation in [`Sources/CodexBar/MenuCardView.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/MenuCardView.swift) (lines 559-585), these markers render as color changes on the progress bar at the specified intervals.

### Does CodexBar support output formats beyond the menu-bar interface?

Yes, the repository includes [`Sources/CodexBarCore/WidgetSnapshot.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/WidgetSnapshot.swift), which provides snapshot data structures for rendering CodexBar information in macOS widgets. While the primary output targets the menu bar, the underlying data models support multiple presentation formats including desktop widgets.