herdrm: a native macOS console for herdr agents across local and SSH devices

The problem herdrm solves for people running agents on several machines

herdr is a background runtime that owns coding-agent terminals and knows which agent is working, blocked or done. The README describes the usual way of living with it as `herdr attach` plus a wall of terminal panes, and says that is its own skill. herdrm is the alternative: a native macOS window that shows every workspace, agent and shell pane across connected devices in one sidebar, and lets you jump into any of them at full TUI fidelity. The README names Claude Code, Codex, Gemini, Grok and OpenCode as agents it can display. The audience is therefore narrow and specific. You need a Mac, a herdr runtime somewhere, and more than one machine or more than one agent to keep track of. If you run a single agent in a single terminal on one box, the sidebar and device switcher buy you very little.

How herdrm talks to herdr: sockets, SSH tunnels and a reconnect loop

The architecture is visible in the README and the repository layout. Remote devices are reached by forwarding sockets over `ssh -L`, and each device runs its own reconnect loop with a 1s to 30s backoff. The sidebar aggregates every device with a tinted OS badge, and a bottom-left switcher filters by device. SSH targets accept `user@host`, `user@host:port`, `ssh://` URIs and `~/.ssh/config` aliases. Authentication falls back in order: OpenSSH keys or agent, then Tailscale SSH (1.98.0+), then an in-app password prompt stored in the macOS login Keychain rather than a file. The terminal is a direct attach to an agent or shell PTY through `herdr agent attach` or `herdr terminal attach`, which is why text selection, fonts and line spacing behave like a terminal rather than a chat view. The socket-RPC, SSH and device layer lives in a separate Swift package, `Packages/HerdrKit`, which the Makefile exercises with `swift test`. There is also a `Packages/HerdrSSH` package whose tests the Makefile runs on an iOS Simulator destination, and the comments note that the session-driver end-to-end tests skip without a live sshd fixture. That is worth knowing before you read a green test run as full coverage.

Installing herdrm and attaching to your first agent

The README points at the releases page for downloads, and the badges state macOS 14 or later and a universal binary for Apple Silicon and Intel. Releases are auto-updated through Sparkle and are signed and notarized. There is no Homebrew formula or package-manager command in the README, so the release download is the documented path. If you build from source instead, the Makefile is the entry point. `make gen` runs `xcodegen generate`, `make build` generates and then builds the `HerdrM` scheme, and `make run` opens the built app. The Makefile defaults `CODE_SIGN_IDENTITY` to `-` and passes `CODE_SIGN_STYLE=Manual`.

make gen
make build
make run

What you should see is `build/Build/Products/Debug/herdrm.app` opened by `open`. The Makefile also defines `make kit-test`, which runs `swift test` inside `Packages/HerdrKit`, and `make test`, which is an alias for it. Once the app is running, the README describes adding devices through the SSH target formats above, then creating work with the keyboard: Command-N for a new agent, Command-T for a new terminal, Shift-Command-N for a new space. New Space includes an inline directory browser that works over SSH. On the local machine the agent picker only lists advertised CLIs that were found on the login-shell PATH, captured once from a real interactive login shell. On SSH devices it follows the remote server's manifest catalog and validates on start. If detection is wrong, the README says Settings, Agents accepts a per-kind binary path.

Where herdrm breaks down, and what the README does not promise

The failure modes are named in the README rather than hidden. A disconnected device can report that herdr is not running on a host, or that `AllowStreamLocalForwarding` is misconfigured, which means the SSH server configuration on the remote side is part of your setup, not an implementation detail. Mixed-version `herdr` binaries are called out as something that used to break attach, so version skew between the app and the runtime is a real concern even if that specific case is fixed. Paste behaviour differs by location: local pastes forward as Ctrl+V so the agent reads the clipboard itself, while remote pastes stream over SSH into a cache with 7-day retention and a 50 MB cap and then paste the path. That cache is a bounded resource you should be aware of on a small remote disk. The repository labels itself early-stage, and there is no rollback or downgrade procedure documented in the README, so pinning a release before upgrading is your own responsibility. The licence file is present as `LICENSE.md`, but the repository metadata reports the licence as NOASSERTION, which means the terms are not machine-identified. Read `LICENSE.md` yourself before shipping herdrm inside a company image.

herdrm against a plain terminal multiplexer

The obvious comparison is tmux, which the README itself invokes when it says not everyone wants to be a tmux person to get the benefit of herdr. The difference is not cosmetic. tmux gives you panes and sessions on whatever host you are already logged into, and it has no concept of an agent's state. herdrm is a client of a runtime that tracks whether an agent is working, blocked or done, and it aggregates those states across machines into one list with a searchable Command-K index ordered by urgency. tmux also does not carry your SSH credentials, your file transfers or your notifications. The trade-off runs the other way too: a multiplexer works over any SSH client, on any OS, without a GUI, and it does not care whether herdr is installed on the far side. herdrm requires macOS 14 or later, a running herdr on each host, and stream local forwarding enabled on the SSH server. If any of those is missing, the app degrades to an error message rather than a working terminal.

Maintenance cost, release cadence and licence questions

The last push to the default branch was on 2026-09-14, and the most recent releases listed are v0.6.5 and v0.6.4 on 2026-09-14, with v0.6.3 on 2026-09-10. Releases arrive in small increments, and the app updates itself through Sparkle, so staying current is the default path rather than a manual chore. That cuts both ways: an auto-updating client talking to a runtime you upgrade on your own schedule is exactly the mixed-version situation the README warns about. Building from source adds a dependency on XcodeGen through `make gen`, plus Xcode and the Swift toolchain, and `make clean` removes `build`, `build-ios`, `HerdrM.xcodeproj` and the Swift package build directories, so a clean rebuild is cheap but not instant. The Makefile notes that the iOS and SSH targets are arm64-only because of libssh2 and OpenSSL xcframeworks, and that unsigned builds log `errSecMissingEntitlement` on every launch, which matters if you try to strip code signing. On licensing, the metadata reports NOASSERTION and the README makes no statement about terms, so the only real source is `LICENSE.md` in the repository root.

Editorial conclusion

Adopt herdrm if you already run herdr and want a clickable macOS front end for agents spread across SSH machines, especially if you value real PTY attach, Keychain-stored passwords and Sparkle auto-updates. Skip it if you are not on macOS 14 or later, if you have no herdr runtime to attach to, or if you prefer a terminal-only workflow that does not need a GUI. Before relying on it, verify that herdr is running on each target host, that SSH stream local forwarding is permitted on those hosts, and that the agent CLI binaries are on the login-shell PATH or set explicitly in Settings, Agents. The repository still labels itself early-stage, so treat each release as something to check against your own hosts rather than a finished product.

Frequently asked questions

Official sources

1. Issues
2. missuo/herdrm on GitHub
3. README
4. Releases