# Command Palette, Nucleo Search & Editable Shortcuts

> The power-user command layer: native fuzzy search, usage boosts, settings toggles, shortcut recording, JSON-backed shortcut files, and tests that preserve keyboard routing behavior.

- Repository: manaflow-ai/cmux
- GitHub: https://github.com/manaflow-ai/cmux
- Human wiki: https://grok-wiki.com/public/wiki/manaflow-ai-cmux-5a511656cb1a
- Complete Markdown: https://grok-wiki.com/public/wiki/manaflow-ai-cmux-5a511656cb1a/llms-full.txt

## Source Files

- `Sources/CommandPalette/CommandPaletteSearchOrchestrator.swift`
- `Sources/CommandPalette/CommandPaletteSettingsToggle.swift`
- `Native/CommandPaletteNucleoFFI/src/lib.rs`
- `Sources/KeyboardShortcutSettings.swift`
- `Sources/KeyboardShortcutSettingsFileStore.swift`
- `cmuxTests/CommandPaletteNucleoFFITests.swift`
- `cmuxTests/ShortcutAndCommandPaletteTests.swift`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [Sources/CommandPalette/CommandPaletteSearchOrchestrator.swift](Sources/CommandPalette/CommandPaletteSearchOrchestrator.swift)
- [Sources/CommandPalette/CommandPaletteSettingsToggle.swift](Sources/CommandPalette/CommandPaletteSettingsToggle.swift)
- [Sources/CommandPalette/CommandPaletteNucleoSearch.swift](Sources/CommandPalette/CommandPaletteNucleoSearch.swift)
- [Native/CommandPaletteNucleoFFI/src/lib.rs](Native/CommandPaletteNucleoFFI/src/lib.rs)
- [Sources/KeyboardShortcutSettings.swift](Sources/KeyboardShortcutSettings.swift)
- [Sources/KeyboardShortcutSettingsLookup.swift](Sources/KeyboardShortcutSettingsLookup.swift)
- [Sources/KeyboardShortcutSettingsFileStore.swift](Sources/KeyboardShortcutSettingsFileStore.swift)
- [Sources/KeyboardShortcutSettingsControls.swift](Sources/KeyboardShortcutSettingsControls.swift)
- [Sources/KeyboardShortcutRecorder.swift](Sources/KeyboardShortcutRecorder.swift)
- [cmuxTests/CommandPaletteNucleoFFITests.swift](cmuxTests/CommandPaletteNucleoFFITests.swift)
- [cmuxTests/ShortcutAndCommandPaletteTests.swift](cmuxTests/ShortcutAndCommandPaletteTests.swift)
- [web/data/cmux.schema.json](web/data/cmux.schema.json)
- [docs/configuration.md](docs/configuration.md)
</details>

# Command Palette, Nucleo Search & Editable Shortcuts

This page covers cmux’s power-user command layer: native fuzzy search, settings toggles exposed as commands, usage-based result boosts, shortcut recording, JSON-backed shortcut files, and tests that keep keyboard routing behavior stable.

The implementation is intentionally local and provider-neutral. The search index is a native Rust dylib loaded by the macOS app, shortcut state is stored in UserDefaults or `~/.config/cmux/cmux.json`, and command definitions are app/runtime artifacts rather than model-provider contracts. The supplied Compound Engineering profile shaped this page, but repository code and tests are the source of truth; no `STRATEGY.md` or `docs/solutions/**` source was present in this checkout.

Sources: [Sources/CommandPalette/CommandPaletteSearchOrchestrator.swift:35-46](), [Sources/KeyboardShortcutSettingsFileStore.swift:33-41](), [docs/configuration.md:1-3]()

## Mental Model

```text
User input
  -> Command Palette UI
     -> Swift orchestrator
        -> Nucleo native index when available
        -> Swift search fallback for compatibility and typo handling
     -> Command handlers
        -> app actions
        -> settings toggles
  -> Shortcut layer
     -> recorder UI
     -> UserDefaults shortcut overrides
     -> cmux.json managed overrides
     -> menu/global-hotkey routing
```

The command palette is not just a search box. It is a shared command surface that can execute actions, switch contexts, and toggle settings. The shortcut system feeds the same actions from menus, UI controls, file configuration, and global hotkey registration.

Sources: [Sources/CommandPalette/CommandPaletteSearchOrchestrator.swift:90-134](), [Sources/CommandPalette/CommandPaletteSettingsToggle.swift:768-787](), [Sources/KeyboardShortcutSettingsLookup.swift:3-43]()

## Search Orchestration

`CommandPaletteSearchOrchestrator.resolvedSearchMatches` is the main decision point. It prepares the query, composes usage-history boosts with any additional boost function, prefers the Nucleo index when present, and falls back to the Swift search engine when native search is unavailable.

