Plugins
Herdsman plugins are shareable, executable workflow packages. A plugin can be a Bash script, JavaScript app, Lua script, Rust binary, or any other argv command your machine can run. Herdsman owns the host surface: installation, manifest validation, keybindings, terminal panes, events, invocation context, and socket access. The plugin owns its implementation language, dependencies, files, and durable state.
Plugins exist so Herdsman can stay lean. The core stays focused on terminal workspaces, panes, agents, and a stable CLI/socket API. Plugins turn that existing extension surface into reusable workflows that people can build, install, and share without adding every workflow to Herdsman itself.
A plugin is a directory with a herdsman-plugin.toml manifest and commands Herdsman
can launch. Herdsman validates the manifest, injects runtime context, starts the
declared commands, and records logs. The commands call back into Herdsman through
the CLI or socket when they need to do more work.
There is no separate plugin SDK or restricted command set. The entire Herdsman CLI
is the plugin API. Every command in the
CLI reference is available to a plugin, and a plugin can
run anything you can run yourself as herdsman .... Most plugins should call Herdsman
through HERDSMAN_BIN_PATH, which points at the running Herdsman binary. That keeps
plugins portable across Unix sockets and Windows named pipes. Use the
socket API when you want to send raw JSON requests yourself.
Runtime action registration and native non-terminal plugin UI are not part of plugin v1. Actions, event hooks, panes, and link handlers are all declared in the manifest.
Trust and security
Section titled “Trust and security”A plugin is ordinary code that runs on your machine. Its build and runtime commands run as your user, inherit your environment, and can call the full Herdsman CLI. Treat a plugin like any extension you add to an editor, shell, or coding agent.
Install or link plugins only from authors and repositories you trust. Before
installing or linking one, skim the herdsman-plugin.toml manifest and the scripts
or binaries it runs. herdsman plugin install shows a preview of the source and
the commands it will run in interactive terminals, so you can review before
confirming. Use --yes for
sources you already trust, and pin --ref when you want a specific revision.
Herdsman validates the manifest and keeps each plugin’s config and state in its own directory, but it does not review or sandbox plugin code. Third-party plugins come from their authors, not Herdsman; you are responsible for deciding whether to run them.
Manifest
Section titled “Manifest”The manifest is the contract between Herdsman and the plugin. It declares package metadata, supported platforms, optional build commands, and the entrypoints Herdsman can run.
id = "example.layout"name = "Layout"version = "0.1.0"min_herdr_version = "0.7.0"description = "Apply project layouts"platforms = ["linux", "macos", "windows"]
[[build]]command = ["npm", "ci"]
[[build]]command = ["npm", "run", "build"]platforms = ["linux", "macos"]
[[startup]]command = ["node", "dist/restore.js"]
[[actions]]id = "apply"title = "Apply layout"contexts = ["workspace"]command = ["node", "dist/apply.js"]
[[events]]on = "worktree.created"command = ["herdsman", "workspace", "list"]
[[panes]]id = "board"title = "Project board"placement = "overlay"command = ["herdsman-board"]
[[link_handlers]]id = "github-issue"title = "Open GitHub issue"pattern = "^https://github\\.com/[^/]+/[^/]+/(issues|pull)/[0-9]+$"action = "apply"Top-level id, name, version, and min_herdsman_version are required.
Set min_herdsman_version to the oldest Herdsman version that supports the plugin
APIs, event names, and manifest fields your plugin uses. Herdsman refuses to link
or install a plugin when its minimum version is newer than the current binary.
description is optional. Plugin ids may use ASCII letters, digits, dot,
colon, underscore, and hyphen.
Instead of min_herdsman_version, or beside it, a manifest may give min_herdr_version: the release of herdsman’s base project the plugin needs, which herdsman --version names on its second line. Plugins written for that project use it, as do the examples on this page. herdsman refuses a plugin when either minimum is newer than herdsman itself or than the release it is built on.
Action ids, pane ids, and link handler ids are local ids inside the plugin.
They may use ASCII letters, digits, colon, underscore, and hyphen, but not
dots. Each id type must be unique inside a plugin. Herdsman qualifies action ids
as plugin.id.action when it needs a globally unique name.
Use platforms = ["linux", "macos", "windows"] to declare where the plugin
can run. Build commands, startup hooks, actions, event hooks, panes, and link
handlers can also declare their own platforms; item-level platforms override
the top-level list. Local plugins without top-level platforms link with a
warning.
command values are argv arrays. Herdsman does not run them through a shell, so
there is no shell expansion unless your command starts a shell itself. Put
language-specific behavior in your script or binary.
First plugin
Section titled “First plugin”Start with a directory that contains herdsman-plugin.toml and one executable
script or program:
my-plugin/ herdsman-plugin.toml index.jsid = "example.workspace-tools"name = "Workspace Tools"version = "0.1.0"min_herdr_version = "0.7.0"description = "Small workspace helpers"platforms = ["linux", "macos", "windows"]
[[actions]]id = "list-workspaces"title = "List workspaces"contexts = ["workspace"]command = ["node", "index.js"]Inside the command, call back into Herdsman with HERDSMAN_BIN_PATH:
const { spawnSync } = require("node:child_process");
const herdsman = process.env.HERDSMAN_BIN_PATH ?? "herdsman";const result = spawnSync(herdsman, ["workspace", "list"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],});
process.stdout.write(result.stdout);process.stderr.write(result.stderr);process.exit(result.status ?? 1);This example uses Node, but nothing about plugins requires Node. The manifest could launch Bash, PowerShell, Python, Rust, Go, Lua, Bun, or any other command available on the user’s machine.
Install and link
Section titled “Install and link”Install an example plugin:
herdsman plugin install remziduzagac/herdsman-plugin-examples/agent-telegram-notifyherdsman plugin updateherdsman plugin config-dir examples.agent-telegram-notifyherdsman plugin listherdsman plugin action list --plugin examples.agent-telegram-notifyWhen you are authoring a local plugin, link the working directory instead:
herdsman plugin link /path/to/pluginherdsman plugin config-dir example.layoutherdsman plugin action list --plugin example.layoutherdsman plugin action invoke example.layout.applyherdsman plugin pane open --plugin example.layout --entrypoint boardherdsman plugin log list --plugin example.layoutplugin install accepts GitHub shorthand only, such as
owner/repo/subdir. It clones with git, shows a preview in interactive
terminals, builds in a new Herdsman-managed installation directory, and registers
it. Use --yes for noninteractive installs. Updates and reinstalls leave the
previous installation in place: running commands and panes keep their original
files, while new invocations use the new installation without a config reload.
Existing processes are not restarted, and startup hooks run at the next server
startup as usual.
plugin update refreshes every GitHub-managed plugin when called without a
target, or only the listed plugin ids or GitHub sources. It refetches the ref
recorded during install, skips unchanged commits, and ignores locally linked
plugins during bulk updates. Use --yes for noninteractive updates.
Installed and linked plugins, including their enabled state, are global to the
current user and available in every Herdsman session. Both plugin install and
plugin link can register plugins while no Herdsman server is running. Plugins
installed only in a named session on Herdr 0.7.3 must be installed or linked
again. Existing plugin config and state remain in place.
Installing over a locally linked plugin is refused; unlink or uninstall the
local plugin first. plugin install and plugin link create the plugin’s
config and state directories, and plugin config-dir <id> prints the config
directory for setup docs and shell scripts.
plugin uninstall <id-or-source> unregisters the plugin and accepts either the
plugin id or the same owner/repo[/subdir...] shorthand used by install.
Installation files are retained after updates, reinstalls, and uninstall so
running plugins can finish. A later successful installation/update or server
startup automatically removes obsolete managed installations once the servers
using them have exited. Reloading config does not release old installations.
Stop plugin work before shutting down its server: processes surviving server
exit are not protected from cleanup. Plugins must stop detached background
processes before their parent command or pane exits. Legacy installations
without cleanup tracking are retained. Config and state are preserved.
plugin unlink <id> only unregisters a plugin and leaves files alone, which is
useful for local development.
The example cookbook repo is remziduzagac/herdsman-plugin-examples. It contains
separate example plugins in subdirectories, including agent-telegram-notify,
github-link-preview, and dev-layout-bootstrap. Use them as examples to copy;
Herdsman does not maintain them as official plugins. That repository is not published yet.
Build commands
Section titled “Build commands”Build commands run during GitHub plugin install after confirmation and before
Herdsman registers the plugin. If a build command fails, install aborts and the
plugin is not registered. plugin link does not run build commands; local
authors build their working tree themselves. Build commands may generate files,
but changing herdsman-plugin.toml after the install preview aborts install. Build
failures show the plugin id, build index, working directory, command, exit
status or spawn error, and capped stdout/stderr without interpreting tool output.
Build commands are plain argv commands too, but they do not receive runtime
plugin context or Herdsman socket env. Plugin authors should document required
system tools such as cargo, npm, bun, or lua; Herdsman reports build
failures but does not install missing toolchains.
Startup hooks
Section titled “Startup hooks”[[startup]] commands run once for each enabled plugin after Herdsman restores the
session and its API socket is ready. They run again when a new server takes over
during live handoff, but not when a client attaches, config reloads, or a plugin
is linked or enabled. Herdsman starts them asynchronously and records their
completion in the normal plugin command log. A startup failure does not stop the
server.
Startup hooks are one-shot initialization commands rather than supervised
daemons. A hook should restore plugin-owned state, call any required Herdsman APIs,
and exit. For example, a plugin can save a declarative Agent view under
HERDSMAN_PLUGIN_STATE_DIR, then read and reapply that view from its startup hook.
Startup hooks receive the normal runtime plugin environment and
HERDSMAN_PLUGIN_EVENT=startup. The install preview lists every startup command so
users can review code that will run automatically.
Commands and environment
Section titled “Commands and environment”Runtime commands run with the plugin directory as their working directory. Herdsman
injects HERDSMAN_SOCKET_PATH, HERDSMAN_BIN_PATH, HERDSMAN_ENV=1,
HERDSMAN_PLUGIN_ID, HERDSMAN_PLUGIN_ROOT, HERDSMAN_PLUGIN_CONFIG_DIR,
HERDSMAN_PLUGIN_STATE_DIR, HERDSMAN_PLUGIN_CONTEXT_JSON, and any available
HERDSMAN_WORKSPACE_ID, HERDSMAN_TAB_ID, and HERDSMAN_PANE_ID. Action commands also
receive HERDSMAN_PLUGIN_ACTION_ID; startup and event hooks receive
HERDSMAN_PLUGIN_EVENT (startup for startup hooks), event hooks additionally
receive HERDSMAN_PLUGIN_EVENT_JSON, and pane commands receive
HERDSMAN_PLUGIN_ENTRYPOINT_ID.
HERDSMAN_PLUGIN_ROOT is the installed or linked plugin directory. Do not store
user credentials or durable state there, because GitHub-installed plugin roots
are managed source checkouts. Put user-editable config such as .env files
under HERDSMAN_PLUGIN_CONFIG_DIR, and put local runtime state under
HERDSMAN_PLUGIN_STATE_DIR. Herdsman creates those directories and seeds
HERDSMAN_PLUGIN_CONFIG_DIR from the legacy plugin config locations when present,
but it does not validate, sync, or delete their contents. The plugin owns the
file format and lifecycle.
HERDSMAN_PLUGIN_CONTEXT_JSON can include workspace, tab, focused pane, worktree,
agent, selected text, clicked URL, and link handler fields when they are
available for that invocation. Shell plugins can read the individual env vars
for common ids, or parse the context JSON for the full shape.
Use HERDSMAN_BIN_PATH when a plugin needs to call Herdsman portably from Node,
PowerShell, Bash, or another runtime. The raw socket transport behind
HERDSMAN_SOCKET_PATH is OS-specific: Unix clients connect to a Unix socket path,
while Windows clients connect to a named pipe. CLI calls through
HERDSMAN_BIN_PATH avoid that transport difference. See the
CLI reference for available commands and
socket API for raw request shapes.
Manifest pane placement defaults to overlay, which opens a temporary zoomed
overlay over the active pane and restores the previous focus and zoom when it
closes. A plugin.pane.open request can override the manifest placement with
overlay, popup, split, tab, or zoomed.
placement = "popup" opens a session-modal terminal popup without changing the
tiled layout. It accepts optional width and height fields in the manifest or
open request; omit them for the default half-size popup, use numbers for outer
terminal-cell dimensions, or use strings like "80%" for a percentage of the
terminal area. It receives all terminal input, including Escape, and closes
when the command exits or a popup.close request is sent. Dimensions smaller
than the popup minimum are clamped.
Declare the placement directly on a plugin pane entrypoint when the pane should always be transient:
[[panes]]id = "picker"title = "Picker"platforms = ["linux", "macos"]placement = "popup"width = "80%"height = 20command = ["sh", "picker.sh"]Split, tab, zoomed, and overlay plugin panes are normal Herdsman panes after they
open. Plugins can call standard pane APIs such as pane.move, pane.swap,
pane.resize, and pane.zoom through the socket or CLI; Herdsman keeps plugin
pane ownership attached to the underlying pane when it moves across tabs or
workspaces. A popup is a singleton session resource rather than a Herdsman pane:
it has no pane ID, does not change plugin focus context, emits no pane lifecycle
events, and does not participate in pane, layout, persistence, or agent APIs.
Its process does not receive HERDSMAN_PANE_ID; the underlying tiled pane remains
available through HERDSMAN_PLUGIN_CONTEXT_JSON.
Opening a popup returns ui_busy while Settings, Copy mode, or another Herdsman
modal is active, and plugin.pane.open returns an ok result after launch.
On Windows, build commands, action commands, and event commands resolve common
PATHEXT shims such as npm.cmd, bun.cmd, and pnpm.cmd when the bare
command is on PATH. Pane commands use Herdsman’s normal Windows pane launcher and
must still be valid Windows argv commands.
Keybindings
Section titled “Keybindings”Bind a key to an installed plugin action:
[[keys.command]]key = "prefix+l"type = "plugin_action"command = "example.layout.apply"description = "apply layout"Link handlers
Section titled “Link handlers”Use [[link_handlers]] to route modified clicks on matching terminal URLs to a
plugin action instead of opening the URL in the browser. The modified-click
modifier is Control on every platform, including macOS, because captured
terminal mouse reports do not expose Command/Super separately from a plain
click. pattern is a Rust regular expression matched against the clicked URL,
and action must
name an action declared by the same plugin. Link handler actions receive
invocation_source = "link_click", clicked_url, and link_handler_id in
HERDSMAN_PLUGIN_CONTEXT_JSON; shell plugins can also read
HERDSMAN_PLUGIN_CLICKED_URL and HERDSMAN_PLUGIN_LINK_HANDLER_ID. Handlers are
checked in manifest order inside each plugin.
Link clicks invoke plugins only while ui.mouse_capture is enabled. Matching handlers run first. A launch failure shows an error and stops. Without a matching handler, only HTTP(S) links open externally. When capture is disabled, the outer terminal handles explicit hyperlinks using its own shortcuts and warnings. See mouse controls for the Windows Terminal URL detection caveat.
Storage
Section titled “Storage”There is no Herdsman-managed plugin storage API in v1. Plugins that need durable state should own their files or database.
Sharing plugins
Section titled “Sharing plugins”Plugins are ordinary GitHub repositories: publish one, then share
herdsman plugin install owner/repo[/subdir]. One repository can hold several
separately installable plugins, with manifests at the root or in subdirectories
of its default branch.
Add the GitHub topic herdsman-plugin to the repository so others can find it
among the tagged repositories.
herdsman has no plugin marketplace of its own.