# CodexBar Performance Characteristics: A Deep Dive into the macOS Menu Bar Architecture

> Explore CodexBar's performance. Discover sub-10ms UI latency & adaptive background refresh via O(1) scheduling, GPU highlighting, JSONL scanning & zero-cost logging.

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

---

**CodexBar achieves sub-10ms UI latency and adaptive background refresh through deterministic O(1) scheduling, GPU-accelerated highlighting, high-throughput JSONL scanning, and zero-cost lazy logging.**

CodexBar is a macOS menu-bar utility that monitors AI provider usage without draining battery or blocking the main thread. Understanding the performance characteristics of CodexBar reveals how it maintains responsiveness while continuously polling usage data and rendering complex menu cards. The implementation spans five tightly integrated layers that prioritize deterministic execution and minimal allocation.

## Adaptive Refresh Scheduling with O(1) Complexity

The `UsageStore` drives the application's refresh cadence through a pure, deterministic policy engine that requires no system calls during computation.

In [`Sources/CodexBar/AdaptiveRefreshPolicy.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/AdaptiveRefreshPolicy.swift), the `AdaptiveRefreshPolicy` struct computes the next refresh delay from a small `Input` struct in **O(1)** time. This design ensures the timer logic never blocks the main thread or triggers expensive runtime calculations.

```swift
func nextDelay(for input: Input) -> Decision {
    if input.lowPowerModeEnabled || Self.isConstrained(input.thermalState) {
        return Decision(delay: .seconds(30 * 60), reason: .constrained)
    }
    // … calculate based on time since last menu open …
}

```

The policy reacts to `ProcessInfo` signals—low-power mode and thermal state—by extending the refresh interval to 30 minutes when constrained. This computation happens in `UsageStore+AdaptiveRefresh.swift`, which wires live system signals to the policy and logs the resulting decision without allocating intermediate strings.

## GPU-Accelerated Menu Card Highlighting

Scrolling long lists of usage rows previously forced full SwiftUI re-renders costing **3–10 ms** per highlight toggle. CodexBar eliminates this bottleneck through `GPUSelectionHostingView` in [`Sources/CodexBar/MenuCardGPUSelectionView.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/MenuCardGPUSelectionView.swift).

The implementation moves highlight state into a Core Animation layer property, reducing the toggle cost to approximately **0.05 ms**—a **60–200× improvement** over the standard SwiftUI approach.

```swift
let row = GPUSelectionHostingView(
    rootView: MenuCardSectionContainerView(content: myRowContent),
    allowsMenuHighlight: true,
    onClick: { print("row clicked") }
)
row.setHighlighted(true)   // toggles selection in < 0.1 ms

```

By avoiding SwiftUI's render pass during scroll operations, the menu remains fluid even with hundreds of usage entries visible.

## High-Throughput JSONL Scanning

