# Herdr keyboard shortcuts

> Herdr keyboard shortcuts cheat sheet: the ctrl+b prefix, splits, tabs, panes, renaming, copy mode, the session navigator, and how to change any key.

Author: [Flavio Copes](https://flaviocopes.com/about/) | Published: 2026-10-01 | Topics: [AI](https://flaviocopes.com/tags/ai/) | Canonical: https://flaviocopes.com/herdr-shortcuts/

Herdr's default prefix key is `ctrl+b`. Press `ctrl+b`, release it, then press the action key: `ctrl+b c` opens a new tab, `ctrl+b v` splits the pane to the right, and `ctrl+b q` detaches while everything keeps running.

To see every binding active in your session, press `ctrl+b ?`. Press `/` in that panel to filter it, for example by typing `rename`.

This post lists the default keymap, checked against the Herdr docs and source in September 2026. I use the defaults myself: my `config.toml` has a single line, `onboarding = false`. If Herdr is new to you, start with my [deep dive into Herdr](https://flaviocopes.com/herdr/).

## The quick answer

| What you want | Keys |
| --- | --- |
| Show every binding | `ctrl+b`, then `?` |
| New tab | `ctrl+b`, then `c` |
| Split right | `ctrl+b`, then `v` |
| Split down | `ctrl+b`, then `-` |
| Move to another pane | `ctrl+b`, then `h` `j` `k` `l` |
| Zoom the focused pane | `ctrl+b`, then `z` |
| Close the focused pane | `ctrl+b`, then `x` |
| Rename the tab | `ctrl+b`, then `shift+t` |
| Rename the workspace | `ctrl+b`, then `shift+w` |
| New workspace | `ctrl+b`, then `shift+n` |
| Switch workspace | `ctrl+b`, then `w` |
| Scroll back and copy | `ctrl+b`, then `[` |
| Detach | `ctrl+b`, then `q` |

## How does the Herdr prefix key work?

The programs inside a pane already use most key combinations. `ctrl+c` interrupts, `ctrl+r` searches your shell history, and editors claim almost everything else. Herdr reserves one key, the prefix, and treats the next keypress as a command for itself.

So `ctrl+b z` is two steps. Hold Control and press `b`. Let go of both keys. Now press `z`, and the focused pane fills the whole tab. Do it again to bring the other panes back.

The Herdr docs and the config file write this as `prefix+z`. When a binding includes `shift`, like `prefix+shift+t`, the second key is a capital `T`.

Press `Esc` after the prefix to cancel it. A key that isn't bound cancels it too, and Herdr drops that key instead of passing it to the pane.

To send a real `ctrl+b` to the program in the pane, press `ctrl+b` twice. Bash and zsh use it to move the cursor back one character, and Vim uses it to scroll up a page.

## The complete Herdr cheat sheet

In every table with an **After `ctrl+b`** column, press the prefix first and then the key in that column.

### Session and help

| Action | After `ctrl+b`, press |
| --- | --- |
| Show all bindings | `?` |
| Detach and leave everything running | `q` |
| Open settings | `s` |
| Reload `config.toml` | `shift+r` |
| Jump to the notification on screen | `o` |
| Send a literal `ctrl+b` to the pane | `ctrl+b` |

There is no key that stops the server. Detaching keeps every process alive, and stopping is a CLI command, `herdr server stop`. I explain the difference in [how to exit, close, and detach from Herdr](https://flaviocopes.com/exit-herdr/).

### Workspaces

| Action | After `ctrl+b`, press |
| --- | --- |
| New workspace | `shift+n` |
| Rename workspace | `shift+w` |
| Close workspace | `shift+d` |
| Workspace navigation | `w` |
| Session navigator | `g` |
| New Git worktree | `shift+g` |
| Show or hide the sidebar | `b` |

Closing a workspace asks for confirmation first, because it ends every process in its tabs.

`ctrl+b w` opens navigate mode. While it's open, single keys work without the prefix:

| In navigate mode | Keys |
| --- | --- |
| Select the workspace above or below | `up` / `down` |
| Open the selected workspace | `Enter` |
| Jump to workspace 1 to 9 | `1` to `9` |
| Focus the pane left, down, up, right | `h` `j` `k` `l` |
| Cycle through panes | `Tab` / `shift+Tab` |
| Leave navigate mode | `Esc` |

The other prefix keys work in navigate mode too. `ctrl+b w` followed by `c` creates a tab without pressing `ctrl+b` again.

### Tabs

| Action | After `ctrl+b`, press |
| --- | --- |
| New tab | `c` |
| Rename tab | `shift+t` |
| Next tab | `n` |
| Previous tab | `p` |
| Go to tab 1 to 9 | `1` to `9` |
| Close tab | `shift+x` |

A new tab asks for a name before it opens. If you'd rather skip that prompt, set `prompt_new_tab_name = false` in the `[ui]` table of your config.

### Panes

| Action | After `ctrl+b`, press |
| --- | --- |
| Split right (side by side) | `v` |
| Split down (stacked) | `-` |
| Focus the pane left, down, up, right | `h` `j` `k` `l` |
| Next or previous pane | `Tab` / `shift+Tab` |
| Swap with the pane left, down, up, right | `shift+h` `shift+j` `shift+k` `shift+l` |
| Zoom the focused pane | `z` |
| Resize mode | `r` |
| Rename pane | `shift+p` |
| Close pane | `x` |

You get a new pane by splitting the one you're in, since Herdr has no separate "new pane" key. From a script, the same split is:

~~~bash
herdr pane split --current --direction right
~~~

In resize mode, press `h`, `j`, `k`, `l` or the arrow keys to resize the focused pane, then `Esc` or `Enter` when you're done.

Closing a pane ends the program running in it.

Herdr names splits the way Vim does. In the config, `split_vertical` is the side-by-side split and `split_horizontal` is the stacked one. tmux uses the opposite names, so keep that in mind when you edit the file.

### Rename a tab, workspace, pane, or session

| Rename | After `ctrl+b`, press |
| --- | --- |
| Tab | `shift+t` |
| Workspace | `shift+w` |
| Pane | `shift+p` |

You can also right-click a tab, a pane, or a workspace in the sidebar and choose **Rename**. The sidebar lists workspaces under **spaces**, so if you're looking for a way to rename a space, it's the same thing.

From the CLI, read the IDs with `herdr workspace list`, `herdr tab list` or `herdr pane list`, then rename:

~~~bash
herdr tab rename w1:t2 tests
herdr workspace rename w1 api
herdr pane rename w1:p2 server
~~~

Named sessions can't be renamed. A session gets its name when you create it with `herdr session attach work`, and Herdr keeps its files in `~/.config/herdr/sessions/work`.

### Scrollback and copy mode

| Action | After `ctrl+b`, press |
| --- | --- |
| Enter copy mode | `[` |
| Open the pane's scrollback in `$EDITOR` | `e` |

Copy mode is how you read and copy a pane's history with the keyboard. These keys work once you're inside:

| In copy mode | Keys |
| --- | --- |
| Move | `h` `j` `k` `l` |
| Jump by word | `w` `b` `e` (or `W` `B` `E` for whitespace-separated words) |
| Page up and down | `PageUp` / `PageDown`, `ctrl+u` / `ctrl+d` |
| Search forward or backward | `/` / `?` |
| Next or previous match | `n` / `N` |
| Start a selection | `v` or `Space` |
| Copy the selection | `y` or `Enter` |
| Leave | `q` or `Esc` |

The program in the pane keeps running while you scroll, and new output keeps arriving. Search ignores case unless your query has an uppercase letter.

Notice that `ctrl+b` inside copy mode starts the prefix instead of paging up.

### Find a pane or an agent

`ctrl+b g` opens the session navigator, a searchable list of every workspace, tab, and pane in the session.

| In the session navigator | Keys |
| --- | --- |
| Search panes by name | `/`, then type |
| Show only blocked, working, idle, or done agents | `b` / `w` / `i` / `d` |
| Show everything again | `a` |
| Move up and down | `k` / `j` or the arrow keys |
| Jump to the selected row | `Enter` |
| Close | `Esc` |

Press `b` to list only the agents waiting for your input, then `Enter` to jump to one.

`ctrl+b o` jumps to whatever the notification on screen points at, like an agent that just finished in another workspace.

Herdr also has agent actions with no default key: `next_agent`, `previous_agent` and `focus_agent`. Bind them if you jump between agents often:

~~~toml
[keys]
next_agent = "prefix+a"
focus_agent = "prefix+alt+1..9"
~~~

## Does Herdr support the mouse?

Yes. You can use Herdr without learning any of the keys above, because mouse capture is on by default:

- click a pane, tab, workspace, or agent to focus it
- drag the border between two panes to resize them
- right-click a pane for **Split right**, **Split down**, **Zoom**, **Rename pane** and **Close pane**
- right-click a tab or a workspace to rename or close it
- drag to select text, which copies it, or double-click to copy a word
- ctrl-click a link in a pane to open it
- use the scroll wheel to move through a pane's output

At the bottom of the sidebar's workspace list, **new** creates a workspace and **menu** opens settings, the keybinding list, reload config, and detach.

If you want your terminal's own mouse selection back, turn mouse capture off:

~~~toml
[ui]
mouse_capture = false
~~~

## How do I change the Herdr prefix key?

Herdr reads its config from `~/.config/herdr/config.toml` (on Windows, `%APPDATA%\herdr\config.toml`). Keybindings go in a `[keys]` table.

This moves the prefix to `ctrl+a`, the default in GNU Screen:

~~~toml
[keys]
prefix = "ctrl+a"
~~~

Your shell uses `ctrl+a` to jump to the start of the line. After this change, press `ctrl+a` twice to send it.

Then check the file and apply it:

~~~bash
herdr config check
herdr server reload-config
~~~

`config check` prints any problem it finds in the file. `reload-config` applies the change to the running session without restarting your panes. Inside Herdr, `ctrl+b shift+r` reloads the config too.

If a value is invalid, Herdr falls back to the default and shows a warning when it starts.

## How do I change a single Herdr keybinding?

Every action has a name, and you assign it a key string. A binding can also be a list, so you can keep the default and add a second shortcut.

This config brings back the tmux keys for detach, rename tab and both splits, and keeps Herdr's own split keys working:

~~~toml
[keys]
detach = "prefix+d"
rename_tab = "prefix+comma"
split_vertical = ["prefix+v", "prefix+percent"]
split_horizontal = ["prefix+minus", "prefix+double_quote"]
~~~

A new value replaces the default, so after this `ctrl+b q` no longer detaches.

`prefix+d` means the prefix, then `d`. Punctuation can be written by name, like `minus`, `comma`, `percent` or `double_quote`. A binding without `prefix+`, like `ctrl+alt+z`, works as a direct shortcut with no prefix at all.

Direct shortcuts are faster, but your terminal and your desktop already own many of them. The Herdr docs suggest the `ctrl+alt` family because it's almost always free:

~~~toml
[keys]
new_tab = ["prefix+c", "ctrl+alt+c"]
zoom = ["prefix+z", "ctrl+alt+z"]
~~~

Avoid bindings made of a single plain key like `n`. Herdr would catch that key every time you type it in a pane.

To see every action name with its default, print the full default config:

~~~bash
herdr --default-config
~~~

To start over, `herdr config reset-keys` backs up `config.toml` and removes your custom keybindings, so the defaults come back at the next reload.

## Herdr shortcuts for tmux users

Herdr uses the same `ctrl+b` prefix as tmux, so a lot of muscle memory carries over. After the prefix, these keys do the same thing in both: `c` for a new tab (a window, in tmux), `n` and `p` for the next and previous one, `z` to zoom, `x` to close a pane, `[` for copy mode, `?` for the key list, and `ctrl+b` again to send the prefix to the program.

These are different:

| Action | tmux | Herdr |
| --- | --- | --- |
| Split side by side | `%` | `v` |
| Split stacked | `"` | `-` |
| Detach | `d` | `q` |
| Rename the window or tab | `,` | `shift+t` |
| Rename the session | `$` | not possible |
| Close the window or tab | `&` | `shift+x` |
| Move between panes | arrow keys | `h` `j` `k` `l` |
| Next pane | `o` | `Tab` |
| Numbered windows or tabs start at | `0` | `1` |

Be careful with `q`. In tmux it shows the pane numbers, and in Herdr it detaches. Detaching keeps everything running, but it surprises you the first time. Also, `ctrl+b s` opens Herdr's settings, not a list of sessions.

For the bigger differences, read my [Herdr vs tmux vs Zellij comparison](https://flaviocopes.com/herdr-vs-tmux-zellij/), or my [tmux tutorial](https://flaviocopes.com/tmux/) for tmux itself.

## Using Herdr shortcuts on a phone

On a phone, the hard part is typing `ctrl+b` at all. Most SSH apps have an extra row of keys with Control, so use that, or move the prefix to a key the app sends easily.

When the terminal is 64 columns wide or less, Herdr switches to a single-column mobile layout. My [guide to using Herdr from a phone](https://flaviocopes.com/herdr-phone/) covers the SSH setup and the keys I'd use there.

## What if a shortcut does nothing?

Your terminal or your operating system might grab the key before Herdr sees it. This happens more with direct shortcuts than with prefix keys.

Press `ctrl+b ?` to confirm the binding exists, then look for a conflicting shortcut in your terminal's settings. The Herdr [keyboard docs](https://herdr.dev/docs/keyboard/) list the `ctrl+alt` chords that terminals and desktop environments already use.