What Is Merge Icons Mode in CodexBar? A Deep Dive into Menu Bar Consolidation

Merge icons mode in CodexBar consolidates multiple AI provider status items into a single menu bar icon when enabled, or displays separate icons per provider when disabled.

CodexBar is an open-source macOS application that integrates AI providers into the system menu bar. The merge icons mode setting determines whether enabled providers render as one unified status item with tabs and a switcher, or as individual, independent icons occupying separate menu bar slots.

How Merge Icons Mode Works

The feature operates through a three-layer architecture spanning data persistence, business logic, and UI presentation.

The Settings Layer (SettingsStore+Defaults.swift)

The boolean flag that persists user preference lives in SettingsStore+Defaults.swift. The property synchronizes with UserDefaults and defaults to false when not explicitly set.

// In Sources/CodexBar/SettingsStore+Defaults.swift
var mergeIcons: Bool {
    get { UserDefaults.standard.bool(forKey: "mergeIcons") }
    set { UserDefaults.standard.set(newValue, forKey: "mergeIcons") }
}

This property is referenced throughout the application to determine display behavior.

The Controller Logic (StatusItemController.swift)

The actual decision to merge happens in StatusItemController.swift via the computed property shouldMergeIcons. This property enforces a guard condition: merging only occurs when the user preference is enabled and more than one provider is active.

// In Sources/CodexBar/StatusItemController.swift (lines 83-85)
var shouldMergeIcons: Bool {
    self.settings.mergeIcons && self.store.enabledProvidersForDisplay().count > 1
}

All rendering branches check this property. When shouldMergeIcons evaluates to true, the controller constructs a single NSStatusItem containing a merged menu with provider tabs. When false, the controller iterates through enabled providers and creates distinct status items for each.

Enabling and Disabling Merge Icons

Checking the Current State

Access the current mode programmatically through the controller:

let controller = StatusItemController()
let isMerged = controller.shouldMergeIcons
// Returns true only if mergeIcons is enabled AND multiple providers are active

Programmatic Toggle

Update the setting directly via the settings store:

// Enable merged mode
SettingsStore.shared.mergeIcons = true

// Disable merged mode (separate icons per provider)
SettingsStore.shared.mergeIcons = false

UI Implementation (PreferencesDisplayPane.swift)

The preferences interface exposes this setting as a standard Toggle control bound to the settings store. The UI resides in PreferencesDisplayPane.swift.

// In Sources/CodexBar/PreferencesDisplayPane.swift (lines 19-34)
Toggle(isOn: self.$settings.mergeIcons) {
    Text("Merge icons")
}
.help("Combine multiple provider icons into a single menu bar item")

When the user toggles this switch, the change propagates immediately to UserDefaults, triggering a reactive update in StatusItemController that rebuilds the menu bar items according to the new shouldMergeIcons evaluation.

Summary

• Merge icons mode controls whether CodexBar displays one combined status item or separate icons per AI provider.
• The setting persists in SettingsStore+Defaults.swift as a boolean stored in UserDefaults.
• The controller determines actual merging via shouldMergeIcons in StatusItemController.swift, which requires both the preference flag and multiple enabled providers to return true.
• The UI toggle in PreferencesDisplayPane.swift provides the user-facing control bound to the same property.
• When active, the merged mode renders a unified menu with provider tabs and shared animations; when inactive, each provider receives independent menu bar real estate.

Frequently Asked Questions

What happens if I enable merge icons but only have one provider active?

The controller will not merge. According to the logic in StatusItemController.swift, shouldMergeIcons requires enabledProvidersForDisplay().count > 1 to return true. With only one provider, the app displays a single status item naturally, regardless of the merge setting.

Does merging affect the functionality of individual provider menus?

No. Each provider retains its full menu structure and actions. In merged mode, CodexBar presents these as tabs or sections within the unified status item, preserving all original capabilities while conserving menu bar space.

Where is the merge icons preference stored on disk?

The value persists in standard UserDefaults under the key "mergeIcons", as implemented in SettingsStore+Defaults.swift. This integrates with macOS system preferences and survives app restarts.

Can I switch between merged and separate modes without restarting CodexBar?

Yes. The app observes changes to the settings store reactively. Toggling the switch in PreferencesDisplayPane.swift triggers immediate reconstruction of the status items in StatusItemController, requiring no application restart.

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