A subtle feature worth preserving: the orchestrator still invokes a Swift “single-edit” fallback when Nucleo’s top matches might miss a query token that permits a one-character edit. It probes the first 12 Nucleo matches, filters Swift matches that actually used the single-edit word-prefix path, then merges the two result sets by score, rank, localized title, and command id.

Sources: [Sources/CommandPalette/CommandPaletteSearchOrchestrator.swift:47-134](), [Sources/CommandPalette/CommandPaletteSearchOrchestrator.swift:143-186](), [Sources/CommandPalette/CommandPaletteSearchOrchestrator.swift:189-243]()

### Usage Boosts

Usage history is deliberately strongest when the query is empty. The boost combines recency and use count: recent entries can get up to 320 points, repeated use can add up to 180 points, and typed queries receive one third of the total. This makes the blank palette feel personalized without overpowering explicit search intent.

Sources: [Sources/CommandPalette/CommandPaletteSearchOrchestrator.swift:373-387]()

### Preview And Scope Behavior

The orchestrator distinguishes command search from switcher previews. Command scope can search the full corpus through the native index. Switcher preview scope builds a deduplicated candidate subset and runs Swift search over that smaller list. The UI can synchronously seed results when no visible results exist and either a native index is ready or the corpus is small enough.

Sources: [Sources/CommandPalette/CommandPaletteSearchOrchestrator.swift:259-313](), [Sources/CommandPalette/CommandPaletteSearchOrchestrator.swift:338-353]()

## Nucleo Native Search

The Rust FFI is a compact native search engine around `nucleo`. It exposes a C ABI with version `2`, builds an immutable `CmuxNucleoIndex` from a UTF-8 blob plus candidate spans, and stores candidate title, searchable text, line-split search fields, rank, ASCII prefilter masks, and title initials.

Sources: [Native/CommandPaletteNucleoFFI/src/lib.rs:10-37](), [Native/CommandPaletteNucleoFFI/src/lib.rs:89-147](), [Native/CommandPaletteNucleoFFI/src/lib.rs:100-103]()

The search function normalizes whitespace, supports optional per-candidate boosts, returns early on invalid ABI inputs, and limits output by both requested result count and output buffer capacity. Empty queries are ranked by boost and candidate rank; non-empty queries use ASCII masks to skip impossible candidates before scoring.

Sources: [Native/CommandPaletteNucleoFFI/src/lib.rs:204-241](), [Native/CommandPaletteNucleoFFI/src/lib.rs:243-304]()

The scoring model has product taste baked in:

| Behavior | Implementation signal |
| --- | --- |
| Title matches beat generic keyword matches | title score gets a `+2_000` bias |
| Exact short aliases can beat initialisms | exact keyword score for short queries starts at `30_000` |
| Multi-token queries can match across fields | each token is scored independently, with an exact full-line query override |
| Initialisms are first-class | title initials are extracted and scored for 2-8 alphanumeric query chars |
| ASCII candidates are cheap to reject | query and candidate ASCII bitmasks skip impossible matches |

Sources: [Native/CommandPaletteNucleoFFI/src/lib.rs:357-392](), [Native/CommandPaletteNucleoFFI/src/lib.rs:427-483](), [Native/CommandPaletteNucleoFFI/src/lib.rs:485-562](), [Native/CommandPaletteNucleoFFI/src/lib.rs:571-601]()

## Swift Wrapper And Fallback Boundary

`CommandPaletteNucleoSearchLibrary` loads the native dylib with `dlopen`, validates required symbols, checks the FFI version, and supports multiple library locations: `CMUX_NUCLEO_FFI_LIB`, app bundle private frameworks, and local Rust target directories. That keeps local development, CI, and packaged app runs on one ABI contract.

Sources: [Sources/CommandPalette/CommandPaletteNucleoSearch.swift:36-103](), [Sources/CommandPalette/CommandPaletteNucleoSearch.swift:110-157]()

The Swift wrapper serializes corpus entries into the blob/span shape the Rust side expects, sends optional boost arrays only when at least one boost is non-zero, clamps result limits to corpus size, and reconstructs title match indices in Swift for UI highlighting.

Sources: [Sources/CommandPalette/CommandPaletteNucleoSearch.swift:159-199](), [Sources/CommandPalette/CommandPaletteNucleoSearch.swift:278-340]()

```swift
// Sources/CommandPalette/CommandPaletteNucleoSearch.swift
let boost = Int32(clamping: historyBoost(entry.payload, queryIsEmpty))
hasNonZeroBoost = hasNonZeroBoost || boost != 0
values.append(boost)
```

Sources: [Sources/CommandPalette/CommandPaletteNucleoSearch.swift:287-307]()

## Settings Toggles As Commands

