Skip to content
These pages describe the newest preview build. For the current release, read the stable documentation.

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.

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.

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.

Start with a directory that contains herdsman-plugin.toml and one executable script or program:

my-plugin/
herdsman-plugin.toml
index.js
id = "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 an example plugin:

Terminal window
herdsman plugin install remziduzagac/herdsman-plugin-examples/agent-telegram-notify
herdsman plugin update
herdsman plugin config-dir examples.agent-telegram-notify
herdsman plugin list
herdsman plugin action list --plugin examples.agent-telegram-notify

When you are authoring a local plugin, link the working directory instead:

Terminal window
herdsman plugin link /path/to/plugin
herdsman plugin config-dir example.layout
herdsman plugin action list --plugin example.layout
herdsman plugin action invoke example.layout.apply
herdsman plugin pane open --plugin example.layout --entrypoint board
herdsman plugin log list --plugin example.layout

plugin 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 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]] 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.

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 = 20
command = ["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.

Bind a key to an installed plugin action:

[[keys.command]]
key = "prefix+l"
type = "plugin_action"
command = "example.layout.apply"
description = "apply layout"

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.

There is no Herdsman-managed plugin storage API in v1. Plugins that need durable state should own their files or database.

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.