herdrmastr — herdr plugin dev

Scratch repo for building herdr plugins. herdr is a terminal workspace manager for AI coding agents (a tmux-ish server/client with workspaces → tabs → panes). Built against herdr 0.7.5.

Plugins here:

• herdr-starter — the root herdr-plugin.toml: minimal scaffold (one action + one pane).
• herdr-mail/ — agent-to-agent workspace mail over @celilo/event-bus; see herdr-mail/README.md.
• herdr-spawn/ — spawn an agent on a fresh worktree in another project and brief it over herdr-mail; see herdr-spawn/README.md.

The plugin model

A plugin is a directory with a herdr-plugin.toml manifest. Five surfaces, all optional, all driven by a command (argv array):

Surface	What it is
[[actions]]	commands run on demand (menu / contexts)
[[panes]]	plugin-owned panes herdr can open
[[events]]	lifecycle hooks (on = "on_session_start", …)
[[link_handlers]]	handle clicked links matching a pattern
[startup] / [build]	run once on load / on install-link

Required top-level: id, name, version, min_herdr_version. platforms is ["macos","linux","windows"].

Every command gets these env vars: HERDR_SOCKET_PATH, HERDR_BIN_PATH, HERDR_ACTIVE_WORKSPACE_ID, HERDR_ACTIVE_TAB_ID, HERDR_ACTIVE_PANE_ID, HERDR_ACTIVE_PANE_CWD.

Commands talk back to herdr by calling $HERDR_BIN_PATH <subcommand> — the CLI is a thin client over the socket API. Useful ones: pane, tab, workspace, notification show, agent. Run herdr <cmd> --help; full API is herdr api schema --json and live state is herdr api snapshot.

Dev loop

herdr plugin link .                       # link this dir (local, live)
herdr plugin list                         # confirm registration
herdr plugin action list                  # see actions
herdr plugin action invoke hello          # run one
herdr plugin log                          # stdout/stderr/exit_code
herdr plugin unlink herdr-starter         # done

Enum values: pane placement = overlay | popup | split | tab | zoomed (popup requires width/height, cells or NN%). action contexts = global | workspace | tab | pane | selection.

This starter

• herdr-plugin.toml — one action + one popup pane, with the other surfaces stubbed in comments.
• actions/hello.sh — toasts the active pane. The reference for how an action reads its env and calls back through the CLI.

Ship from here: herdr plugin install <owner/repo> installs from GitHub.