CodexBar stores usage history in line-oriented JSONL files that must parse quickly without memory pressure. The `CostUsageJsonl.scan` method in [`Sources/CodexBarCore/CostUsageJsonl.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/CostUsageJsonl.swift) processes up to **256 KB** per line using a tiny front-buffer, avoiding repeated heap allocations.

Benchmarks in [`Tests/CodexBarTests/CostUsageJsonlShapeBenchmarkTests.swift`](https://github.com/steipete/CodexBar/blob/main/Tests/CodexBarTests/CostUsageJsonlShapeBenchmarkTests.swift) demonstrate approximately **30.4 MB s⁻¹** throughput on a 30-day sample, achieving a **2.1× speedup** over the older baseline implementation:

```

Codex JSONL shape benchmark: divisor=20 … current=30.4MB/s baseline=14.8MB/s speedup=2.1x

```

The scanner accepts parameters for `maxLineBytes` and `prefixBytes`, allowing callers to tune memory usage based on expected file sizes while maintaining consistent parsing performance.

## Zero-Cost Lazy Logging

Diagnostic output uses level-gated lazy evaluation to ensure disabled log levels incur **zero** string construction cost. The `CodexBarLogger` implementation, verified in [`TestsLinux/CodexBarLoggingPerformanceTests.swift`](https://github.com/steipete/CodexBar/blob/main/TestsLinux/CodexBarLoggingPerformanceTests.swift), only interpolates messages when the configured minimum level permits output.

```swift
let logger = CodexBarLogger(minimumLevel: .info) { _, message, _ in
    print(message)               // only called for `info` or higher
}
logger.debug(expensiveMessage()) // no string interpolation performed

```

This pattern prevents debug strings from impacting release build performance or battery life during normal operation.

## Asynchronous Non-Blocking Refresh Loop

The `UsageStore.startTimer()` method spawns a lightweight Swift `Task` that sleeps for the computed `Duration` before refreshing usage data. Because the `AdaptiveRefreshPolicy` computation is pure and executes in constant time, the refresh loop adds only network I/O latency (typically **< 200 ms**) without blocking the main thread.

The entry point in [`Sources/CodexBar/TerminalApp.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/TerminalApp.swift) ensures all performance hooks—including the GPU selection view and adaptive timer—are active before the status item appears, guaranteeing consistent behavior from first launch.

## Summary

- **Deterministic scheduling**: The `AdaptiveRefreshPolicy` computes delays in O(1) time using only the `Input` struct, enabling rapid reactions to thermal and power state changes.
- **GPU layer optimization**: `GPUSelectionHostingView` reduces selection toggles from 3–10 ms to 0.05 ms by bypassing SwiftUI layout passes.
- **Efficient file I/O**: The JSONL scanner achieves 30 MB s⁻¹ throughput with bounded memory usage via front-buffering and 256 KB line limits.
- **Lazy evaluation**: Log messages are only constructed when the logger's level permits, eliminating runtime overhead for disabled verbosity levels.
- **Cooperative multitasking**: The refresh loop uses Swift concurrency to perform network requests without blocking UI updates, keeping latency sub-10 ms.

## Frequently Asked Questions

### How does CodexBar adapt to low power mode and thermal constraints?

When `ProcessInfo.processInfo.isLowPowerModeEnabled` returns true or the thermal state indicates throttling, the `AdaptiveRefreshPolicy` returns a 30-minute delay instead of the standard interval. This decision logic resides in [`Sources/CodexBar/AdaptiveRefreshPolicy.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/AdaptiveRefreshPolicy.swift) and executes in constant time, allowing the application to respect system constraints without complex state machines.

### Why is scrolling through usage history smoother in CodexBar than in standard SwiftUI lists?

Standard SwiftUI list selection triggers a full view re-render costing 3–10 ms per toggle. CodexBar's `GPUSelectionHostingView` moves the highlight into a Core Animation layer property, reducing the operation to approximately 0.05 ms. This implementation in [`Sources/CodexBar/MenuCardGPUSelectionView.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/MenuCardGPUSelectionView.swift) maintains 60 fps scrolling even with extensive usage datasets.

### How fast can CodexBar process large usage history files?

The `CostUsageJsonl.scan` method processes JSONL files at approximately **30 MB s⁻¹**, achieving a 2× speedup over previous implementations according to benchmarks in [`Tests/CodexBarTests/CostUsageJsonlShapeBenchmarkTests.swift`](https://github.com/steipete/CodexBar/blob/main/Tests/CodexBarTests/CostUsageJsonlShapeBenchmarkTests.swift). The scanner handles lines up to 256 KB using a fixed-size front buffer to minimize heap allocations during parsing.

### Does enabling debug logging slow down CodexBar?

No. The logging system uses lazy evaluation patterns verified in [`TestsLinux/CodexBarLoggingPerformanceTests.swift`](https://github.com/steipete/CodexBar/blob/main/TestsLinux/CodexBarLoggingPerformanceTests.swift). When the minimum level is set to `.info` or higher, calls to `logger.debug()` perform zero string interpolation and incur no runtime cost, ensuring release builds maintain optimal performance.