# cmux Keyboard Shortcuts for Pane Navigation: Complete Guide to Focus Commands

> Master cmux keyboard shortcuts for pane navigation. Learn to use ⌘⌥←, ⌘⌥→, ⌘⌥↑, and ⌘⌥↓ to effortlessly switch focus between split panes with this comprehensive guide.

- Repository: [manaflow-ai/cmux](https://github.com/manaflow-ai/cmux)
- Tags: how-to-guide
- Published: 2026-03-29

---

**cmux provides four directional keyboard shortcuts—⌘⌥←, ⌘⌥→, ⌘⌥↑, and ⌘⌥↓—to instantly move focus between adjacent split panes**, hard-wired in [`KeyboardShortcutSettings.swift`](https://github.com/manaflow-ai/cmux/blob/main/KeyboardShortcutSettings.swift) and routed through the Bonsplit controller.

The `manaflow-ai/cmux` terminal multiplexer for macOS streamlines multi-pane workflows with intuitive **cmux keyboard shortcuts** for navigation. These shortcuts are defined centrally in [`Sources/KeyboardShortcutSettings.swift`](https://github.com/manaflow-ai/cmux/blob/main/Sources/KeyboardShortcutSettings.swift) and persist via user defaults under specific keys. Understanding the default bindings and customization API allows developers to optimize their terminal layout management.

## Default cmux Pane Navigation Shortcuts

The application ships with four built-in actions for directional pane focus. These are declared in the `Action` enum at lines 34‑38 of [`KeyboardShortcutSettings.swift`](https://github.com/manaflow-ai/cmux/blob/main/KeyboardShortcutSettings.swift) and bound to specific key combinations via the `defaultShortcut` property at lines 156‑163.

### Directional Focus Commands

- **Focus Pane Left**: `⌘⌥←` (Command + Option + Left Arrow) — Mapped to `Action.focusLeft`
- **Focus Pane Right**: `⌘⌥→` (Command + Option + Right Arrow) — Mapped to `Action.focusRight`
- **Focus Pane Up**: `⌘⌥↑` (Command + Option + Up Arrow) — Mapped to `Action.focusUp`
- **Focus Pane Down**: `⌘⌥↓` (Command + Option + Down Arrow) — Mapped to `Action.focusDown`

Each shortcut is stored in user defaults under the keys `shortcut.focusLeft`, `shortcut.focusRight`, `shortcut.focusUp`, and `shortcut.focusDown`. The static constants `focusLeftKey`, `focusRightKey`, `focusUpKey`, and `focusDownKey` (defined at lines 286‑290) provide programmatic access to these storage keys for UI reset and clearing operations.

## How cmux Shortcut Routing Works

The pane navigation system follows a declarative pipeline from key press to focus change. When a user invokes a shortcut, the system matches the keystroke to a `StoredShortcut` instance, resolves the corresponding `Action` enum case, and routes the command through the workspace hierarchy.

1. **Definition**: The `KeyboardShortcutSettings.Action` enum declares the four navigation actions (`focusLeft`, `focusRight`, `focusUp`, `focusDown`).
2. **Binding**: `defaultShortcut` supplies a `StoredShortcut` initialized with the appropriate arrow key and modifiers (`command: true, option: true`).
3. **Persistence**: Shortcuts serialize to user defaults under the `shortcut.focus*` keys.
4. **Execution**: `AppDelegate` captures the shortcut event and forwards it to `workspace.bonsplitController.focusPane(paneId)`, which performs the actual focus shift in [`WorkspaceContentView.swift`](https://github.com/manaflow-ai/cmux/blob/main/WorkspaceContentView.swift).

The `BonsplitController` handles the spatial logic for determining which `paneId` resides in the requested direction, ensuring focus jumps to the correct adjacent split.

## Customizing cmux Keyboard Shortcuts

Developers can override default bindings programmatically using the public API exposed in [`KeyboardShortcutSettings.swift`](https://github.com/manaflow-ai/cmux/blob/main/KeyboardShortcutSettings.swift). The `StoredShortcut` struct encapsulates the key code and modifier flags.

```swift
// Change "Focus Left" to ⌘⌥H
let newShortcut = StoredShortcut(
    key: "h",
    command: true,
    shift: false,
    option: true,
    control: false
)
KeyboardShortcutSettings.setShortcut(newShortcut, for: .focusLeft)

```

After execution, the UI updates immediately and the underlying user default for `shortcut.focusLeft` persists the new binding. To retrieve the current binding for display in help overlays:

```swift
let current = KeyboardShortcutSettings.focusLeftShortcut()
print("Current focus-left shortcut: \(current.displayString)")
// Output: "⌘⌥H" (if customized) or "⌘⌥←" (default)

```

## Programmatic Pane Navigation via Socket Commands

External scripts and CLI tools can trigger pane focus changes by sending socket commands to the running cmux instance. The command strings map directly to the `Action` enum cases.

```swift
// Send focus command via socket
let command = "focus_right"
socket.send(command)  // Triggers Action.focusRight internally

```

Available socket commands correspond exactly to the directional actions:
- `focus_left`
- `focus_right`
- `focus_up`
- `focus_down`

These strings are interpreted by cmux’s CLI layer and routed to the same `BonsplitController.focusPane(paneId)` method invoked by physical keyboard shortcuts.

## Summary

- **cmux** provides four default directional shortcuts (`⌘⌥←→↑↓`) for pane navigation, defined in [`KeyboardShortcutSettings.swift`](https://github.com/manaflow-ai/cmux/blob/main/KeyboardShortcutSettings.swift) lines 34‑38 and 156‑163.
- Shortcuts persist via user defaults under keys like `shortcut.focusLeft`, referenced by static constants at lines 286‑290.
- The routing chain flows from `AppDelegate` to `workspace.bonsplitController.focusPane(paneId)` in [`WorkspaceContentView.swift`](https://github.com/manaflow-ai/cmux/blob/main/WorkspaceContentView.swift).
- Developers can customize bindings via `KeyboardShortcutSettings.setShortcut(_:for:)` using `StoredShortcut` objects.
- Socket commands (`focus_left`, `focus_right`, etc.) enable external automation of pane focus.

## Frequently Asked Questions

### What are the default cmux keyboard shortcuts for pane navigation?

The defaults are **⌘⌥←** (left), **⌘⌥→** (right), **⌘⌥↑** (up), and **⌘⌥↓** (down). These bindings are hard-coded in [`KeyboardShortcutSettings.swift`](https://github.com/manaflow-ai/cmux/blob/main/KeyboardShortcutSettings.swift) at lines 156‑163 as `StoredShortcut` instances with Command and Option modifiers.

### How do I change the default pane navigation shortcuts in cmux?

Use the `KeyboardShortcutSettings.setShortcut(_:for:)` API, passing a `StoredShortcut` object with your desired key and modifier flags. This updates both the active binding and the user default entry (e.g., `shortcut.focusLeft`) immediately.

### Can I trigger pane navigation programmatically in cmux?

Yes. Send socket commands `focus_left`, `focus_right`, `focus_up`, or `focus_down` to the cmux instance. The CLI interprets these strings and routes them to `BonsplitController.focusPane(paneId)`, executing the same logic as physical key presses.

### Where are cmux keyboard shortcuts stored?

Shortcuts serialize to macOS user defaults under keys defined by `KeyboardShortcutSettings.focusLeftKey` and its directional counterparts (lines 286‑290). The format uses the `StoredShortcut` codable structure, allowing persistence across app launches.