How to Use CodexBar for Batch Processing Provider Usage Data

CodexBar does not process barcodes; instead, it aggregates AI-coding provider quota usage through automatic batch API calls (e.g., ?batch=1), parsing TRPC-shaped responses into a unified menu-bar interface.

CodexBar is a macOS menu-bar application designed to monitor usage quotas across dozens of AI-coding providers. While the query may suggest barcode processing, the codebase actually implements batch API processing—querying provider endpoints that return batched TRPC responses and normalizing them into UsageSnapshot models for real-time display.

Understanding CodexBar's Batch API Architecture

The batch processing workflow centers on the UsageFetcher.swift orchestrator, which delegates to provider-specific implementations. When a provider supports a batch endpoint (indicated by the query parameter batch=1), CodexBar automatically constructs the request, parses the batched payload, and presents the data in the menu-bar UI.

The architecture follows a pipeline pattern:

• UsageFetcher.swift – Coordinates high-level fetch operations across all enabled providers, normalizing results into the common UsageSnapshot model【https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/UsageFetcher.swift】
• Provider-specific fetchers – Handle the construction of batch URLs and TRPC response decoding
• Fallback CLI strategy – Used when providers lack batch endpoints, configured via ProviderCLIConfig.swift

How Provider Fetchers Implement Batch Processing

Each supported provider implements its own fetcher class that constructs the batch URL and handles provider-specific authentication.

KiloUsageFetcher and the batch=1 Parameter

In KiloUsageFetcher.swift, the batch request is constructed using makeBatchURL, which automatically appends the required query parameter:

// URLQueryItem construction from KiloUsageFetcher.swift
URLQueryItem(name: "batch", value: "1")

The fetcher validates the TRPC response shape—expecting a single-element array containing a result object—and throws descriptive KiloUsageError cases if the structure is unexpected【https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Providers/Kilo/KiloUsageFetcher.swift】.

T3ChatUsageFetcher Implementation

The T3ChatUsageFetcher.swift implements similar batch logic for the T3 Chat provider, constructing requests to endpoints like https://t3.chat/api/trpc/getCustomerData?batch=1&input=ignored and handling the x-trpc-batch header requirements【https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Providers/T3Chat/T3ChatUsageFetcher.swift】.

MistralUsageFetcher Pattern

MistralUsageFetcher.swift follows the same architectural pattern, isolating provider-specific parsing logic while conforming to the batch response protocol【https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Providers/Mistral/MistralUsageFetcher.swift】.

The UsageFetcher Orchestration Layer

The central UsageFetcher class manages the refresh loop across all enabled providers. It reads the pipeline configuration from ProviderDescriptor.swift to determine whether to use batch API fetching or fall back to CLI-based strategies.

When batch mode is active, the fetcher:

1. Invokes loadLatestUsage() on each provider's fetcher
2. Receives normalized UsageSnapshot objects containing credits remaining, reset countdowns, and incident badges
3. Updates the UI layer without storing passwords—re-using existing API keys, OAuth tokens, or CLI sessions

// Example: manually invoke a batch fetch for the Kilo provider
import CodexBarCore

let fetcher = KiloUsageFetcher()
Task {
    do {
        // `loadLatestUsage` calls `makeBatchURL` → ?batch=1 automatically
        let snapshot = try await fetcher.loadLatestUsage()
        print("Kilo credits left: \(snapshot.creditsRemaining)")
    } catch {
        print("Failed to fetch Kilo usage: \(error)")
    }
}

Enabling and Configuring Batch Processing

To utilize CodexBar's batch API processing:

1. Enable the provider in Settings → Providers—the UI automatically selects the batch fetch strategy when available
2. Authenticate using existing credentials (API key, OAuth, or CLI session)—CodexBar never stores passwords independently
3. Run the refresh loop either via the macOS app or the CLI command:

# CLI equivalent – fetch all enabled providers in batch mode

codexbar serve --refresh 15s

For debugging specific batch endpoints manually:

# Direct curl of a provider's batch endpoint

curl "https://t3.chat/api/trpc/getCustomerData?batch=1&input=ignored" \
     -H "x-trpc-batch: true"

Error Handling for Batch Responses

Provider fetchers implement strict validation of batch response shapes. The KiloUsageFetcher defines specific KiloUsageError enums for various failure cases, ensuring that malformed TRPC responses or missing result objects trigger descriptive errors rather than silent failures.

If a provider does not expose a batch endpoint, CodexBar transparently falls back to the KiloCLIFetchStrategy or equivalent, as defined in the provider descriptor's pipeline configuration【https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Providers/ProviderDescriptor.swift】.

Summary

• CodexBar processes batch API calls, not barcodes, to aggregate AI provider usage data
• The UsageFetcher.swift orchestrator delegates to provider-specific implementations like KiloUsageFetcher.swift, T3ChatUsageFetcher.swift, and MistralUsageFetcher.swift
• Batch requests automatically append ?batch=1 via makeBatchURL and parse TRPC-shaped responses
• Providers without batch support fall back to CLI-based strategies configured in ProviderCLIConfig.swift
• The UI displays normalized UsageSnapshot data regardless of whether the source was a batch API, CLI helper, or local file

Frequently Asked Questions

Does CodexBar support barcode scanning or processing?

No. Despite potential naming confusion, CodexBar does not handle barcodes. The application aggregates quota usage statistics from AI-coding providers through HTTP API calls, specifically batch TRPC endpoints that use the batch=1 query parameter.

What is the batch=1 parameter in CodexBar API calls?

The batch=1 parameter indicates a TRPC batch endpoint that returns aggregated data in a specific shape (typically a single-element array containing a result object). CodexBar automatically appends this via URLQueryItem in provider fetchers like KiloUsageFetcher.swift to retrieve usage statistics in a single request.

How does CodexBar handle providers without batch endpoints?

When a provider lacks a batch API, CodexBar falls back to CLI-based fetching strategies. The ProviderDescriptor.swift configuration defines the pipeline for each provider, switching between UsageFetcher implementations and ProviderCLIConfig.swift settings based on capability detection.

Can I manually trigger batch API requests for debugging?

Yes. You can use the codexbar serve CLI command with a refresh interval, or manually curl the endpoints using the same URLs constructed by the fetchers. For example, T3 Chat batch endpoints accept the x-trpc-batch: true header and return JSON arrays containing usage data.

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