herdr-plus: workspace templates and a quick action picker for herdr

The build step prefers Go and falls back to a release binary

Installing means one command, and herdr does the work:

herdr plugin install cloudmanic/herdr-plus

herdr clones the repository, runs the manifest's [[build]] step declared in herdr-plugin.toml, and registers the actions with herdr. Nothing in your own config.toml is edited, which is the main difference from a shell function or a keybinding you maintain by hand. That build step prefers a local Go toolchain so the binary is an exact build of the source, and falls back to downloading the newest prebuilt release binary when Go is absent, so the install works with or without Go on Linux and macOS. Three commands cover the lifecycle afterwards: herdr plugin list, herdr plugin action list --plugin cloudmanic.herdr-plus, and herdr plugin uninstall cloudmanic.herdr-plus. herdr 0.7.0 or newer is required, and every merge to main cuts a release with cross-compiled binaries.

Windows loses the prebuilt fallback and switches to a named pipe

The platform split is where the plugin stops being uniform. herdr's own Windows support is in preview, and the plugin does install and run there, but its build step compiles straight from source with the Go toolchain. There is no prebuilt-binary fallback on Windows, because the fallback on Linux and macOS is a shell script. Go therefore has to be on your PATH before herdr plugin install will finish on that platform, which rules out the quick install for anyone without a Go setup. The transport changes too: the plugin talks to herdr over a named pipe on Windows instead of a unix socket. The split lives in two files in the repository root, herdrdial_other.go and herdrdial_windows.go, and the plugin is stated to be validated against the herdr Windows beta rather than a stable channel. Treat Windows as the supported-but-rough path.

placement decides whether a picker zooms over your layout or floats

Three optional keys in a config.toml sit in the plugin's config directory, and two of them change how much of your screen herdr-plus takes over:

[worktree]
branch_prefix = "your-name/" # used verbatim; include your own trailing /

[projects]
placement = "zoomed" # overlay, popup, split, tab, or zoomed; default is zoomed

[quick_actions]
placement = "overlay" # overlay, popup, split, tab, or zoomed; default is overlay

The accepted values are the same five herdr understands, and popup is the one to pick if you want a small floating window that leaves your tiled layout alone instead of the default zoomed or overlay takeover. A bad value is not forwarded: an empty or invalid placement falls back to the built-in default and prints a warning to stderr. The branch_prefix value is used verbatim, trailing slash included, which is the detail to get right if you name worktree branches by hand.

A worktree opened from a project ignores that project's tabs

The picker has two keys and they do not build the same thing. Enter opens the highlighted project as a normal workspace, filling tabs from its own [[tabs]] definitions. ctrl+g opens it as a git worktree, and that path does not read the project's tab list at all. Instead it looks for a matching worktree auto-layout, a file in worktrees/ whose repo field matches, and fills the tabs from that. With no matching file, the worktree opens with herdr's default single pane, so a repo you habitually open with ctrl+g needs its own worktrees/ file or you get a bare pane and no error to tell you why. The worktree prompt takes an optional branch name with three cases: empty lets herdr generate a worktree/... name, a bare name gets the optional [worktree] branch_prefix attached, and a name that already contains a slash is used as-is.

Every directory is resolved and checked before a tab opens

A project is one TOML file in the projects/ subdirectory, and the file name is irrelevant: add a file to add a project, delete it to remove one, and an empty directory makes the browser show an onboarding card instead. Tabs open in file order, the first tab reuses the workspace's root tab and the rest are created behind it, and a tab with no command is just an empty shell. Directories are where the real work happens. A tab, or a single pane, can override the project's working_dir, a relative path is resolved against the project's own working_dir, and panes inherit their tab's directory unless they set one:

name = "Shop"
working_dir = "~/dev/shop"

[[tabs]]
name = "web"
working_dir = "frontend"   # relative to the project → ~/dev/shop/frontend
command = "npm run dev"

Absolute paths, ~ and $VARS expand the same way they do at project level. Every directory has to exist, and a missing one is reported before anything opens, so a typo cannot leave you a half-built workspace.

herdr-plus open skips the picker and shares its code path

The fuzzy browser is optional. A project can be opened by name with a subcommand, which is what makes the plugin scriptable:

herdr-plus open harbor-sysadmin

It loads the same templates, resolves the one whose name matches, and builds the workspace through the identical code path the picker uses, so a script and a human pressing Enter get the same layout from a single implementation rather than two that drift. Matching is exact first, with a case-insensitive fallback if nothing matches exactly. A mistyped name is not a silent no-op: it fails with the list of available projects. Note the split with the Homebrew route, which installs herdr-plus as a binary on your PATH so you can call herdr-plus version, and which explicitly does not register the plugin with herdr on its own. Registration still goes through herdr plugin install.

Config lives in herdr's plugin directory and survives upgrades

State is kept where herdr manages plugins rather than in a dotfile you have to back up yourself. The location comes from herdr:

herdr plugin config-dir cloudmanic.herdr-plus
# → ~/.config/herdr/plugins/config/cloudmanic.herdr-plus

Inside that directory, projects/ holds the workspace templates and quick-actions/ holds the one-off actions the second picker runs in the directory you launched from. herdr provisions the directory and keeps it across uninstall and upgrade, so removing the plugin does not take your templates with it. Running the binary outside herdr, which is the case for the standalone install, falls back to ~/.config/herdr-plus/ and honors $XDG_CONFIG_HOME. The repository ships both example directories, examples/projects/ and examples/quick-actions/, which are the fastest way to see the file format. The sections further down the README, covering key binding and the quick-actions file layout in detail, are not in the visible text of the file this article draws on.

A bubbletea UI, sahilm/fuzzy matching, and a test file per source file

The dependency list in go.mod is short and says what the interface is built on: BurntSushi/toml for the template files, charmbracelet bubbletea, bubbles and lipgloss for the terminal UI, charmbracelet/x/ansi for styling, and sahilm/fuzzy for the matching behind both pickers. The module targets go 1.26.2. The layout follows the same discipline, with a test file sitting next to nearly every source file: worktreebranch.go next to worktreebranch_test.go, projectsmodel.go next to projectsmodel_test.go, and separate quickactions.go and quickactionspicker.go files. The Makefile keeps the same shape, with build producing a single binary at ./bin/herdr-plus, test running the suite with the race detector the way CI does, and test-short skipping slow tests for a quick loop. There is also a Hugo site under www/, built by make site and served locally by make site-dev on port 1313.

Editorial conclusion

herdr-plus earns its place if you rebuild the same multi-tab layout by hand often, and the per-tab working_dir plus the pre-open directory check remove most of the tedium. Skip it if you need Windows without a Go toolchain on your PATH, since the prebuilt fallback is a shell script and the named pipe path is only validated against a herdr beta. Before adopting, put a worktrees/ file in place for every repo you plan to open as a worktree, read the placement defaults, which default to zoomed for projects and overlay for quick actions, and note that the last push was on 2026-09-04 with the newest tag v0.1.24 from 2026-08-28.

Frequently asked questions

Official sources

1. cloudmanic/herdr-plus on GitHub
2. License: MIT
3. Project website
4. README
5. Releases