Reference · verified against app builders
tmux ↔ herdr mapping
Concept-by-concept mapping used by SSHHIP's shared MultiplexerCommandBuilding layer. herdr rows were
checked against a real herdr binary, not only --help text. Read from SSHHIP source
1.20.1 on 2026-08-18.
WORKSPACE_ID, TAB_ID, PANE_ID, and tmux's %ID and
@ID are immutable ids; NAME and SESSION are names, DIR is a
direction, CELLS is a count, and TTY is a path. herdr control actions resolve the focused
workspace, tab, or pane id before targeting it, while tmux commands otherwise target the attached session.
Confirmed closes resolve an immutable pane or window id first, preventing a layout change from making the close
hit the wrong target.
| Concept | tmux | herdr |
|---|---|---|
| Session attach-or-create | tmux new-session -A -s NAME | herdr --session NAME |
| Attach existing only | tmux attach-session -t NAME | herdr session attach NAME |
| List sessions | tmux list-sessions -F '#{session_name}' | herdr session list --json (running:true only) |
| Window / tab list | tmux list-windows -t SESSION -F '#{window_index}:#{window_active}:#{window_name}' | herdr tab list --workspace WORKSPACE_ID |
| New window / tab | tmux new-window -t SESSION | herdr tab create --workspace WORKSPACE_ID --focus |
| Next / previous window | tmux next-window / previous-window -t SESSION | herdr tab focus TAB_ID (resolve the tab list first - herdr has no next/prev) |
| Rename window / tab | tmux rename-window -t SESSION NAME | herdr tab rename TAB_ID NAME |
| Split pane | tmux split-window -h/-v -t SESSION | herdr pane split PANE_ID --direction DIR --focus |
| Focus pane | tmux select-pane -U/-R/-D/-L -t SESSION | herdr pane focus --direction DIR --pane PANE_ID |
| Zoom pane | tmux resize-pane -Z -t SESSION | herdr pane zoom PANE_ID --toggle |
| Resize pane | tmux resize-pane -t SESSION <flag> CELLS | herdr pane resize --direction DIR --pane PANE_ID |
| Swap pane | tmux swap-pane -s SESSION:. -t SESSION:.{dir-of} | herdr pane swap --direction DIR --pane PANE_ID |
| Close pane | tmux display-message -p -t SESSION:. '#{pane_id}', then tmux kill-pane -t %ID | herdr pane close PANE_ID |
| Close window / tab | tmux display-message -p -t SESSION:. '#{window_id}', then tmux kill-window -t @ID | herdr tab close TAB_ID |
| Workspaces | n/a | herdr workspace list / herdr workspace focus WORKSPACE_ID |
| Detach this client | tmux detach-client -t TTY | no socket detach API - TUI keybinding only |
| Copy mode | tmux copy-mode -t SESSION | TUI keybinding only - no CLI |
Non-obvious facts paid for in production code
tmux format strings destroy tab delimiters
tmux replaces control characters - including tab - with _ when expanding -F format
strings. A tab-delimited parser is unusable. SSHHIP uses colon-separated fields and keeps only the first two
colons so window names containing colons still parse.
herdr exec channels have no ambient pane
Socket API subcommands do not inherit HERDR_PANE_ID on a bare SSH exec channel. Every control action
must set HERDR_SESSION and resolve the focused workspace/tab/pane itself before mutating.
Login shells matter for discovery
Bare sh -lc is not enough on Apple Silicon Homebrew hosts. Probes must start the user's login shell
and still fall back to common absolute prefixes. See host-check.
Object model mismatch
tmux: session / window / pane. herdr: session / workspace / tab / pane. Vocabulary on SSHHIP surfaces follows the attached kind - a herdr UI never says "window."
Related
Get SSHHIP
Full access for one month, then a $29.99 lifetime unlock. No account. No SSHHIP backend.