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

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, 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.

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.

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.

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 processes up to 256 KB per line using a tiny front-buffer, avoiding repeated heap allocations.

Benchmarks in 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, only interpolates messages when the configured minimum level permits output.

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 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 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 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. 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. 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.

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