cmux is designed for keyboard-driven workflows. All shortcuts are customizable in Settings → Keyboard Shortcuts.
Workspaces
| Shortcut | Action |
|---|
| ⌘ N | New workspace |
| ⌘ 1–8 | Jump to workspace 1–8 |
| ⌘ 9 | Jump to last workspace |
| ⌃ ⌘ ] | Next workspace |
| ⌃ ⌘ [ | Previous workspace |
| ⌘ ⇧ W | Close workspace |
| ⌘ ⇧ R | Rename workspace |
| ⌘ B | Toggle sidebar |
Surfaces (tabs within workspace)
| Shortcut | Action |
|---|
| ⌘ T | New surface (terminal) |
| ⌘ ⇧ ] | Next surface |
| ⌘ ⇧ [ | Previous surface |
| ⌃ Tab | Next surface |
| ⌃ ⇧ Tab | Previous surface |
| ⌃ 1–8 | Jump to surface 1–8 |
| ⌃ 9 | Jump to last surface |
| ⌘ W | Close surface |
| ⌘ R | Rename surface |
Split panes
| Shortcut | Action |
|---|
| ⌘ D | Split right (new terminal) |
| ⌘ ⇧ D | Split down (new terminal) |
| ⌥ ⌘ D | Split right (new browser) |
| ⌥ ⌘ ⇧ D | Split down (new browser) |
| ⌥ ⌘ ← | Focus pane left |
| ⌥ ⌘ → | Focus pane right |
| ⌥ ⌘ ↑ | Focus pane up |
| ⌥ ⌘ ↓ | Focus pane down |
| ⌘ ⇧ ↩ | Toggle pane zoom (maximize/restore) |
| ⌘ ⇧ H | Flash focused panel |
Browser
Browser shortcuts follow Safari defaults and are customizable in Settings → Keyboard Shortcuts.
| Shortcut | Action |
|---|
| ⌘ ⇧ L | Open browser in split |
| ⌘ L | Focus address bar |
| ⌘ [ | Back |
| ⌘ ] | Forward |
| ⌘ R | Reload page |
| ⌥ ⌘ I | Toggle Developer Tools |
| ⌥ ⌘ C | Show JavaScript Console |
Notifications
| Shortcut | Action |
|---|
| ⌘ I | Show notifications panel |
| ⌘ ⇧ U | Jump to latest unread notification |
Find
| Shortcut | Action |
|---|
| ⌘ F | Find |
| ⌘ G | Find next |
| ⌘ ⇧ G | Find previous |
| ⌘ ⇧ F | Hide find bar |
| ⌘ E | Use selection for find |
Terminal
| Shortcut | Action |
|---|
| ⌘ K | Clear scrollback |
| ⌘ C | Copy (with selection) |
| ⌘ V | Paste |
| ⌘ + | Increase font size |
| ⌘ - | Decrease font size |
| ⌘ 0 | Reset font size |
Window
| Shortcut | Action |
|---|
| ⌘ ⇧ N | New window |
| ⌘ ⇧ P | Command palette |
| ⌘ O | Open folder |
| ⌘ , | Settings |
| ⌘ ⇧ , | Reload configuration |
| ⌘ Q | Quit |
Customizing shortcuts
Change any shortcut in Settings → Keyboard Shortcuts:
- Open Settings (⌘ ,)
- Navigate to Keyboard Shortcuts
- Click the shortcut button next to the action you want to change
- Press your desired key combination
- Press Esc to cancel or click away to save
Keyboard shortcuts require at least one modifier key (Command, Option, Shift, or Control). Plain letter keys without modifiers are not allowed.
Shortcut conflicts
cmux does not validate for conflicts when you customize shortcuts. If you assign the same shortcut to multiple actions:
- The first matching action in the responder chain wins
- Terminal shortcuts generally have lower priority than app-level shortcuts
- You may need to resolve conflicts manually
Resetting shortcuts
Reset shortcuts to defaults:
- Click “Reset All” in Settings → Keyboard Shortcuts to restore all defaults
- Reset individual shortcuts by editing and pressing Backspace
Arrow key modifiers
Arrow key shortcuts use special handling:
- ⌥ ⌘ ← → ↑ ↓: Focus pane directionally
- Plain arrow keys are passed to the terminal for shell navigation
Tab navigation shortcuts
The Tab key (⌃ Tab) cycles through surfaces, not workspaces. Use ⌃ ⌘ ] / [ for workspace navigation.
Recording shortcuts
When recording a custom shortcut:
- Click the shortcut button in Settings
- Press the desired key combination
- Only certain keys are recordable:
- Letters (a-z)
- Numbers (0-9)
- Symbols (via keyCode mapping:
[]{}\;',./ etc.)
- Arrow keys, Tab, Return
- At least one modifier (⌘⌥⇧⌃) is required
Unsupported keys (function keys, media keys, etc.) are not recordable.