1. Installing Herdr Projects, and What the Restart Costs You

Herdr Projects is a plugin for Herdr, the agent multiplexer, and it exists for one situation: you have a piece of work too big for a single coding agent, and briefing five of them by hand has become a job in itself. It gives you one coordinator conversation that starts a separate agent per task, each on its own branch, and an overview of which ones need you.

It went up on 18 September, has 290 stars, is MIT licensed and is written in Rust. We installed it on a machine that was not ready for it, which turned out to be the useful part.

Two things the docs get wrong

Before the install, the two corrections that will save you time.

The repository is not private. The getting started guide says "The repository is currently private. Authenticate Git for GitHub before installing." We checked with no credentials at all:

$ curl -s -o /dev/null -w "%{http_code}" \
    https://api.github.com/repos/eliasstravik/herdr-projects
200

Public, and the web page returns 200 unauthenticated too. You do not need to set up Git authentication to install this, and the instruction telling you to is a leftover from before the repo was opened up.

The error the docs name is not the error you get. This one matters more, and it is the whole of the next section.

The version wall

The plugin needs Herdr 0.9.1 or newer, and the docs are specific that both the client and the running server must be on it. We were on 0.8.2. Homebrew had 0.9.1 waiting:

$ brew upgrade herdr
herdr 0.8.2 -> 0.9.1

Twelve seconds. Then the thing worth knowing:

$ herdr status
client:
  version: 0.9.1
  protocol: 22
server:
  status: running
  version: 0.8.2
  endpoint_compatible: unknown

The client upgraded. The server did not, because it was already running and Homebrew does not restart it. This is exactly the state the docs warn about, and it is easy to land in without noticing: herdr --version alone says 0.9.1 and looks fine.

We tried installing anyway, to see what happens:

$ herdr plugin install eliasstravik/herdr-projects --yes

