// install

One command per plugin.

Every plugin lives in its own folder with its manifest, code and tests, and installs on its own. No tool needs another: take only the ones you want.

Requirements and compatibility

	Plugins (auto-tab-name, Space Herder)	herdr-jump
System	macOS or Linux	macOS
Herdr	0.9.5 or newer	0.9.5 or newer, on the same Mac
Other herdr-tools	none: each plugin works alone	none: it reads the Herdr server only, with or without plugins
Runs on	`python3` 3.9 or newer, standard library only	Hammerspoon
Shell	none needed; auto-tab-name's optional shell integration covers zsh, bash and fish	none needed; the installer runs in `sh`
Terminal	any; Space Herder's colours need truecolor, auto-tab-name's `alt` keys need Option as Alt	any: iTerm2 and Terminal get the exact tab, other terminals come forward as an app
Also	nothing else to install	Homebrew only to install Hammerspoon; the Accessibility and Automation permissions

About python3:

Herdr runs the first python3 on the PATH its server started with, from 3.9 to the latest. On macOS, /usr/bin/python3 works once the Command Line Tools are installed (xcode-select --install); Python from Homebrew or python.org works too.
The server keeps that PATH until it restarts: after installing Python, run herdr server stop (it ends the programs running in its panes) and start herdr again.

Not covered: Windows, and for herdr-jump a Herdr client inside tmux or over ssh, whose terminal cannot be seen. install.sh --check tells what a Mac has and lacks for herdr-jump.

Plugins

Plugin	Version	Install
Space Herder	0.1.1	`herdr plugin install MrBogomips/herdr-tools/space-herder`
auto-tab-name	0.3.0	`herdr plugin install MrBogomips/herdr-tools/auto-tab-name`

herdr plugin install MrBogomips/herdr-tools/<plugin>   # one plugin
herdr plugin update                                    # update installed plugins
herdr plugin uninstall mrbogomips.<plugin>             # remove one

Herdr shows the manifest and the commands it will run before installing. Plugins are ordinary code running as your user, so read them first. Each plugin's page explains its key bindings and its config.json, which lives in herdr plugin config-dir <plugin id>.

The plugins are also listed in the Herdr plugin marketplace.

herdr-jump

A Hammerspoon Spoon, not a Herdr plugin, so herdr plugin install does not handle it. It needs only a running Herdr server: no plugin, nothing to set up inside Herdr. One line installs it, and the same line updates it (v0.4.0 today):

curl -fsSL https://raw.githubusercontent.com/MrBogomips/herdr-tools/main/herdr-jump/install.sh | sh

See what the installer does and how to read it before running it.

Versions

herdr plugin update follows main, which only receives tested changes. Every release is also tagged <plugin>-vX.Y.Z; to stay on one, pin it:

herdr plugin install MrBogomips/herdr-tools/auto-tab-name --ref auto-tab-name-v0.3.0

Release notes are on the tags page.

Develop

git clone https://github.com/MrBogomips/herdr-tools
herdr plugin link "$PWD/herdr-tools/space-herder"   # run your working copy
cd herdr-tools/space-herder && /usr/bin/python3 -m unittest -v

Code stays compatible with Python 3.9 and the standard library. CI runs every plugin's tests on macOS with the system Python and with Python 3.13 and 3.14, and on Ubuntu. Issues and pull requests are welcome on GitHub.