Settings toggles are modeled as `CommandPaletteSettingToggleDescriptor` values. Each descriptor owns a command id, settings key, localized title and section title, search keywords, availability, state lookup, and setter. The generated command title flips between “Enable …” and “Disable …”; the subtitle includes the settings section and current on/off state.

Sources: [Sources/CommandPalette/CommandPaletteSettingsToggle.swift:3-40](), [Sources/CommandPalette/CommandPaletteSettingsToggle.swift:62-83]()

`ContentView.commandPaletteSettingsToggleCommandContributions()` turns descriptors into command palette contributions with extra keywords like `settings`, `toggle`, and the settings key. `registerSettingsToggleCommandHandlers` wires those command ids back to descriptor toggles. This is a good extension pattern: adding a setting to the palette is mostly data, not a new bespoke handler.

Sources: [Sources/CommandPalette/CommandPaletteSettingsToggle.swift:86-143](), [Sources/CommandPalette/CommandPaletteSettingsToggle.swift:751-787]()

## Editable Shortcuts

`KeyboardShortcutSettings.Action` is the action catalog for public shortcut bindings. It includes app/window actions, command palette navigation, workspace navigation, pane splits, browser commands, find commands, and panel-specific actions. Each action has a localized label, a default `StoredShortcut`, display formatting, conflict behavior, and special handling for numbered shortcuts.

Sources: [Sources/KeyboardShortcutSettings.swift:60-146](), [Sources/KeyboardShortcutSettings.swift:148-228](), [Sources/KeyboardShortcutSettings.swift:243-397](), [Sources/KeyboardShortcutSettings.swift:403-420]()

Shortcut persistence has two layers:

| Layer | Role |
| --- | --- |
| UserDefaults | Interactive Settings UI writes encoded `StoredShortcut` values per action defaults key. |
| `cmux.json` | Managed file overrides can supersede app settings and disable editing for managed rows. |
| Built-in defaults | Used when neither file nor UserDefaults supplies a binding. |

Sources: [Sources/KeyboardShortcutSettingsLookup.swift:3-23](), [Sources/KeyboardShortcutSettings.swift:765-783](), [Sources/KeyboardShortcutSettingsControls.swift:144-176]()

### Conflict And Validation Rules

The shortcut recorder does not accept everything the user types. It can reject bare keys, conflicts with other actions, macOS-reserved shortcuts, invalid numbered shortcuts, and system-wide hotkeys without a primary modifier. Numbered action families such as selecting workspace or surface by number normalize to `1` for persistence/display while matching the 1-9 family.

Sources: [Sources/KeyboardShortcutSettings.swift:47-58](), [Sources/KeyboardShortcutSettings.swift:438-516](), [Sources/KeyboardShortcutSettings.swift:519-611]()

Conflict detection is context-aware. Chords conflict only when their first strokes conflict and their second strokes conflict; numbered digit actions compare by digit family rather than exact digit. This lets “select workspace 1…9” behave like one shortcut family instead of nine unrelated shortcuts.

Sources: [Sources/KeyboardShortcutSettings.swift:613-732]()

The settings control presents localized validation messages and offers “Swap” only when both the current and conflicting shortcuts can be replaced and neither action is managed by `cmux.json`.

Sources: [Sources/KeyboardShortcutSettingsControls.swift:3-43](), [Sources/KeyboardShortcutSettingsControls.swift:64-141](), [Sources/KeyboardShortcutSettingsControls.swift:225-243]()

## JSON-Backed Shortcut Files

Global app preferences live at `~/.config/cmux/cmux.json`. The store also knows legacy/fallback paths, bootstraps the primary file if missing, parses JSONC, and watches the primary plus fallback files for reloads. When file-managed shortcuts change, it posts the same shortcut settings notification used by the rest of the app.

Sources: [docs/configuration.md:1-3](), [Sources/KeyboardShortcutSettingsFileStore.swift:33-41](), [Sources/KeyboardShortcutSettingsFileStore.swift:76-115](), [Sources/KeyboardShortcutSettingsFileStore.swift:134-165](), [Sources/KeyboardShortcutSettingsFileStore.swift:184-219]()

The schema declares `shortcuts.bindings` as shortcut overrides keyed by cmux action id. Bindings accept a string for a single shortcut, an array for a chord, or null/empty/`none`/`clear`/`unbound`/`disabled` to unbind. The same schema also exposes `app.commandPaletteSearchesAllSurfaces`, which controls switcher breadth.

Sources: [web/data/cmux.schema.json:316-320](), [web/data/cmux.schema.json:887-980]()

The parser accepts both nested `shortcuts.bindings` and direct shortcut keys inside `shortcuts`, resolves action ids through `KeyboardShortcutSettings.Action(rawValue:)`, parses string or string-array bindings, and normalizes settings-file shortcuts without consulting the global recorder conflict path during store initialization.

