Keyboard

The default prefix is Control+B. Press the next key within 1.6 seconds.

Common direct shortcuts:

Click mode

Double-tap Option to show keyboard hints over clickable elements in the selected pane. Type a hint to click its element. Click mode works directly in bmux, including page frames, without a browser extension or Accessibility permission.

Choose a pane action before typing its link hint. The pane actions show hints for links only. Click mode only targets web content. It does not place hints over bmux's status bar or dialogs. Use the click-mode action to assign another shortcut or prefix binding.

Pickers support typing to search, Up/Down to select, Enter to confirm, and Escape to clear or close. Open ? or press F1 to see active shortcuts and commands.

In the bookmark editor, press / from a folder row to search folders, use Up/Down and Enter to select one, or create a new folder inside the selected folder.

Command prompt

Press Control+B, then :, or click : in the status bar. Type a command or part of its name. Tab completes the selected result and Enter runs it.

open https://example.com
new-session -s work --profile professional
session personal
new-window -n research
close-system-window
split-window -h --profile bot
pane-left
save-layout development
restore-layout development --confirm
bookmark
bookmarks
history
sessions
profiles
activity
help

Control+R/S moves through command history. Shift+Enter runs the text exactly as entered.

Configuration

Edit ~/.config/bmux/config.yaml, or press Command+,. Changes reload automatically. Omitted bindings keep their defaults. Set a binding to null to disable it.

statusBar: top
showTabCloseButtons: false
clickMode:
  enabled: true
  doubleTapModifier: Option
  hintCharacters: asfghjklqwetyuiopzxvbm
  showInput: true
  fontSize: 12
  opacity: 0.95
  backgroundColor: "#ffcc00"
  textColor: "#000000"
keyboard:
  prefix: Ctrl+B
  prefixTimeoutMs: 1600
  shortcuts:
    Cmd+1: select-window-1
    Cmd+R: reload
    Cmd+Shift+R: hard-reload
    Cmd+L: address
    Cmd+N: new-client
    Cmd+T: new-window
    Cmd+W: close-window
    Cmd+Shift+W: detach
    CmdOrCtrl+F: find
    Cmd+Ctrl+Alt+Shift+W: sessions
    Cmd+,: settings
    Escape: stop
  prefixBindings:
    "1": select-window-1
    ":": command
    "?": help
    c: new-window
    ",": rename-window
    "&": close-window
    "quot;: rename-session
    "(": previous-session
    ")": next-session

Set showTabCloseButtons: true when you want close buttons on the status tabs.

clickMode.doubleTapModifier accepts Option, Command, Control, Shift, Escape, or null. Hint characters must be unique letters or digits and cannot include r, c, d, or n, which select click actions. The action-first link keys f, h, and l are ignored if present in an older hintCharacters setting. Click mode settings reload with the rest of the file.

Configured shortcuts take precedence over website shortcuts and native menu defaults. Multiple shortcuts can use the same action.

To make Command+W close the selected floating pane, while continuing to close the internal window for a tiled pane, use:

keyboard:
  shortcuts:
    Cmd+W: close-pane-or-window

Pane movement actions are pane-left, pane-down, pane-up, and pane-right. Split actions are split-right and split-down. Assign any of them under keyboard.shortcuts or keyboard.prefixBindings.

Page scrolling actions are scroll-up, scroll-down, scroll-half-up, scroll-half-down, scroll-top, and scroll-bottom. A two letter binding such as gg goes under keyboard.sequences. Sequence keys use prefixTimeoutMs for the interval between letters. For Vim style page controls that leave text fields alone:

keyboard:
  shortcuts:
    j: { action: scroll-down, when: pane-not-editing }
    k: { action: scroll-up, when: pane-not-editing }
    d: { action: scroll-half-down, when: pane-not-editing }
    u: { action: scroll-half-up, when: pane-not-editing }
    Shift+G: { action: scroll-bottom, when: pane-not-editing }
    r: { action: reload, when: pane-not-editing }
    Shift+R: { action: hard-reload, when: pane-not-editing }
    /: { action: find, when: pane-not-editing }
  sequences:
    gg: { action: scroll-top, when: pane-not-editing }

Window reordering actions are move-window-left, move-window-right, move-window-first, and move-window-last. Modifier-only shortcuts can distinguish the physical Shift keys with ShiftLeft and ShiftRight; the defaults use Cmd+ShiftRight to move the current window one position right and Cmd+ShiftLeft to move it one position left. Movement wraps to the opposite end at the boundary. The shortcuts run when the Shift key is released and are canceled if another key is pressed while it is held.

BMUX_CONFIG selects another configuration file. Normal instances respect XDG_CONFIG_HOME. Isolated BMUX_DATA_DIR instances use their own config.yaml.

Conditional shortcuts

A shortcut can specify an action and a context. For example, use Command+Z to zoom the active pane while retaining Undo in text fields:

keyboard:
  shortcuts:
    Cmd+Z:
      action: toggle-pane-zoom
      when: pane-not-editing

pane-not-editing requires page focus in the active pane, outside text fields. The URL bar, browser prompts, website inputs, and editable page content retain their normal keyboard behavior. If focus cannot be determined, the shortcut is not intercepted. This includes unknown focusable controls and closed shadow roots. Selecting ordinary page text does not count as focusing a text field.

when: always (or omitting when) preserves global shortcut behavior. Existing string values remain valid, and null disables a binding. Prefix bindings keep their existing behavior. Contexts appear alongside bindings in shortcut help.