missuo/herdrm

Native macOS console for herdr — all your coding agents and their live terminals, across devices

📦 herdrm – a native macOS console for the herdr AI‑coding‑agent runtime

herdrm is a macOS‑only GUI application (built with SwiftUI) that lets you interact with the herdr background server – the daemon that runs AI coding agents such as Claude, Codex, Gemini, Grok, OpenCode, etc. It turns the remote‑or‑local PTYs managed by herdr into real, full‑featured terminal panes, while giving you a graphical sidebar to browse devices, spaces, agents and files.

✨ What it does (as described in the README)

Feature	What you get
Every device	Connect to the local Mac and any SSH‑accessible machine (plain SSH, Tailscale SSH, or password stored in the macOS Keychain). The app keeps a reconnect loop for each device.
Live status	Sidebar shows Spaces → Agents → Terminals for every connected machine, with real‑time state (running, blocked, finished).
Real terminal	Attaches to the actual PTY of an agent or shell – not a chat wrapper. You get native text selection, proper fonts, line‑spacing controls, and a resilient session that can reconnect if the connection drops.
Paste anything	Drag‑and‑drop files or images; they are streamed to the agent (locally via clipboard, remotely via a short‑lived cache).
Move files	Two‑pane file manager lets you copy files between the local Mac and any SSH host, with progress, cancel, and conflict handling.
Notifications	macOS alerts fire when an agent needs input or finishes; clicking jumps straight to that pane.
⌘K search	Global, fuzzy search across all devices, spaces and agents – one keystroke to jump anywhere.
Native macOS feel	Universal binary (Apple Silicon + Intel), light/dark mode, auto‑updates via Sparkle, signed & notarized.

🤔 Why use herdrm?

You already run agents with herdr, but the default herdr attach workflow is terminal‑centric and requires tmux‑style navigation.
herdrm gives a point‑and‑click UI (sidebar rows, context menus) while still exposing the real PTY, so you keep the full TUI experience without the mental overhead of a multiplexer.
It is pure‑native – no Electron or embedded browsers – so it launches instantly and stays lightweight.
Centralises all your machines in one window, letting you monitor status and respond to agents without polling.

📦 Installation

Method	Command / Steps
Homebrew (recommended)	`brew install owo-network/brew/herdrm`
Manual	Download the latest `herdrm‑x.y.z.zip` from the Releases page, unzip, and drag `herdrm.app` into `/Applications`. The app will self‑update thereafter via the Check for Updates… menu.

⚠️ Security note – Only the official GitHub repo and the Homebrew cask provide signed, notarized builds. Third‑party mirrors have distributed unrelated Windows payloads under the same name.

⚡ Quick‑start guide (from the README)

Launch herdrm – it will start a local herdr daemon if none is running.
(Optional) Add a remote device – e.g. you@dev-box, you@dev-box:2222, or a Tailscale host.
Press ⌘N, pick a device and a CLI (Claude, Codex, etc.) – you are attached to its live terminal.
Press ⌘K to search and jump to any other agent or terminal on any device.

🏗️ Architecture (high‑level view from the README)

herdr  (background server, owns PTYs) ──► Unix‑socket RPC / SSH tunnel ──► HerdrKit (Swift package, UI‑independent transport & device store) ──► HerdrM (SwiftUI app: sidebar, terminal, search, notifications)

herdr – the daemon that creates and persists spaces, agents and their PTYs.
Packages/HerdrKit – a Swift package handling socket‑RPC, SSH tunnelling, and device bookkeeping; it is unit‑tested separately (make kit-test).
Sources/HerdrM – the actual macOS app, built on top of SwiftTerm (a Metal‑based terminal emulator) and wired to the UI via SwiftUI.

🛠️ Development & contribution

Build prerequisites: brew install xcodegen.
Commands:
- make build – generates an Xcode project with xcodegen, then builds the app (herdrm.app).
- make run – launches the built app.
- make kit-test – runs the HerdrKit integration tests (requires a local herdr daemon).
The project is early‑stage: test coverage is limited, bugs are expected, and PRs are welcomed. Follow the contribution guidelines in the README.

📄 License

PolyForm Non‑commercial 1.0.0 – free for non‑commercial use, modification and sharing. Commercial use requires a separate license from the maintainer.

⚠️ Status

Early stage – functional but not yet fully covered by automated tests. Expect occasional crashes or missing edge‑case handling.

Bottom line: If you already use the herdr AI‑coding‑agent runtime and want a native macOS UI that lets you manage multiple devices, monitor agents, and work with real PTYs without leaving the comfort of a graphical app, herdrm is the client built exactly for that purpose.