Configure Herdr
Keyboard shortcuts
How the Herdr prefix key works, and the direct shortcuts Dave uses instead.
Herdr is mouse first. Keyboard control is optional, and every binding is configurable.
How it works
By default Herdr uses a prefix key, like tmux. Press Ctrl+B, release it, then press one more key. Press prefix+? to see every active binding.
| Action | Default |
|---|---|
| New tab | prefix+c |
| Close tab | prefix+Shift+X |
| Next or previous tab | prefix+n, prefix+p |
| Split right, split down | prefix+v, prefix+minus |
| Move between panes | prefix+h, j, k, l |
| Zoom the focused pane | prefix+z |
| Go to any workspace, tab, or agent | prefix+g |
| Detach, leave everything running | prefix+q |
Bindings live under [keys] in the config file, including the prefix itself. A binding takes one key or a list, so you can keep the prefix version and add a direct one.
[keys]
prefix = "ctrl+a"
new_tab = ["prefix+c", "cmd+t"]A [[keys.command]] block binds a key to your own command. type = "shell" runs it in the background, type = "popup" in a floating window over the focused pane. HERDR_ACTIVE_PANE_CWD holds the working directory of that pane.
Direct chords have one catch. If the terminal or the operating system owns the key, Herdr never sees it. The terminal page frees the keys in the terminal. The section below frees the Ctrl arrows on macOS.
Dave's setup
Dave does not like the prefix. Two key presses for one action is one too many when you switch panes all day. So the actions he uses most got a direct key, mostly Cmd combinations the terminal gave up. The prefix moved to §, a key nothing else uses on a European Mac keyboard, and stays as a fallback.
| Action | Keys |
|---|---|
| New tab | Cmd+T |
| Close tab | Cmd+W |
| Go to any workspace, tab, or agent | Cmd+K |
| Previous or next tab | Ctrl+Left, Ctrl+Right |
| Previous or next workspace | Ctrl+Up, Ctrl+Down |
| Cycle panes in the tab | Alt+Up, Alt+Down |
| Open lazygit over the pane | Cmd+Shift+G |
[keys]
prefix = "§"
new_tab = ["prefix+c", "cmd+t"]
close_tab = ["prefix+shift+x", "cmd+w"]
goto = ["prefix+g", "cmd+k"]
previous_tab = ["prefix+p", "ctrl+left"]
next_tab = ["prefix+n", "ctrl+right"]
previous_workspace = "ctrl+up"
next_workspace = "ctrl+down"
cycle_pane_next = ["prefix+tab", "alt+up"]
cycle_pane_previous = ["prefix+shift+tab", "alt+down"]
# Lazygit over the focused pane. q closes it.
[[keys.command]]
key = ["cmd+shift+g", "prefix+d"]
type = "popup"
command = "cd \"${HERDR_ACTIVE_PANE_CWD:-.}\" && exec lazygit"
description = "Git status"
width = "90%"
height = "85%"Free the Ctrl arrows on macOS
macOS uses the Ctrl arrows for Mission Control and takes them before the terminal sees them. Open System Settings, then Keyboard, then Keyboard Shortcuts, then Mission Control, and uncheck these four:
- Mission Control (Ctrl+Up)
- Application windows (Ctrl+Down)
- Move left a space (Ctrl+Left)
- Move right a space (Ctrl+Right)
On Windows
There is no Cmd key, and Ctrl+T or Ctrl+W would collide with the shell. Use Ctrl+Alt chords instead, which the Herdr keyboard docs list as safe. Replace every cmd+ in the config above with ctrl+alt+, and swap § for a key your keyboard has, like ctrl+a. The Ctrl arrows are free on Windows, so skip the Mission Control step.
Check
Run herdr server reload-config. Press Cmd+T for a new tab and Ctrl+Left to go back. If a key does nothing, the terminal or the OS still owns it.