How to Enable or Disable Features in CodexBar: Provider Flags and User Preferences

CodexBar uses two distinct mechanisms to control functionality: provider-side feature flags delivered automatically via the Factory API, and user-side menu bar metric preferences stored in SettingsStore and exposed through the Preferences window.

CodexBar is an open-source macOS menu bar application for monitoring AI API usage across providers like OpenAI, Claude, and Gemini. Understanding how to enable or disable features requires navigating both automatic provider capabilities defined in Sources/CodexBarCore/Providers/Factory/FactoryStatusProbe.swift and manual user preferences managed in Sources/CodexBar/SettingsStore+MenuPreferences.swift.

Understanding Provider-Side Feature Flags

Provider-side capabilities are controlled by the FactoryFeatureFlags struct, which the app receives from the Factory API during authentication probing. These flags determine whether optional features—such as token-rate-limit billing or extra-usage balance tracking—are available for your account.

The flags are parsed in FactoryStatusProbe.swift (line 49) within the fetchAuthInfo method:

public struct FactoryFeatureFlags: Codable, Sendable {
    public let flags: [String: Bool]?       // simple on/off toggles
    public let configs: [String: AnyCodable]? // optional configuration values
}

When the client checks for capabilities, it validates specific boolean flags before exposing UI elements. For example, token-rate-limit billing is only displayed when usesTokenRateLimitsBilling evaluates to true:

if let billingLimits = try await self.fetchBillingLimitsIfAvailable(...),
   billingLimits.usesTokenRateLimitsBilling,
   let tokenRateLimits = billingLimits.limits {
    // Build a snapshot that includes rate-limit windows
}

If a flag is missing or set to false, the associated menu item is omitted automatically. No user configuration is required—when the provider toggles the flag on their side, the next fetch cycle surfaces the feature immediately.

To verify which flags are active for your account, open the Developer Console (⌥ ⇧ I) and inspect JSON payloads prefixed with [factory]. The raw featureFlags object appears in these log lines.

Configuring User-Side Menu Bar Metrics

While provider flags control availability, user preferences determine which metrics appear in the macOS menu bar. These settings are persisted in the menuBarMetricPreferencesRaw dictionary within SettingsStore and define which usage bars (primary, secondary, extra-usage, etc.) render for each provider.

The validation logic resides in SettingsStore+MenuPreferences.swift (lines 5‑46). The menuBarMetricPreference(for:) method returns .automatic when a selected metric is unsupported for the specific provider:

// Guard clauses at lines 31-45 return .automatic when the metric is unsupported
func menuBarMetricPreference(for provider: UsageProvider) -> MenuBarMetricPreference {
    // Validation logic ensures compatibility
}

Adjusting Preferences via the UI

To manually enable or disable menu bar features:

1. Click the CodexBar icon in the macOS menu bar.
2. Select Preferences… (or press ⌘,).
3. Navigate to the Menu Bar tab.
4. For each provider (OpenAI, Claude, Gemini, etc.), use the dropdown to select the desired metric:
   • Automatic: Allows CodexBar to select the most appropriate metric at runtime.
   • Primary/Secondary/Tertiary: Forces specific usage tiers.
   • Extra Usage: Displays additional balance tracking (only when provider flags permit).
   • Monthly Plan: Forces Automatic mode (the code explicitly returns .automatic at lines 44‑45 for this option).
5. Close the Preferences window—changes apply instantly and the menu bar refreshes.

Programmatic Access (Advanced)

You can toggle features programmatically by writing to the menuBarMetricPreferencesRaw UserDefaults key. The setMenuBarMetricPreference method (lines 49‑88) enforces provider-specific constraints:

let store = SettingsStore.shared
store.setMenuBarMetricPreference(.primary, for: .openrouter) 
// Enables primary metric for OpenRouter

Note that for balance-only providers like Mistral, the method automatically stores .automatic regardless of the requested preference.

Feature Reference Summary

Feature	Control Method	Source Location
Token-rate-limit billing	Provider flag (usesTokenRateLimitsBilling)	FactoryStatusProbe.swift
Extra-usage balance	Provider flag (extraUsageAllowed)	FactoryStatusProbe.swift
Menu-bar metric display	User preference (menuBarMetricPreferencesRaw)	SettingsStore+MenuPreferences.swift
Metric validation	Automatic fallback to .automatic	SettingsStore+MenuPreferences.swift (lines 31‑45)

Summary

• Provider-side features are controlled by FactoryFeatureFlags in FactoryStatusProbe.swift and update automatically when the Factory API returns new flags.
• User-side features are managed through Preferences → Menu Bar, storing selections in SettingsStore under the menuBarMetricPreferencesRaw key.
• Selecting Automatic in the UI allows CodexBar to determine the best available metric, falling back safely when specific capabilities are unsupported.
• Use the Developer Console (⌥ ⇧ I) and filter for [factory] logs to inspect raw provider feature flags in real time.

Frequently Asked Questions

Why is the Extra Usage metric missing from my menu bar?

The Extra Usage option only appears when the provider returns extraUsageAllowed: true in the FactoryFeatureFlags payload. If the flag is disabled on the provider side, CodexBar automatically hides the metric regardless of your user preferences. Verify availability by checking the [factory] logs in the Developer Console for the featureFlags object.

Can I force-enable a feature that my provider does not support?

No. Provider-side features such as token-rate-limit billing are gated by the usesTokenRateLimitsBilling flag parsed in FactoryStatusProbe.swift. If the provider API does not include this flag, the associated UI elements are not rendered, and user preferences cannot override these constraints.

How do I reset all menu bar preferences to default?

Delete the menuBarMetricPreferencesRaw key from UserDefaults or set all providers to Automatic in the Preferences window. The menuBarMetricPreference(for:) method automatically returns .automatic when a preference is missing or invalid, effectively restoring default behavior.

What is the difference between Automatic and Primary metrics?

Automatic mode lets CodexBar select the most relevant metric at runtime based on provider capabilities and account status. Primary forces the display of the first usage tier (typically standard rate limits). If a provider does not support the Primary metric, the code at lines 31‑45 of SettingsStore+MenuPreferences.swift falls back to Automatic to prevent empty UI states.

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