Making Ghostty and herdr share one keyboard

I've been on Ghostty for about 8 months. Last week I added herdr, a multiplexer built around running coding agents (Claude Code, Codex, opencode and friends) in panes. Ghostty already has tabs and splits, with Cmd shortcuts I use all day. herdr has its own tabs, panes and workspaces, with its own keys.

I did the reasonable thing first and learned herdr's defaults. It's prefix-first, Ctrl+B like tmux, then a letter. It works fine, but after a few days I had two sets of shortcuts for the same actions, Cmd+T for a Ghostty tab and Prefix+C for a herdr tab, and I only ever wanted the herdr one. So I decided to merge them into a single set of keys. There are a couple of write-ups that do this by making Ghostty translate Cmd keys into herdr's prefix sequences (Matt Venables' post, native-shortcuts-herd). I went the other way: herdr binds the Cmd keys directly and Ghostty just gets out of the way. No escape codes, and it covers the split and bracket keys I actually use, so I wrote it down..

Ghostty tabs vs herdr tabs

Ghostty: window, tab, split.
herdr: workspace, tab, pane.

Same idea twice, but you get different things from each. Ghostty tabs are just shells, close the window and they're gone. herdr tabs and panes live in a server that keeps running, so I can close the window, restart the machine, come back and the layout is there and the agents kept working. herdr also has workspaces (one per project) which Ghostty doesn't have at all.

So the question is only which one should react when I press Cmd+T.

Giving the Cmd keys to herdr

Cmd+T, Cmd+W, Cmd+D and Cmd+1..9 are years of macOS muscle memory, browsers, editors, every terminal I used before Ghostty. I didn't want a second set for the same actions, and I didn't want a prefix key for things I do a hundred times a day. So:

1. herdr owns the tab / pane / workspace keys.
2. Ghostty unbinds them, so the key press goes through to the terminal like any other input.
3. herdr is configured to answer the exact same keys Ghostty used to.

herdr is prefix-first by default on purpose, so it doesn't steal input from shells and editors. Direct shortcuts are opt-in, which is what the config below does. Prefix mode keeps working as a fallback, and Prefix+? shows the help panel.

One decision I had to make on the way, Cmd+1..9 vs Alt+1..9. herdr has two levels that can take a number, workspaces and tabs. Workspace is the bigger unit (a project), so it gets Cmd. Tabs inside a workspace get Alt. For Alt to work at all on macOS you need macos-option-as-alt = true in Ghostty, otherwise Option types special characters.

The configs

Ghostty

File: ~/.config/ghostty/config. Cmd+, opens it, Cmd+Shift+, reloads it, no restart needed.

macos-option-as-alt = true

keybind = cmd+t=unbind
keybind = cmd+w=unbind
keybind = cmd+d=unbind
keybind = cmd+shift+d=unbind
keybind = cmd+[=unbind
keybind = cmd+]=unbind
keybind = cmd+shift+[=unbind
keybind = cmd+shift+]=unbind
keybind = cmd+1=unbind
keybind = cmd+digit_1=unbind
# ... same two lines for 2 through 9

I unbind both cmd+1 and cmd+digit_1 because Ghostty's defaults bind both (1 matches the character, digit_1 matches the physical key). Unbinding only one of them leaves the other default in place, you can check with ghostty +show-config --default | grep goto_tab.

herdr

File: ~/.config/herdr/config.toml. Prefix+Shift+R reloads it, or herdr server reload-config from any shell. herdr config check tells you if you broke the TOML.

[keys]
new_tab = "cmd+t"
close_pane = "cmd+w"
split_vertical = "cmd+d"
split_horizontal = "cmd+shift+d"
cycle_pane_next = "cmd+]"
cycle_pane_previous = "cmd+["
next_tab = "cmd+shift+]"
previous_tab = "cmd+shift+["
switch_workspace = "cmd+1..9"
switch_tab = "alt+1..9"

Who handles what

Ghostty keeps everything else: Cmd+C / Cmd+V, Cmd+N for a new window, font size, search.

Files

Both snippets, with all nine digit unbinds written out: https://gist.github.com/oronbz/7696a0918b459a1624997530f0b14e52

herdr's own guide for a prefix-free setup is at https://herdr.dev/docs/keyboard/, worth reading before you copy mine.

If you run Ghostty with herdr (or tmux, or Zellij) and split the keys differently, I'd like to hear how. I'm not sure my split is the best one, it's just the one that didn't break my muscle memory.