CodexBar Performance: How the macOS Menu Bar Utility Achieves Sub-10ms UI Response and Adaptive Refresh

CodexBar delivers sub-10 millisecond UI updates and power-aware background processing through a three-layer architecture that combines O(1) scheduling decisions, Core Animation GPU acceleration, and zero-allocation JSONL scanning capable of 30 MB/s throughput.

CodexBar is a macOS menu bar utility developed by steipete that monitors AI usage data while maintaining strict performance budgets for battery-powered devices. Its architecture demonstrates how Swift applications can minimize CPU overhead and thermal impact through pure-function scheduling, layer-based rendering optimizations, and lazy evaluation patterns. This analysis examines the specific implementation details in the CodexBar performance model that enable responsive operation during continuous background polling.

Adaptive Refresh Scheduling with O(1) Complexity

The UsageStore drives the application's refresh timer through a deterministic AdaptiveRefreshPolicy that requires no system calls to compute delays. Located in Sources/CodexBar/AdaptiveRefreshPolicy.swift, this pure function examines an Input struct containing system state and user interaction timestamps to return a Decision value.

The logic checks for low-power mode and thermal constraints first:

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 …
}

Because the computation involves only value-type comparisons and arithmetic on the Input struct, the complexity remains O(1) regardless of system load. The UsageStore then implements this in Sources/CodexBar/UsageStore+AdaptiveRefresh.swift by spawning a lightweight Task that sleeps for the computed Duration, ensuring the refresh loop never blocks the main thread.

GPU-Accelerated Menu Card Rendering

Scrolling through long usage lists previously forced full SwiftUI re-renders costing 3–10 ms per highlight toggle. The GPUSelectionHostingView in Sources/CodexBar/MenuCardGPUSelectionView.swift eliminates this bottleneck by moving the selection highlight into a Core Animation layer property change.

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

By manipulating the layer directly rather than triggering SwiftUI's reactive update cycle, the operation completes in approximately 0.05 ms—a 200× improvement over the previous implementation. This approach ensures buttery-smooth scrolling even when displaying hundreds of usage entries.

High-Throughput JSONL Scanning

CodexBar processes historical usage data stored in line-oriented JSONL files using a zero-allocation scanner capable of sustained high throughput. The CostUsageJsonl.scan method in Sources/CodexBarCore/CostUsageJsonl.swift processes up to 256 KB per line using a tiny front-buffer strategy that avoids repeated heap allocations.

Benchmarks in Tests/CodexBarTests/CostUsageJsonlShapeBenchmarkTests.swift demonstrate consistent performance:

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

The implementation achieves ≈ 30 MB/s parsing speed on 30-day history samples when configured with a 32 KB prefix buffer:

let summary = try CostUsageJsonl.scan(
    fileURL,
    offset: 0,
    maxLineBytes: 256 * 1024,
    prefixBytes: 32 * 1024
) { line in
    // process each parsed line here
}
print("Scanned \(summary.lineCount) lines")

This 2× speedup over the baseline front-buffer approach ensures that loading historical data never stalls the UI, even with large usage histories.

Zero-Cost Background Optimizations

Lazy Logging Evaluation

The logging system eliminates string interpolation overhead through level-gated evaluation. As demonstrated in TestsLinux/CodexBarLoggingPerformanceTests.swift, debug-level calls incur zero construction cost when the minimum logger level is set to info:

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

Asynchronous Timer Architecture

The UsageStore.startTimer() method creates a cooperative concurrency context where timer computation remains pure and cheap. By isolating the policy logic from I/O operations, the refresh loop adds only network latency (typically < 200 ms) to the total cycle time, keeping the main thread responsive for user interactions.

Summary

• O(1) scheduling: The AdaptiveRefreshPolicy computes refresh delays in constant time using pure functions, adapting to battery and thermal constraints without system calls.
• Sub-millisecond UI updates: GPU-accelerated selection highlighting in MenuCardGPUSelectionView.swift reduces toggle latency from 3–10 ms to 0.05 ms.
• 30 MB/s data throughput: The JSONL scanner processes usage logs at approximately 30 MB/s with minimal memory allocation, validated by CostUsageJsonlShapeBenchmarkTests.swift.
• Zero-cost logging: The CodexBarLogger prevents expensive string construction when log levels filter out debug messages.
• Non-blocking architecture: The UsageStore timer runs on Swift concurrency tasks, ensuring the main thread never blocks during refresh cycles.

Frequently Asked Questions

How does CodexBar maintain low CPU usage during continuous monitoring?

CodexBar achieves low CPU usage through its AdaptiveRefreshPolicy in Sources/CodexBar/AdaptiveRefresh.swift, which extends polling intervals to 30 minutes when the system enters low-power mode or experiences thermal pressure. The policy computes delays using value-type arithmetic only, avoiding expensive system calls or dynamic dispatch. Additionally, the JSONL scanner uses fixed-size stack buffers rather than heap allocations, reducing memory pressure and garbage collection pauses.

Why does the selection highlighting use Core Animation instead of SwiftUI?

The MenuCardGPUSelectionView.swift implementation uses Core Animation layer properties rather than SwiftUI state changes because modifying view selection through SwiftUI's reactive pipeline triggers a full layout pass costing 3–10 ms. By contrast, updating the CALayer background color property costs approximately 0.05 ms and executes entirely on the GPU compositor thread. This optimization is critical for maintaining 60 FPS scrolling performance when rendering long lists of AI usage entries.

What makes the JSONL scanner faster than standard file parsing?

The scanner in Sources/CodexBarCore/CostUsageJsonl.swift achieves its 2× speedup by limiting line buffering to 256 KB per line with a 32 KB prefix buffer, preventing the parser from allocating new memory for each line during scanning. Unlike generic JSON parsers that decode entire files into intermediate representations, this scanner performs zero-copy iteration over the file's bytes. The benchmark suite confirms sustained throughput of 30.4 MB/s compared to a 14.8 MB/s baseline that used traditional front-buffer allocation patterns.

How does the adaptive timer respond to user interaction?

When the user opens the menu bar, UsageStore captures the timestamp via lastMenuOpenAt and passes it to AdaptiveRefreshPolicy.nextDelay(for:). The policy immediately reduces the next refresh interval to ensure data freshness during active usage, then gradually extends intervals as the system idles. This state machine operates on ProcessInfo signals including isLowPowerModeEnabled and thermalState, requiring no asynchronous IPC calls and completing in nanoseconds on the calling thread.

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