Sources: [Sources/KeyboardShortcutSettingsFileStore.swift:316-352](), [Sources/KeyboardShortcutSettingsFileStore.swift:853-898]()

Shortcut config strings support modifier aliases (`cmd`, `command`, `⌘`, etc.), named keys, arrow keys, media keys, function keys, and up to two strokes for chords. The stored shortcut type also has explicit chord fields, so JSON-backed chords are first-class rather than encoded as opaque text.

Sources: [Sources/KeyboardShortcutSettings.swift:1910-2008](), [Sources/KeyboardShortcutSettings.swift:2140-2281](), [Sources/KeyboardShortcutSettings.swift:2284-2298]()

## Recorder And Global Hotkey Coordination

Shortcut recording is global state, not just button-local state. `KeyboardShortcutRecorderActivity` tracks the active recorder count, emits change notifications, and can stop all recording. The recorder dispatch path consumes key events only when a recorder is active and the event is a key or system-defined event.

Sources: [Sources/KeyboardShortcutSettings.swift:2301-2347](), [Sources/KeyboardShortcutRecorder.swift:407-450]()

System-wide hotkeys are extra conservative. The controller registers only `.showHideAllWindows` and `.globalSearch`, unregisters hotkeys while shortcut recording is active, validates Carbon hotkey registration, and refreshes registration when UserDefaults, shortcut settings, recorder activity, or keyboard input source changes.

Sources: [Sources/KeyboardShortcutSettings.swift:969-1050](), [Sources/KeyboardShortcutSettings.swift:1052-1105]()

## Tests That Preserve Behavior

The Nucleo tests lock down ranking and search semantics: open-folder queries, multi-token field matching, title initialism preference, exact alias preference, title-over-keyword preference, diacritic matching, empty-query ordering, deep workspace matches, bundled dylib presence, and history boosts before limiting.

Sources: [cmuxTests/CommandPaletteNucleoFFITests.swift:9-80](), [cmuxTests/CommandPaletteNucleoFFITests.swift:82-171](), [cmuxTests/CommandPaletteNucleoFFITests.swift:173-209](), [cmuxTests/CommandPaletteNucleoFFITests.swift:238-252]()

The shortcut and command palette tests protect keyboard routing details that users feel immediately: arrow and Ctrl-N/Ctrl-P navigation, ignoring unsupported modifiers, leaving clipboard/undo/editing shortcuts available while the palette is visible, consuming Escape, blocking terminal/browser focus stealers, restoring browser or terminal focus after command palette flows, and preserving scroll positioning.

Sources: [cmuxTests/ShortcutAndCommandPaletteTests.swift:392-558](), [cmuxTests/ShortcutAndCommandPaletteTests.swift:561-656](), [cmuxTests/ShortcutAndCommandPaletteTests.swift:659-796](), [cmuxTests/ShortcutAndCommandPaletteTests.swift:827-859]()

Shortcut configuration tests also verify that right-sidebar mode shortcuts use default private Control-digit bindings, honor customized app bindings, honor settings-file bindings, and leave untouched mode shortcuts on their defaults when only one binding is overridden.

Sources: [cmuxTests/ShortcutAndCommandPaletteTests.swift:1074-1213]()

## What To Copy Or Productize

The strongest reusable pattern is the layered command contract:

| Pattern | Why it works |
| --- | --- |
| Data-driven setting toggles | New toggles become searchable commands through descriptors. |
| Native search with Swift fallback | Fast common path without giving up compatibility and typo behavior. |
| Usage boosts outside the search engine | Ranking personalization remains portable and testable. |
| File-managed shortcuts | BYOC-friendly: teams can manage shortcuts through plain JSON rather than hosted state. |
| Recorder activity as global routing state | Menu/global shortcuts can stand down while the user is recording a new binding. |

For Grok-Wiki or another documentation/product surface, this should be described as a portable local command layer: file-backed configuration, repository-defined action ids, and native/client-side fuzzy search. Nothing in the architecture requires a specific model provider, hosted connector, or proprietary runtime catalog.

Sources: [Sources/CommandPalette/CommandPaletteSettingsToggle.swift:768-787](), [Sources/CommandPalette/CommandPaletteSearchOrchestrator.swift:47-134](), [Sources/KeyboardShortcutSettingsFileStore.swift:853-898](), [Sources/KeyboardShortcutSettings.swift:2301-2347]()

In summary, cmux’s command palette is a high-leverage command router: Nucleo makes search fast, the Swift orchestrator keeps behavior resilient, setting toggles make preferences discoverable, and the shortcut stack lets users and teams own bindings through either UI recording or `cmux.json`. The tests are not decorative; they encode the interaction contract for search ranking, focus, text editing, and shortcut routing. Sources: [cmuxTests/CommandPaletteNucleoFFITests.swift:254-280](), [cmuxTests/ShortcutAndCommandPaletteTests.swift:392-656]()