Ghostty plus herdr: handing Cmd shortcuts to a coding-agent multiplexer

Two tools, one set of muscle memory

A post on dev.to by oronbz tackles a niche but real friction point: running the Ghostty terminal alongside herdr, a multiplexer built specifically for running coding agents such as Claude Code, Codex and opencode in panes. Both tools manage surfaces — Ghostty offers tabs and splits driven by Cmd shortcuts, while herdr brings its own tabs, panes and workspaces keyed through a tmux-style prefix, Ctrl+B followed by a letter.

After a few days of maintaining two mental maps — Cmd+T for a Ghostty tab, Prefix+C for a herdr tab — the author, a Ghostty user of roughly eight months, decided to collapse them. The goal: herdr owns the tab, pane and workspace keys, Ghostty unbinds them so the presses pass through to the terminal, and herdr answers the exact keys Ghostty just gave up.

Why herdr gets the keys

The two models overlap but are not identical, according to the post. Ghostty's hierarchy is window, tab, split; herdr's is workspace, tab, pane. The bigger difference is state: Ghostty tabs are plain shells that disappear when the window closes, whereas herdr's tabs and panes live in a persistent server, so layouts — and any agents running inside them — survive a closed window or a machine restart. herdr also has workspaces, one per project, with no Ghostty equivalent.

That persistence is the practical argument for letting herdr win the keyboard: it is the layer holding the state.

How the handoff works

On the Ghostty side, the shared Cmd bindings are unbound in the config file, so the keystroke reaches herdr like any other terminal input. On the herdr side, direct shortcuts are opt-in — the tool is prefix-first by default precisely so it does not swallow input meant for shells and editors. Prefix mode keeps working as a fallback, and Prefix+? opens the help panel.

One design decision the post explains: herdr has two numbered levels, so Cmd+1..9 goes to workspaces (the larger, project-scoped unit) and Alt+1..9 to tabs within a workspace. For Alt to register at all on macOS, Ghostty needs macos-option-as-alt = true, otherwise Option types special characters.

The configs

Ghostty, in ~/.config/ghostty/config (Cmd+, opens it, Cmd+Shift+, reloads it):

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

herdr, in ~/.config/herdr/config.toml (reload with Prefix+Shift+R or herdr server reload-config; herdr config check validates 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"

A gotcha worth flagging: Ghostty binds both cmd+1 (the character) and cmd+digit_1 (the physical key) by default, so both must be unbound or one default survives. You can verify with ghostty +show-config --default | grep goto_tab.

Who handles what afterwards

With the change in place, Cmd+T opens a herdr tab, Cmd+W closes a herdr pane, Cmd+D and Cmd+Shift+D split herdr panes, Cmd+[ and Cmd+] move pane focus, Cmd+Shift+[ and ] switch herdr tabs, Cmd+1..9 switch workspaces, and Alt+1..9 switch tabs. Ghostty keeps everything untouched: copy and paste, Cmd+N for a new window, font size and search.

The author shares the full snippets, with all nine digit unbinds written out, in a gist, and points to herdr's own documentation on prefix-free setups as worth reading before copying the configuration. The post closes with an admission that the split may not be the best one — just the one that preserved existing habits — and an invitation for others running Ghostty with herdr, tmux or Zellij to share how they divide the keys.

Why it matters

Coding agents have made terminal multiplexers newly relevant, because agents run long and need somewhere durable to live. This setup resolves the resulting overlap cleanly: state sits in the persistent multiplexer, the fast native terminal becomes a window onto sessions that keep working whether it is open or not, and years of macOS Cmd-key muscle memory stay intact. It is also a transferable template — the same unbind-and-rebind pattern applies to any pairing of terminal and multiplexer fighting over the same shortcuts.