Honeymux’s bindable actions are listed below. Bindings live at ~/.config/honeymux/keybindings.json in a { default, overrides } structure, and can also be edited from the Main Menu’s Functions, Agents, and Navigation tabs. Only mainMenu is bound by default; every other action starts unbound so the user can choose mappings that do not collide with their terminal emulator or the applications running inside it.
| Action | Description |
|---|
| Open the ≡ pane border menu on the active pane. |
|
agentLatch
| Toggle review-latched mode on the focused Mux-o-Tron agent; keyboard input routes to that agent’s pane while the latch is held. |
|
agentPermApprove
| Send an approve response to a waiting agent’s pending permission request. |
|
agentPermDeny
| Send a deny response to a waiting agent’s pending permission request. |
|
agentPermDismiss
| Dismiss a waiting agent’s permission request without responding; the agent stays in the unanswered queue. |
|
agentPermGoto
| Switch focus to the pane where the waiting agent is running. |
|
agentReviewGoto
| From the agent review workflow, jump focus to the currently selected agent’s pane. |
|
agentReviewNext
| Step forward through pending agents while the review workflow is active. |
|
agentReviewPrev
| Step back through pending agents while the review workflow is active. |
|
agents
| Open the Agents dialog. |
|
bufferZoom
| Capture the active pane’s scrollback and display it full-screen (Buffer Zoom). |
|
conversations
| Open the Conversations cross-agent history search. |
|
favoriteProfile
| Apply the favorite layout profile directly, skipping the dropdown. Does nothing if no profile is starred. |
|
mainMenu
| Open the Main Menu. The only action bound by default. Pressing the binding a second time from inside the menu forwards the key to the active pane, so an app inside that also uses ctrl+g still receives it. |
|
mobile
| Toggle the mobile-optimized UI layout. |
|
newPaneTab
| Add a new pane tab to the active pane. |
|
nextPaneTab
| Cycle to the next pane (or pane tab, when pane tabs are enabled) in the current window. |
|
nextSession
| Switch to the next tmux session in alphabetical order. |
|
nextWindow
| Switch to the next tmux window in the current session. |
|
notifications
| Open the Notifications review frame. |
|
options
| Open the Options dialog. |
|
prevPaneTab
| Cycle to the previous pane (or pane tab, when pane tabs are enabled) in the current window. |
|
prevSession
| Switch to the previous tmux session in alphabetical order. |
|
prevWindow
| Switch to the previous tmux window in the current session. |
|
profiles
| Open the Profiles dropdown. |
|
quickTerminal
| Toggle the Quick Terminal overlay. |
|
redraw
| Force a full redraw of the Honeymux UI. Useful after an outer-terminal event corrupts the display. |
|
review
| Enter the agent review workflow from the Mux-o-Tron. Within the workflow, the agentReview* actions step through pending agents. |
|
screenshot
| Open the Screenshot capture dialog for the active pane. |
|
sessions
| Open the Sessions dropdown. |
|
| Toggle the Sidebar panel. |
|
| Move keyboard focus into the sidebar for arrow-key navigation. |
|
toolbar
| Toggle the Toolbar. |
|
toolbarFocus
| Move keyboard focus into the toolbar for arrow-key navigation. |
|
zoomAgentsView
| Expand the Agents tree to full terminal width. Whether the binding is tap-to-toggle or must be held down is controlled by zoomAgentsViewStickyKey; hold-mode requires a terminal that supports the kitty keyboard protocol. |
|
zoomServerView
| Expand the tmux server tree view in the sidebar to full terminal width. Sticky vs hold behavior mirrors zoomAgentsView and is controlled by zoomServerViewStickyKey. |
|
The full list of recognized key names:
| Category | Keys |
|---|
| Editing and navigation | homeendpage_uppage_downinsertdeletetabbackspaceescapeenterspaceupdownleftright |
| Function row | f1 through f35 |
| Other functional keys | caps_lockscroll_locknum_lockprint_screenpausemenu |
| Numeric keypad | kp_0kp_1kp_2kp_3kp_4kp_5kp_6kp_7kp_8kp_9kp_decimalkp_dividekp_multiplykp_subtractkp_addkp_equalkp_separatorkp_enterkp_leftkp_rightkp_upkp_downkp_page_upkp_page_downkp_homekp_endkp_insertkp_deletekp_begin |
| Media keys | media_playmedia_pausemedia_play_pausemedia_reversemedia_stopmedia_fast_forwardmedia_rewindmedia_track_nextmedia_track_previousmedia_recordlower_volumeraise_volumemute_volume |
| Modifier-only keys | left_shiftright_shiftleft_ctrlright_ctrlleft_altright_altleft_superright_superleft_hyperright_hyperleft_metaright_metaiso_level3_shiftiso_level5_shift |
A binding is a single string: zero or more modifier prefixes joined with +, ending in a key name. Modifiers are ctrl, alt, and shift, written in that order. Examples: ctrl+g, alt+page_up, ctrl+shift+f5, or just home.
The simplest way to set a binding is from the Main Menu — focus an action, press return to enter capture mode, and press the key combo. Honeymux normalizes whatever the terminal sent into the canonical form shown above and saves it.
Plain printable keys (a, 1, /, etc.) must include at least one modifier — binding a bare letter would shadow normal terminal input, so the capture UI rejects it. Named keys like home or f1 are accepted standalone, since they have no in-band representation that could collide with what the application beneath sees.
Most named keys (home, end, arrows, page up/down, F1–F12, insert, delete) flow through standard terminal sequences and bind on every emulator Honeymux runs in. A handful of capabilities require the Kitty keyboard protocol:
- Modifier-only key bindings (e.g., assigning
right_alt to agentLatch)
- Hold-to-zoom mode for
zoomAgentsView and zoomServerView
- F13 and above
- The keypad, media, and “other functional” keys (
caps_lock, print_screen, etc.) — without the protocol, most terminals send keypad keys as the same sequence as the main keyboard, so kp_enter is indistinguishable from enter
- Reliable disambiguation between
tab and ctrl+i, enter and ctrl+m, escape and ctrl+[
Terminals known to support the protocol include Kitty, Ghostty, WezTerm, foot, Contour, and recent iTerm2 (with the option enabled). On terminals without it, the rest of Honeymux still works — those specific features just aren’t available.
Bare f3 binds on any terminal. Modified F3 (ctrl+f3, shift+f3, etc.) only works when the terminal has the Kitty keyboard protocol’s “report all keys” flag active.1 F1, F2, and F4 are unambiguous and bind on any terminal, modified or not.
A few legacy combinations are the same on the wire on most terminals and get canonicalized to a single name:
ctrl+@, ctrl+space, ctrl+2, and ctrl+` all canonicalize to ctrl+@ on a US layout.- Unless the Kitty keyboard protocol is active,
tab and ctrl+i, enter and ctrl+m, escape and ctrl+[ are the same single byte.
Binding ctrl+@ therefore catches all four of the first group; binding tab (without Kitty protocol) also catches ctrl+i.
On macOS, the bare F-row keys default to hardware and OS-level shortcuts — F1/F2 for display brightness, F3 for Mission Control, F4 for Spotlight or Launchpad, F11 for Show Desktop, and so on — and the system intercepts them before the terminal sees them. Holding fn while pressing an F-key always sends the actual F-key through to honeymux without changing any settings, so fn+f3 works out of the box.
To use the bare F-keys (no fn), visit System Settings → Keyboard → Keyboard Shortcuts and uncheck the entries that own the keys you want.
The fn and cmd keys are not exposed to terminal applications. fn is an OS-level remapper, not a terminal modifier; cmd is reserved by terminal emulators for their own menu shortcuts.
