# Keybindings `prefix ?` opens the in-app help with every key and glyph. This document lists the keys and describes what the help does not show: how the nav is placed and walked, what the longer commands do, the prefix hint, popups, toasts, the mouse, and automation. ## Everyday Keys The nav takes these keys while it holds focus: | Key | Action | | ------------------------ | ------------------------------------------------------------------------ | | `↑` / `↓` (or `k` / `j`) | move one card (wraps at both ends) | | `←` / `→` (or `h` / `l`) | previous / next `machine/mux` host section, the machine cards counting as one | | `Home` / `End` | jump to the first / last card | | `PageUp` / `PageDown` | jump ten cards | | `Enter` | move focus into the selected session's terminal view | | `prefix 1`-`prefix 9` | jump to card number (keep typing for 10+) | | `prefix n` | new session on the selected host | | `prefix /` | filter cards (fuzzy) | | `prefix r` | rescan this machine: the selected card's machine and its hosts | | `prefix R` | rescan all machines: refresh which machines exist, and every host's sessions | | `prefix L` | log out of this machine (an SSH machine) | xmux has its own prefix, like tmux's `set -g prefix`. The default is `Ctrl-g`, and `[ui] prefix` replaces it. A chord is the prefix followed by one key: | Chord | Action | | ------------ | ------------------------------------------------------- | | `prefix q` | quit xmux | | `prefix ?` | help and glyphs (type to search) | | `prefix m` | message history of results and events | | `prefix Tab` | toggle focus between the nav and the terminal view | | `prefix p` | place nav on the next side of the view | Pressing the prefix opens a box beside the prefix hint that lists every key it unlocks. A click on a card selects it, and a click on the terminal view focuses it. ## The Prefix The prefix is read only from `[ui] prefix` in `~/.config/xmux/config.toml`, with no environment-variable override. It accepts `C-` (for example `C-g`, `C-b`, `C-a`) and `C-Space`, and anything unrecognised falls back to `C-g`. The prefix is a single control byte, so it never collides with typed text, and a prefix pasted as data (bracketed paste) passes through untouched. A mux that binds the same key reaches that bind through a doubled prefix: the second press sends one literal prefix to the session, as tmux's `send-prefix` does. The default `C-g` is zellij's lock-mode key and a common dvtm MOD key, so with either one `C-g C-g` does what `C-g` does outside xmux. Setting `[ui] prefix` to a key the mux leaves free removes the collision. ## Other Keys | Key | Action | |---|---| | `Ctrl-↑` / `Ctrl-↓` | move up a level (session, host, machine) / back down to the child | | `prefix i` (bare `i` in the nav) | select the current host and show its screen | | `prefix r` | rescan this machine: the selected card's machine alone | | `prefix h` | open the table of machine problems | | `prefix :` | open the command palette | | `prefix t` | toggle auto-hide-nav | | `prefix Ctrl-←` / `prefix Ctrl-→` | move a side nav's nav border, then bare `Ctrl-←` / `Ctrl-→` keep resizing until another key | | `prefix Ctrl-↑` / `prefix Ctrl-↓` | move a horizontal nav's nav border, then bare `Ctrl-↑` / `Ctrl-↓` keep resizing until another key | | the prefix arrow pair facing the terminal | focus the terminal view | | the other prefix arrow pair | focus the nav | | `prefix prefix` | send one literal prefix byte to the focused pane | | `d` on an unreachable screen | unfold the full failure diagnostic | When the terminal view has focus, every key that is not a prefix chord reaches the session's active pane unchanged. A paste reaches it as one paste, bracketed only when the pane's program asked for bracketed paste. Pasted text never acts as the prefix or a key: a text field takes it without its line breaks, and over the nav it is dropped. A pane's program that asks for focus reports hears that it lost the focus when xmux's window, the nav, or a popup takes it, and that it gained the focus when the terminal view has it back. A program using the kitty keyboard protocol gets the keys it tells apart, such as Shift+Enter, when the terminal running xmux has the protocol too. ## Nav Placement The nav rides on one of four sides of the terminal view: a left or right column, or a top or bottom horizontal nav, or floats as a box over the terminal's empty space. `[ui] nav-position` (`left`, `top`, `right`, `bottom`, or `floating`; an unknown word falls back to `left`) names the default, and `prefix p` pins the next side clockwise in `~/.xmux/nav_position`. The cycle unpins at `floating`, the last position: the default applies again, and the next step re-pins from it. The nav never moves on its own. The floating nav is a box over the full-screen terminal: as wide as the nav width the user set, as tall as the card list it shows plus its border, with the prefix hint on its top border's left. It moves in real time to the topmost area the box fits whole, its right border never more than five cells from the window's right wall; when no area fits the box it sits at the top of the widest blank area. Dragging it from anywhere on the box moves it anywhere in the window, the way the prefix key list and a modal popup drag. A drop holds the position for ten seconds, then the position is forgotten and the scan resumes. While the nav view holds the focus or the prefix is armed the box docks: it behaves exactly as a right nav does, the terminal view keeping the remainder, and the focus's return to the terminal view or the chord's end undocks it. A click on the box routes as a nav click: a click on a card selects and executes it at once, whatever the focus, and a click on the box's empty area focuses the nav, which docks it. The layout inside the nav is identical at every side: a right column is the same list as a left one, and a bottom horizontal nav is the same down-then-right flow as a top one, a whole section per column. A horizontal nav column that continues a split section starts with session cards on its top row; the machine/host title appears only where the section starts. A horizontal nav one row tall runs titles and cards along its row and scrolls sideways. The prefix arrow pair facing the terminal's side focuses the terminal: `prefix →` and `prefix ↓` with the nav on the left or above, `prefix ←` and `prefix ↑` with it on the right or below. The resize keys move the nav border the way they point, so the nav grows on a left or top nav and shrinks on a right or bottom one. An expanded side nav is never narrower than a card's indent, a two-digit number, and eight cells of name; a horizontal nav is at least one row. A nav that would leave the terminal view smaller than 24 columns by 4 rows, the size xmux draws in at all, hides the way auto-hide hides it whenever the terminal view holds the focus, whatever auto-hide is set to. In a small window the view the user works in then has the whole window: focusing the nav or pressing the prefix brings the nav back. Moving the focus from a session card into the terminal view leaves the run of machine and host cards without sessions off the nav, so the nav lists only the sessions. The run shows again while the nav holds the focus, while a card of it is selected, and while the prefix is armed, so a `prefix ` jump can see the numbers of those cards. The card numbers and the selection are the same whether the run shows. ## Walking the Nav The nav is a list of numbered cards in sections, not a tree. `←`/`→` step one section: a host with sessions, entered at its first session, or the whole run of machine cards at once, entered at its first card, so a run of idle machines is one stop rather than a long walk. Both steps wrap, and neither depends on where a card sits on screen, so they mean the same thing in a column and in a horizontal nav. The card step never stops on a section title, and a title takes no number. The hierarchy of sessions, hosts, and machines is reached three ways: `Ctrl-↑`/`Ctrl-↓`, the two parts of a section title, and the links on a machine's or a host's screen. A host is selected on the `{mux}` part of its title, or on its card when it has no sessions; a machine on the `{machine}` part, or on its card when none of its hosts connected. `Ctrl-↓` returns to the child the walk came from, else the first host by name or the first session in card order. From a title part, `↑`/`↓` go to the adjacent card and `←`/`→` to the adjacent section. A bare `Ctrl-↑`/`Ctrl-↓` right after `prefix Ctrl-↑`/`prefix Ctrl-↓` still resizes the horizontal nav. The terminal view shows a machine screen for a machine and a host screen for one mux on it. Each reads from the top as its level and path, such as `machine db-01` or `host db-01/tmux`, then its status, then the level below as links, then its actions. A machine screen states how the machine is reached and logged in to and links each of its hosts whose mux is confirmed, and none while no mux is; a host screen states how many sessions it has (`no sessions`, `1 session`, `2 sessions`) and how they stay current and links each of its sessions, and the machine half of its path links to its machine. Every action a screen offers, such as `prefix n start a new session`, is a link written beside the key that runs it, and a failure screen's actions are links too. While the terminal view shows either screen, `↑`/`↓` (and `Tab`) step through its links and `Enter` opens the selected link or runs the selected action exactly as its key does. The links are walked in one order: the level below, then the actions, then, on a host screen, the machine link as the last stop. The steps cycle: a step past the last link returns to the first, and a step before the first returns to the last. A host screen starts on its first session (on its machine link while it has none) and a machine screen on its first host. Opening a link one level up selects the link back to the screen just left. While a machine screen shows the login pane, the pane takes those keys and its links answer only a click. A screen too short for its selected link or the pane's focused stop scrolls just far enough to show it on its last row. At launch the terminal view shows the landing screen in place of a session: how many machines the scan has reached, and every nav card under its number as a `machine/mux/session` path. While a newer release is recorded, an `update` row above the list names it and `xmux update`. The landing list and the nav share one selection, which only highlights there. The first execution (`Enter`, a click on a nav card or a landing card, a landed `prefix ` jump, or a ctl `switch`) closes the landing screen for the rest of the run, opens the chosen card, and focuses the terminal view. ## Commands `prefix n` starts a session on the host of the selected card, a host's card or a session card alike, and is refused under an unreachable machine or host. An empty name is assigned by the mux where it names its own sessions, otherwise by xmux as an `-` no session on that host holds. `prefix r` asks the selected card's machine again and nothing else: its reachability probe, then every host it serves. Its cards keep their sessions and numbers meanwhile, and it reports in one toast titled `rescan machine `. It is refused while that machine is still scanning and while another re-scan has not reported; a `prefix R` pressed meanwhile takes over. `prefix L` asks for `logout` typed in full; `Enter` on any other word states so beside the field and leaves the confirm open with the field empty. It removes the lines of the machine's key files that hold this PC's public key and carry the `xmux-registered` mark. A matching line without the mark opens a second confirmation, where `remove` typed in full removes it too, any other word is stated beside the field the same way, and `Esc` keeps it. The ssh config stanza a login saved for the machine goes next. Any other ssh config `Host` entry naming the machine is listed in that same second confirmation, and `remove` takes the machine off it too: an entry naming only this machine goes, and an entry naming others too keeps them. The held password and the connections are cleared after that; a machine that cannot be reached or a removal that fails still logs out, with a toast saying what remains and why. `prefix ` opens the jump popup holding the digit, so a number past 9 is typed out (`prefix 1` then `2` lands on 12). The selection follows the number while it names a card and stays put while it does not; `prefix 0` therefore moves nothing, and a leading zero is only a spelling. `Enter` closes the popup on a card's number and otherwise states in the popup that no card carries it, with the range in its top border; `Esc` returns to where the jump started. ## Prefix Hint The prefix hint is a chip on the nav's start, at the card flow's beginning: a vertical nav carries it on its own first row, aligned against the nav border, and a horizontal nav writes it at the leftmost cell of its nav border row. A vertical nav's list that overflows thickens the stretch of the nav border beside the cards on screen to `┃`; a horizontal nav writes `‹ 5` and `7 ›` on its nav border row, counting the cards scrolled off each side. Pressing the prefix opens the key list from the prefix hint toward the terminal view, floating over it without moving a card. Its bottom border carries the xmux version, followed by a newer release and `xmux update` while one is recorded. A terminal view too narrow beside a side column lends the box the window's whole width. When the keys do not fit, the box shortens every description, then gives up the keys needed least behind `+N more`, never the jump, help, or quit keys. The box closes when the function the prefix started ends: at once for most keys, when Enter or Esc closes an input, or when a key other than a resize key ends a resize, which then acts as it would have. While a resize lasts, the box is titled `resize`, lists only the resize keys, and names on its bottom border that any other key ends it. A focus switch or any mouse action outside the box cancels the prefix; dragging the box moves it. A held prefix sends one literal per repeat and blinks the box, because a terminal sends no key-up. The prefix hint states the armed prefix alone. What a key did, or why it did nothing, is a toast. The active filter paints its match cell by cell in the warning background on the cards it matches, and a rescan opened by `prefix r` or `prefix R` states its `scanning hosts n/m…` progress in a box beside the prefix hint. With the nav auto-hidden, a prefix interaction brings the nav back until it ends, and the key list and the rescan box open over the window's bottom left. ## Popups Every popup opens where the key list opens, at the same place each time. Dragging a popup moves only that popup, and only until it closes. Its rows wrap to its width rather than being cut, and only a text field stays on one row. In a popup with items to pick, the arrows move its selection, the pointer marks an item without moving that selection, and a click executes the item as `Enter` would. A popup that cannot accept what was typed in it says so beside its field in the error colour, led by `✗`, until the next key, and stays open for the correction; it raises no toast. - **Help** (`prefix ?`): typing searches it, ignoring case; `Backspace` shortens the query and `Ctrl-U` clears it. A row of tabs names the sections: `←`/`→` or a click scrolls to one, and a hovered tab shows its section until the pointer leaves the tab row. `↑`/`↓`, `PgUp`/`PgDn`, and `Home`/`End` scroll. `Esc` or `prefix ?` closes it. - **History** (`prefix m`): newest first, with how long ago each record happened. Opening it takes every toast down. `q`, `Esc`, or `prefix m` closes it. - **Machine problems** (`prefix h`): `Enter` or a click selects the machine's card, filtering to its name when it has no card, and focuses its login pane when it needs a login. - **Filter** (`prefix /`): the list re-filters as you type, and the selection moves to the nearest visible card related to its card when that card is hidden. `Enter` keeps the filter, `Esc` restores the one the popup opened with, and `Esc` in the nav clears an applied filter. - **Logout** (`prefix L`): states the machine it logs out of, whichever of its cards is selected, the observed SSH login, what happens to a held password, to this PC's key, and to the ssh config entry xmux saved, and the machine whose connections close. Typing `logout` and `Enter` confirms it, and `Esc` cancels. When the window is too short for these rows, `↑`/`↓` and `PgUp`/`PgDn` scroll them above the field, and the key removal confirm that can follow scrolls the same way. A terminal smaller than 24 columns by 4 rows shows the required and current size in place of the split view. ## Toasts The result of an action you took floats as a toast in the terminal view's top-right corner, at most 40% of the window wide, up to three at once, each stacked below the one before. A refused action is a result too: its toast is a warning titled by the action, saying why nothing happened. Every toast, a warning (`▲`) or a failure (`✗`) included, leaves after five seconds, with the time left drawn on its bottom border. Something nobody asked about, such as a machine that stops answering, goes to the history only. `[ui] notifications = false` turns toasts off; the history still records every result. ## Mouse | Gesture | Action | |---|---| | left-click a card or title part | open it: select it and focus the terminal view | | point at a card or title part | preview it in the terminal view without moving the selection | | left-click a screen link | open the screen it names, or run the action it names as its key does | | point at or left-click a landing card | mark it, or open it as `Enter` does, from either focus | | left-click a view | focus that view | | left-click `‹ 5` or `7 ›` | select the nearest card scrolled off that side | | wheel over the nav | move the selection | | drag the nav border | resize the nav, clamping it at its minimum | | drag the key list or a popup | move it | | left-click a popup item | execute it, as `Enter` would | | left-click a toast | dismiss it | There is no context menu. While the terminal view is focused, mouse events over it reach the pane, which needs the mux's own mouse mode to use them. The pane gets only the events its program's mouse mode asks for, in the form it asked for, and a drag that starts over the terminal view keeps reaching it past the view's edge until the button is released. ## Automation A running instance listens on `ctl-.sock`. Its verbs are `ping`, `status`, `dump`, `rescan`, `switch `, `focus `, `width ` (a signed column delta), `toggle-auto-hide`, `quit`, and `new-session [name]`. There are no kill, rename, or window verbs, because the mux owns editing a session. ``` xmux instances xmux send amber-otter switch prod api xmux send am focus terminal # any unambiguous name prefix works xmux send - dump # `-` when exactly one is running printf 'switch prod api\nfocus terminal\n' | xmux send amber-otter ``` `--name` takes lowercase letters, digits, and `-`, up to 32 characters. With no command, `send` reads commands from stdin, one per line. A refused command exits non-zero, and a `switch` to a host or session the inventory does not list replies `err:` naming the missing half. The `raw:` namespace (`raw:key`, `raw:keys`, `raw:text`) injects keystrokes or bytes and is not part of the supported surface.