{"error":{"code":"protocol_mismatch","message":"client protocol 22
is newer than server protocol 20; restart the Herdr server before
using this command. Stop the old server to use the new version.
Stopping exits pane processes.
Run `herdr server stop`, then run `herdr` again."}}

The docs say this fails with plugin_requires_newer_herdr. It fails with protocol_mismatch, and the numbers it reports are protocol versions, 22 against 20, not Herdr versions. If you search the docs for the error you actually got, you will find nothing.

Finding out what you are about to kill

Since the tooling cannot tell you while it is in this state, drop to the process table. The Herdr server's children are your panes:

$ pgrep -f "herdr server"
22998

$ pgrep -P 22998 | while read k; do
    ps -o pid,etime,command -p "$k" | tail -1
  done
23015  06-19:36:21  -zsh

One shell, which looks harmless. It is not the whole answer, because what matters is what is running inside that shell:

$ pgrep -P 23015 | while read k; do
    ps -o pid,etime,command -p "$k" | tail -1
  done
23302  06-19:35:12  claude --dangerously-skip-permissions

There it is. Two levels down, invisible to the first check, and six days old.

Work out where it was running before you decide, because that tells you whether it matters:

$ lsof -a -d cwd -p 23302 | tail -1 | awk '{print $NF}'
/Users/you/SomeProject

Close it properly rather than letting the restart take it. In a Claude Code pane, /quit writes the transcript, and claude --resume from that directory brings the conversation back later.

The restart

$ herdr server stop
stopped

$ herdr server &

$ herdr status
client:
  version: 0.9.1
  protocol: 22
server:
  status: running
  version: 0.9.1
  endpoint_compatible: yes

endpoint_compatible: yes is the line to check. Until you see it, every Herdr command will keep returning the protocol error.

Rust, and what it actually costs

The plugin is Rust and Herdr builds it from source during installation, so you need a toolchain. The docs ask for Cargo 1.89 or newer.

$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
    | sh -s -- -y --profile minimal
$ cargo --version
cargo 1.98.0

Four seconds on a fast connection, which is faster than we expected. The disk cost is not:

Path	Size
~/.cargo	555 MB
~/.rustup	455 MB
Total	1.0 GB

A gigabyte of toolchain to install a 3.3 MB binary. That is how Rust distribution works and it is not the plugin's fault, but it is worth knowing before you start, especially on a laptop that is tight on space. We used --profile minimal, which already skips the documentation and extra components.

Installing the plugin

$ herdr plugin install eliasstravik/herdr-projects --yes

One note on that flag. Without --yes, in a non-interactive shell, you get remote plugin install requires --yes when stdin is not interactive and an exit code of 0. A script that checks the exit code will conclude the install succeeded when nothing was installed. If you are automating this, check for the binary rather than trusting the status.

Seventeen seconds, including the Cargo release build. What it registered:

Actions	9
Panes	4
Build command	cargo build --release --locked
Binary size	3.3 MB

The --locked is a good sign: it builds against the committed lockfile rather than resolving fresh dependencies, so your build matches the one the author tested.

Checking it worked

The plugin ships a self-check, and it is genuinely useful:

$ herdr-projects action doctor

[ok  ] herdr: 0.9.1 (herdr)
[ok  ] session: ~/.config/herdr/herdr.sock
[ok  ] git: git version 2.50.1
[ok  ] ssh: OpenSSH_10.2p1
[ok  ] rsync: openrsync: protocol version 29
[ok  ] gh: gh version 2.86.0
[ok  ] gh auth: logged in
[warn] root: does not exist yet; `new` creates it
[warn] ticker: not running

Both warnings are expected on a fresh install and clear themselves once you create a project. Running doctor first is the right move: it catches a missing gh or an unauthenticated Git before you hit them halfway through setting up a project.

What the install actually registers

The install preview is worth reading rather than approving past, because it is the clearest description of the plugin's surface area you will get:

panes: 4
build commands: 1
  build: cargo build --release --locked
  startup: herdr-projects ticker start
  action adopt-workspace   action doctor
  action focus             action new
  action open              action overview
  action pause             action resume
  action unfocus
  pane adopt   pane new   pane overview   pane pick

Two details in there matter.

The startup command runs a background ticker. The docs are clear that it "starts a background ticker only when you have at least one project; until then it creates nothing", and our doctor output confirmed it: [warn] ticker: not running on a fresh install. A plugin that declines to run a daemon until you have given it something to do is behaving well.

The install is pinned to a commit. Check afterwards:

$ herdr plugin list
- herdr-projects (Projects) enabled
  [github:eliasstravik/herdr-projects@a4cdb0a69713d98...]

A full SHA, not a branch name. Combined with --locked on the Cargo build, what you installed is reproducible, which is more than you get from most plugin systems.

Where it puts things

Path	What
~/.config/herdr/plugins/github/herdr-projects-<hash>/	Clone and build output
~/.config/herdr/plugins/config/herdr-projects	Plugin config
~/.herdr-projects/	Your projects, created on first use
~/.config/herdr-projects/	Tool config

Four locations, all under your home directory, none of them surprising. The binary is not on your PATH by default, and the docs are upfront that running it from a terminal means symlinking it yourself.

A note on the version this covers

We installed commit a4cdb0a, which reported itself as version 0.1.0+a4cdb0a.1790054499 against Herdr 0.9.1. The repository is four days old at time of writing, has 290 stars, 14 forks, one watcher and nine open issues.

That star to watcher ratio is worth reading correctly. 290 stars and one watcher means the project has been noticed and bookmarked rather than adopted, which is normal for a project this age and is the honest context for everything above. Treat the install instructions here as accurate for this commit and expect the rough edges we found to move.

Both documentation errors we hit, the private repo claim and the wrong error code, are the kind of thing that gets fixed in a week. If you are reading this later and the docs look right, that is the project working as it should.

The total, honestly

Step	Time
brew upgrade herdr	12 s
Server restart	Seconds, plus whatever you lose in panes
rustup	4 s, 1.0 GB
Plugin install and build	17 s

Under a minute of commands. The real cost is not any of those numbers, it is the server restart, and only if you did not check what was running first.

Next

Part 2 creates a project, looks at what the plugin actually writes to disk, and reaches the point where we could no longer test it headlessly, which we will be specific about.