AI-native multiplexer
Herdr: keep agents, terminals, and projects visible.
Herdr is Groundwork's recommended multiplexer for new AI-native installations: project workspaces, tabs, panes, agent visibility, and resumable sessions in one terminal. tmux remains a supported mature choice, and existing users keep their selection until they change it.
groundwork-mux start the selected primarygroundwork-mux status --json inspect desired and live stateherdr status inspect client and serverherdr integration status inspect agent hooksChoose deliberately
| Herdr | Recommended for a new AI-native setup. Groundwork installs Herdr and owns an explicit, conservative config. |
| tmux | The traditional, mature workflow documented on the tmux page. |
| Both | Herdr is primary; tmux remains available as a fallback. groundwork-mux starts Herdr and refuses to nest either multiplexer. |
| None | Groundwork does not install or manage a multiplexer. Existing binaries and configuration remain user-owned and are not silently removed. |
Review or change the stored choice with groundwork-configure. A legacy Groundwork machine without this field stays on tmux during migration. Changing the choice updates Groundwork's desired package/config state; it does not silently uninstall packages or delete sessions.
Herdr is available under the Apache License 2.0. tmux and None remain explicit alternatives.
Inspect desired and live state
groundwork-mux status --json emits schema groundwork.terminal-multiplexer-status version 1. Its managed array is desired package state from the saved choice; available.herdr and available.tmux separately report whether each executable is currently on PATH. A failed install or a leftover unselected binary therefore remains visible instead of being mislabeled.
What Groundwork manages
- Homebrew installation on supported macOS and Linux profiles, with no vendor curl installer.
- Visible upgrades through
update-all, using the same selected Homebrew surface as installation. ~/.config/herdr/config.tomlthrough an exact hash receipt and atomic, ownership-safe apply.- A
Ctrl+aprefix shared with Groundwork tmux, current-directory following, agent session resume, plain SSH behavior, no automatic nesting, no persisted pane history, and sound disabled. - Zsh completion generated by the installed Herdr binary.
groundwork-muxas a stable launcher. It is separate, never an alias fortmuxorherdr.
Pane history stays off because terminal output can include secrets. Normal detach keeps the live Herdr server and its processes running; a complete server restart restores layout, not arbitrary processes. Native agent resume needs a current agent integration.
The Groundwork key map
Herdr workspaces correspond to the role tmux sessions play, while Herdr tabs carry the familiar tmux window shortcuts. Press Ctrla, release it, then press the second key. Herdr's Ctrla then ? help panel is the authoritative view of the effective bindings.
| Panes | | / - split; h/j/k/l focus; H/J/K/L resize; R enter resize mode; P rename; z zoom; x close |
| Tabs | c create; 1–9 switch; p/n previous/next; , rename; & close |
| Workspaces | s workspace picker; T navigator; $ rename; d detach |
| Tools | g open lazygit in a 90% popup rooted at the active pane directory when Herdr can resolve it; r reload config; [ copy mode; ? active bindings |
Direct CtrlAlth/j/k/l also focuses Herdr panes without a prefix. Groundwork deliberately does not bind direct Alth/j/k/l in Herdr: those keys remain available to Neovim, while tmux's navigator can hand them across the Neovim/tmux pane boundary. Use the prefix form on desktops that reserve a CtrlAlt chord.
Groundwork implements H/J/K/L through Herdr's supported pane-resize API so the tmux mnemonic works without relying on unreleased config fields. Tab reordering is not bound yet because Groundwork's supported Herdr interface does not expose that action; </> remain available to pane programs instead of becoming ignored configuration.
Groundwork keeps Herdr's workspace-close confirmation enabled. Pane and tab close keys are still destructive actions; read the target before using x or &.
Claude Code and Codex integrations
Groundwork does not silently edit agent settings during chezmoi apply. After Herdr is selected, inspect detected integrations, then explicitly install the official hooks for Claude Code and Codex present on this machine:
$ groundwork-herdr-integrations status
$ groundwork-herdr-integrations install --yes
$ groundwork-herdr-integrations uninstall --yesThe explicit commands delegate to Herdr's supported integration lifecycle and show final status. Claude and Codex keep their own configuration authority; Groundwork does not copy hook policy into those files.
If one agent integration succeeds and the next fails, Groundwork continues to the final status report, names the completed and failed agents, and exits nonzero. Rerun the same install or uninstall command to repair the partial state; successful Herdr integration operations are idempotent. Herdr's Codex uninstall removes its hook entries and script but intentionally leaves Codex's [features] hooks = true setting unchanged.
Persistence and recovery
| Close a client | Detach with Ctrla then d. The live server and pane processes continue. |
| Return | Run groundwork-mux or herdr; Herdr attaches to the default background session. |
| Server stopped | Herdr restores saved workspace/layout state. Arbitrary processes do not survive; supported agents can resume when their integrations reported a native session. |
| Config changed | Run herdr server reload-config. If startup warns about a value, compare the effective file with groundwork-herdr-config diff. |
Customize or remove safely
An existing unowned or changed config.toml blocks apply with recovery guidance; it is never overwritten.
groundwork-herdr-config status | Read-only ownership and drift report. |
groundwork-herdr-config diff | Compare the effective file with Groundwork's exact source. |
groundwork-herdr-config edit | Edit the source through chezmoi, then apply it. |
groundwork-herdr-config remove --yes | Remove only an unchanged, receipt-matching Groundwork config. Sessions, agent settings, and the binary stay untouched. |
To stop managing the binary too, first choose tmux or None with groundwork-configure, review brew uses --installed herdr, then run brew uninstall herdr yourself. Groundwork does not infer that deleting a package or its session data is safe.
Acceptance boundary
Automated Groundwork fixtures prove macOS/Linux package selection, rendered config, atomic ownership, conflict refusal, symlink safety, idempotence, explicit removal, primary selection, and nesting refusal. Because the current proof host does not have Herdr installed, launch, detach/reattach, agent-hook behavior, and server-restart recovery remain named manual acceptance on both platforms rather than an overclaimed automated result.