Add herdr as an alternative multiplexer backend

README.md

@@ -28,6 +28,7 @@ parallel without conflict.
 windowing, git for worktrees, your agent for coding - workmux ties them together.
 
 <sup><sub>\* Also supports
+<a href="https://workmux.raine.dev/guide/herdr">herdr</a>,
 <a href="https://workmux.raine.dev/guide/kitty">kitty</a>,
 <a href="https://workmux.raine.dev/guide/wezterm">WezTerm</a>, and
 <a href="https://workmux.raine.dev/guide/zellij">Zellij</a> as alternative
@@ -163,6 +164,7 @@ For manual installation, see
 > [!NOTE]
 > workmux requires a terminal multiplexer. Make sure you have
 > [tmux](https://github.com/tmux/tmux) (or
+> [herdr](https://raine.github.io/workmux/guide/herdr) /
 > [WezTerm](https://raine.github.io/workmux/guide/wezterm) /
 > [Kitty](https://raine.github.io/workmux/guide/kitty) /
 > [Zellij](https://raine.github.io/workmux/guide/zellij)) installed and running
@@ -2735,6 +2737,10 @@ workmux completions fish | source
 While tmux is the primary and recommended backend, workmux also supports
 alternative terminal multiplexers:
 
+- **[herdr](https://workmux.raine.dev/guide/herdr)** (experimental) - For users
+  who prefer herdr. Detected automatically via `$HERDR_PANE_ID`. herdr manages
+  git worktrees itself, so `add` and `remove` delegate to it instead of running
+  git directly.
 - **[WezTerm](https://workmux.raine.dev/guide/wezterm)** (experimental) - For
   users who prefer WezTerm's features. Thanks to
   [@JeremyBYU](https://github.com/JeremyBYU) for contributing this backend.
@@ -2745,9 +2751,10 @@ alternative terminal multiplexers:
   users who prefer Zellij. Detected automatically via `$ZELLIJ`.
 
 workmux auto-detects the backend from environment variables (`$TMUX`,
-`$WEZTERM_PANE`, `$KITTY_WINDOW_ID`, or `$ZELLIJ`). Session-specific variables
-are checked first, so running tmux inside kitty correctly selects the tmux
-backend. Set `$WORKMUX_BACKEND` to override detection.
+`$WEZTERM_PANE`, `$KITTY_WINDOW_ID`, `$ZELLIJ`, or `$HERDR_PANE_ID`).
+Session-specific variables are checked first, so running tmux inside kitty or
+inside herdr correctly selects the tmux backend. Set `$WORKMUX_BACKEND` to
+override detection.
 
 ## Inspiration and related tools
 

docs/astro.config.mjs

@@ -135,6 +135,7 @@ export default defineConfig({
         {
           label: "Alternative backends",
           items: [
+            { label: "herdr", slug: "guide/herdr" },
             { label: "kitty", slug: "guide/kitty" },
             { label: "WezTerm", slug: "guide/wezterm" },
             { label: "Zellij", slug: "guide/zellij" },

docs/src/content/docs/guide/herdr.mdx

@@ -0,0 +1,89 @@
+---
+title: "herdr"
+description: Use herdr as an alternative multiplexer backend
+---
+
+:::caution[Experimental]
+The herdr backend is new. Expect rough edges.
+:::
+
+[herdr](https://herdr.dev) is an agent multiplexer that lives in your terminal.
+Detected automatically via `$HERDR_PANE_ID`.
+
+herdr calls its top-level containers workspaces. workmux maps one worktree onto
+one workspace, the same way it maps one worktree onto one tmux window.
+
+## Requirements
+
+- herdr 0.7.1 or later
+- `herdr` on `PATH`, or `$HERDR_BIN_PATH` pointing at the binary
+
+## Differences from tmux
+
+| Feature           | tmux               | herdr                   |
+| ----------------- | ------------------ | ----------------------- |
+| Agent status      | Yes (window names) | Yes (pane names)        |
+| Scope             | tmux session       | herdr session           |
+| Session mode      | Yes                | No (window only)        |
+| Pane size control | Percentage-based   | Percentage-based        |
+| Stacked panes     | No                 | No                      |
+| Dashboard preview | Yes                | Yes                     |
+| Worktree creation | `git worktree add` | `herdr worktree create` |
+| Renaming a target | Yes                | No                      |
+
+## Worktree integration
+
+herdr manages git worktrees itself, so workmux delegates to it rather than
+running git directly. `workmux add` becomes a single `herdr worktree create`
+that makes the worktree and the workspace together, and `workmux remove` becomes
+a single `herdr worktree remove`.
+
+This matters when removal is deferred. Running `workmux remove` from inside the
+workspace being removed cannot tear down its own terminal, so workmux hands
+herdr a command to run after the workspace closes. On other backends that step
+renames the worktree to a trash directory and prunes it; on herdr the one
+command covers both, and no trash directory is created.
+
+workmux falls back to separate `git worktree add` and workspace creation when
+the combined call cannot express the request, namely when checking out an
+existing branch or tracking an upstream branch. Both paths produce the same
+result.
+
+## Configuration
+
+No herdr configuration is required. workmux drives herdr through its JSON CLI,
+which works out of the box.
+
+To override the auto-detected backend:
+
+```bash
+export WORKMUX_BACKEND=herdr
+```
+
+Two environment variables affect the backend.
+
+`$HERDR_BIN_PATH` is the path to the `herdr` binary, defaulting to `herdr` on
+`PATH`. Set it when herdr is installed elsewhere. Deferred cleanup commands
+embed this path, so they keep working in a detached shell.
+
+`$HERDR_SOCKET_PATH` is the socket of the herdr instance. herdr sets it, one
+value per named session, and workmux keys its stored state on it. Sessions
+started with `herdr --session <name>` therefore stay isolated from each other.
+
+## Detection order
+
+workmux checks `$TMUX` before `$HERDR_PANE_ID`. herdr exports `HERDR_PANE_ID`
+into every descendant process, so a tmux server started inside a herdr pane sets
+both; checking tmux first selects the inner multiplexer, which is the one the
+user is looking at. Set `$WORKMUX_BACKEND` to override.
+
+## Known limitations
+
+- Session mode is not supported, only window mode
+- `workmux rename` renames the worktree and branch, but leaves the workspace
+  label unchanged
+- Pane display names (`name` in a pane config) are not applied
+- Stacked panes are not supported
+- Agent status icons do not clear when a pane receives focus
+- herdr does not report pane PIDs or foreground commands, so workmux treats a
+  live pane as a live agent rather than checking the process