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

> Discover Merge Icons Mode in CodexBar to simplify your menu bar. Consolidate AI provider statuses with this deep dive into efficient menu bar consolidation.

- Repository: [Peter Steinberger/CodexBar](https://github.com/steipete/CodexBar)
- Tags: deep-dive
- Published: 2026-07-07

---

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

```swift
// 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`](https://github.com/steipete/CodexBar/blob/main/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.

```swift
// 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:

```swift
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:

```swift
// 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`](https://github.com/steipete/CodexBar/blob/main/PreferencesDisplayPane.swift).

```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`](https://github.com/steipete/CodexBar/blob/main/StatusItemController.swift), which requires both the preference flag and multiple enabled providers to return `true`.
- The UI toggle in [`PreferencesDisplayPane.swift`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/PreferencesDisplayPane.swift) triggers immediate reconstruction of the status items in `StatusItemController`, requiring no application restart.