What Kind of Output Does CodexBar Generate?

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 (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, 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) 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:

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:

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

This technique, found in 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:

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, triggers background refreshes while the menu remains visible.

Rendering Metric Rows with Visual Alerts

For individual metric visualization with threshold warnings:

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 (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 for card construction, 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 (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 (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, 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.

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