Keyboard
Preview build
2026-09-21-0ff0f27e2226, published from 0ff0f27e2226. Stable docs remain at /docs/.
Herdr is mouse-native. You can click panes, tabs, workspaces, and agents, drag split borders, and use right-click menus without learning a single keybinding. Keyboard control is optional.
What the prefix is
Section titled “What the prefix is”A terminal multiplexer sits between your terminal and the programs running inside it. Those programs already use most key combinations: ctrl+c interrupts, ctrl+r searches history, editors claim nearly everything else. If Herdr grabbed common keys directly, it would break the programs inside it.
The prefix solves this. Press the prefix key, default ctrl+b, and the next keypress goes to Herdr instead of your terminal. prefix+c means: press ctrl+b, release, then press c. Herdr reserves one key instead of dozens.
Press prefix+? at any time to see every active binding. Press / in the keybind help to filter actions and shortcuts; use Backspace to edit the filter or ctrl+u to clear it.
Learn these five first
Section titled “Learn these five first”| Action | Key |
|---|---|
| New tab | prefix+c |
| Split right / down | prefix+v / prefix+minus |
| Move between panes | prefix+h/j/k/l |
| Workspace navigation | prefix+w |
| Detach, leave everything running | prefix+q |
These cover most daily movement. Everything else can stay on the mouse.
The rest, by task
Section titled “The rest, by task”Panes:
| Action | Key |
|---|---|
| Zoom the focused pane | prefix+z |
| Close pane | prefix+x |
| Swap panes | prefix+shift+h/j/k/l |
| Resize mode | prefix+r |
| Copy mode | prefix+[ |
Tabs:
| Action | Key |
|---|---|
| Next / previous tab | prefix+n / prefix+p |
| Jump to tab 1–9 | prefix+1..9 |
| Rename tab | prefix+shift+t |
| Close tab | prefix+shift+x |
Workspaces and session:
| Action | Key |
|---|---|
| New workspace | prefix+shift+n |
| Rename workspace | prefix+shift+w |
| Close workspace | prefix+shift+d |
| Goto picker | prefix+g |
| Toggle sidebar | prefix+b |
The full keymap and the binding syntax live in the keybinding reference.
The Goto picker (prefix+g) lists each agent or terminal on its own row, grouped by workspace. Split tabs never hide their panes behind another row. Click a row or press Enter to jump directly to it. Press / to search names, agent kinds, tabs, workspaces, branches, or paths; use Up/Down or j/k to move between rows when not typing a search. Left/Right jumps to the first agent or terminal in the previous/next workspace section, without wrapping. While editing a search, Left/Right moves the text cursor instead. Outside search, b/w/i/d filter blocked, working, idle, or done agents, and a shows all terminals again. The selected destination’s location and path appear below the list. When the list overflows, use the mouse wheel, click the scrollbar track, or drag its thumb to scroll without opening a destination.
Editing text fields
Section titled “Editing text fields”Herdr’s naming dialogs, worktree branch fields, filters, and copy-mode search support editing at the cursor. These shortcuts apply to Herdr-owned fields, not to the shell or agent inside a pane.
| Action | Keys |
|---|---|
| Move one character | Left / Right, Ctrl+B / Ctrl+F |
| Move to the beginning / end | Home / End, Ctrl+A / Ctrl+E |
| Move one word | Alt+B / Alt+F |
| Delete the previous character | Backspace, Ctrl+H |
| Delete the next character | Delete, Ctrl+D |
| Cut to the beginning / end | Ctrl+U / Ctrl+K |
| Cut the previous word | Ctrl+W, Alt+Backspace, Ctrl+Backspace |
| Cut the next word | Alt+D |
| Insert the last cut text | Ctrl+Y |
Typing and paste insert at the cursor. Movement and deletion respect Unicode grapheme boundaries, and long values scroll horizontally. Cut text stays within the current field; it does not use the system clipboard. Alt shortcuts require the terminal to report Alt/Meta. Enter and Esc retain the dialog’s confirm and cancel behavior.
Copy mode
Section titled “Copy mode”Press prefix+[ to enter copy mode for the focused pane. Use h/j/k/l, tmux-style w/b/e and big-word W/B/E, {/}, PageUp/PageDown, ctrl+b/ctrl+f, and ctrl+u/ctrl+d to move. Press / or ? for forward or backward literal search, then n or N to repeat in the same or opposite direction. Search is case-insensitive unless the query contains an uppercase letter. Use v or Space to start a selection, y or Enter to copy it, and q or Esc to leave without copying. Esc clears an active selection or search before exiting. Copy mode does not pause the pane process: output remains live, follows at the bottom, and stays pinned when you navigate into history. The configured prefix keeps its normal meaning in copy mode; with the default prefix, ctrl+b enters prefix mode instead of paging up, so use a different prefix if you want ctrl+b for copy-mode page-up. Mouse drag-select copies without entering copy mode at all.
Mouse drag selections and selections started with v, Space, or V remain active during output and redraws, including when part of the selected range is outside the viewport. Copy reads the current text in that range, not a frozen snapshot. Resizing the pane or switching between its normal and alternate screens still clears the selection. Search results and double-click word selections retain their content-change checks.
Change anything
Section titled “Change anything”Every binding is configurable, including the prefix itself:
[keys]prefix = "ctrl+a"Going prefix-free
Section titled “Going prefix-free”You can bind Herdr actions to direct chords that need no prefix at all. The hard part is knowing which chords are safe, because terminals, shells, and desktop environments already own most of the keyboard.
Any chord works as a binding: ctrl+j, alt+k, whatever fits your hands. But a chord has to survive three layers before Herdr sees it: your operating system, your outer terminal (Ghostty, iTerm2, and others ship their own defaults), and the programs running inside the pane. ctrl+j reaches Herdr fine, but shells and editors treat it as enter. alt+k is free on Linux, but macOS composes it into a special character in most terminals. If you pick chords from these families, double-check them against your own terminal and OS shortcuts.
We mapped the default keybindings of Ghostty, iTerm2, Terminal.app, kitty, WezTerm, Alacritty, Warp, Windows Terminal, GNOME Terminal, and Konsole, plus the global shortcuts of GNOME and KDE. One modifier family is almost untouched everywhere: ctrl+alt. Terminals leave it free, it is not affected by the macOS option-key composing behavior that blocks plain alt chords, and it transmits even in terminals without a modern keyboard protocol. It is a safe default, but the choice is yours.
This setup keeps the prefix bindings working and adds direct chords on top:
[keys]focus_pane_left = ["prefix+h", "ctrl+alt+h"]focus_pane_down = ["prefix+j", "ctrl+alt+j"]focus_pane_up = ["prefix+k", "ctrl+alt+k"]focus_pane_right = ["prefix+l", "ctrl+alt+l"]previous_tab = ["prefix+p", "ctrl+alt+["]next_tab = ["prefix+n", "ctrl+alt+]"]new_tab = ["prefix+c", "ctrl+alt+c"]split_vertical = ["prefix+v", "ctrl+alt+d"]split_horizontal = ["prefix+minus", "ctrl+alt+shift+d"]zoom = ["prefix+z", "ctrl+alt+z"]A few ctrl+alt chords are taken elsewhere. Avoid these:
| Chord | Owned by |
|---|---|
ctrl+alt+arrows | GNOME workspace switching, Ghostty and Konsole defaults |
ctrl+alt+t | “Launch terminal” on Ubuntu and Fedora |
ctrl+alt+l / ctrl+alt+a | KDE lock screen / attention window |
ctrl+alt+s / ctrl+alt+u | Konsole |
ctrl+alt+f1..f12 | Linux virtual console switching |
If a direct chord does nothing, your terminal or desktop environment consumed it before Herdr could see it. Rebind either side: free the chord in the terminal’s settings, or pick another chord in Herdr.