herdrm README

The project's README from github.com/missuo/herdrm. As one markdown file: README.md.

herdrm — every coding agent, every machine, one native terminal

The native macOS console for herdr — see Claude Code, Codex, Gemini, Grok and OpenCode across your Mac and every SSH box you own, and jump into any one of them at full-TUI fidelity.

Latest release macOS 14+ Downloads Status: early stage PRs welcome

What it does · Why herdrm? · Install · Quick Start · Architecture

herdrm — device switcher and a live claude terminal

✨ What it does

herdr is the runtime your coding agents live on — a background server that owns their terminals and knows which one is working, blocked, or done. herdrm is a native macOS window on top of it, and it's grown well past "attach to a terminal":
🖥️ Every device Local + remote over SSH — keys, Tailscale, or a Keychain password — with auto-reconnect
🧭 Live status Spaces, Agents & Terminals across every connected device
⌨️ Real terminal Full PTY attach, not a chat wrapper — native selection, legible fonts, resilient sessions
📎 Paste anything Files and images land straight in the agent's pane, locally or over SSH
📁 Move files Browse Local + SSH files side by side and copy in either direction
🔔 Notifications A system alert the moment an agent needs you — click it to jump right there
🔍 ⌘K search Every agent, on every device, one keystroke away
See the full feature list

Every machine, one sidebar

  • All your devices, in parallel — remote sockets forwarded over ssh -L, each on its own reconnect loop (1s → 30s backoff). The sidebar aggregates every device with a tinted OS badge; the bottom-left switcher filters by device.
  • Flexible SSH targets — user@host, user@host:port, ssh:// URIs, and ~/.ssh/config aliases. Auth falls back OpenSSH keys/agent → Tailscale SSH (1.98.0+) → an in-app password prompt stored in the macOS login Keychain, never in a file.
  • Diagnosable failures — "herdr isn't running on <host>", a misconfigured AllowStreamLocalForwarding, or why a disconnected device is unreachable — never a bare "not connected".

Spaces, Agents & Terminals, always current

  • Spaces, Agents & Terminals sidebar — every workspace, coding agent (claude, codex, gemini, grok, opencode, …), and ordinary Herdr shell pane, across local and SSH devices.
  • New Agent / New Terminal / New Space — New Terminal creates a persistent shell tab in any device and space. Locally the agent picker only lists advertised CLIs found on the login-shell PATH (captured once from a real interactive + login shell, not by grepping rc files or trusting LaunchServices); SSH devices follow the remote server's manifest catalog and validate on start. Each agent's bypass-permissions flag is on by default. ⌘N for a new agent, ⌘T for a new terminal, ⇧⌘N for a new space. New Space includes an inline directory browser that works over SSH. Settings → Agents accepts a per-kind binary path when detection is wrong.
  • Spaces rename straight from the sidebar's context menu.

A real terminal, not a chat wrapper

  • Live terminal — attaches directly to an agent or shell PTY (herdr agent attach / herdr terminal attach); grabs keyboard focus the moment you jump in from ⌘K, the sidebar, or a notification.
  • Standalone terminals — open a local login shell or choose any configured SSH device; remote shells reuse the same OpenSSH config, agent, host-key, and Keychain password flow.
  • Native text selection — drag to select, no Shift needed; right-click for Copy/Paste/Select All plus link actions (⌘-click opens a URL).
  • Legibility controls — Thin strokes, font Weight, and Line spacing settings.
  • Shift+Enter inserts a line break instead of submitting; colors adapt correctly in Light mode instead of washing out.
  • Resilient sessions — a dropped connection or a takeover shows a Reconnect button instead of freezing on the last frame; mixed-version herdr binaries no longer break attach.

Files, search, and staying in the loop

  • Two-pane file manager — browse Local and any configured SSH device side by side, then upload or download regular files with progress, cancellation, and explicit Replace / Keep Both conflict handling. Transfers use the same OpenSSH config, agent, host-key, and Keychain password flow as terminals.
  • Paste files and images into Claude Code, Codex, Copilot, Cursor, Gemini, Grok, OpenCode, or pi. Local pastes forward as Ctrl+V so the agent reads the clipboard itself; remote pastes stream over SSH into a self-pruning cache (7-day retention, 50 MB cap) and paste the path.
  • Search — ⌘K across every device, ordered by urgency, scrolling to follow your selection.
  • Notifications — a sound and a system alert when any agent finishes or needs input; clicking jumps straight to it. Agents you're already watching stay quiet.

Built like a native Mac app

  • Universal binary — Apple Silicon and Intel, one download.
  • Light & dark, auto-updates via Sparkle, signed and notarized.
  • HerdrKit — the socket-RPC/SSH/device layer ships as its own, independently testable Swift package (Packages/HerdrKit).

🤔 Why herdrm?

You already run agents through herdr because the model is right — spaces, live status, real PTYs, not a chat window pretending to be one. But living in herdr attach and a wall of terminal panes is its own skill, and not everyone wants to be a tmux person to get the benefit. herdrm is the same model, built for people who'd rather click:

📋 Requirements

📦 Install

Homebrew

brew install owo-network/brew/herdrm

Manual — download herdrm-x.y.z.zip from Releases, unzip, drag herdrm.app into /Applications. Either way it self-updates from then on — HerdrM → Check for Updates…, or HerdrM → About HerdrM for the version you're running.

⚡ Quick Start

1. Launch herdrm            → no local herdr running? herdrm starts it for you
2. Add a device (optional)  → you@dev-box · you@dev-box:2222 · a Tailscale machine
3. ⌘N                       → pick a device + a CLI, you're attached to its live terminal
4. ⌘K                       → jump to any agent on any device, any time

🏗️ Architecture

flowchart LR
    A(["🖥️ herdr<br/>background server, owns the PTYs"]) -->|"Unix-socket RPC +<br/>herdr agent attach"| B[["Packages/HerdrKit<br/>RPC client · SSH tunnel · device store"]]
    B -->|SwiftUI bindings| C(["Sources/HerdrM<br/>sidebar · terminal · search · notifications"])
    style A fill:#161b22,stroke:#E2795B,color:#e6edf3
    style B fill:#1f2630,stroke:#3B82F6,color:#e6edf3
    style C fill:#161b22,stroke:#2FA35F,color:#e6edf3

🔨 Build from source

brew install xcodegen
make build   # xcodegen + xcodebuild → build/Build/Products/Debug/herdrm.app
make run
make kit-test  # HerdrKit integration tests (needs a running local herdr)

🤝 Contributing

Early-stage software, PRs genuinely welcome — small and single-purpose lands fastest.

🙏 Credits

📄 License

PolyForm Noncommercial 1.0.0 — free to use, modify, and share for any noncommercial purpose. Commercial use requires a separate license from the maintainer. Contributions are accepted under the same terms.

⚠️ Status

Early stage, without full test coverage — expect bugs. Issues and PRs are very welcome.

⭐ Star History

Star History Chart for missuo/herdrm

herdrm (missuo/herdrm)

Searching Database…

763 ·GitHub
Herdrm
Что это?herdrm — нативное консольное приложение для macOS, надстройка над herdr, фоновым демоном, который владеет терминалами ваших агентов для кодинга; оно позволяет видеть живой статус и подключаться к любому терминалу агента или shell на локальных и удалённых (SSH) устройствах из одной боковой панели.
Это приложение с интерфейсом или терминальный мультиплексор вроде tmux?Это полностью нативное приложение macOS на SwiftUI, не Electron-обёртка и не чат-интерфейс — оно даёт настоящий PTY-терминал через кликабельную боковую панель вместо навигации с клавиатуры в стиле tmux.
Как установить herdrm?Установите через Homebrew или скачайте herdrm-x.y.z.zip со страницы Releases, распакуйте и перетащите herdrm.app в /Applications. После этого программа самообновляется через Sparkle.
Нужно ли устанавливать herdr отдельно?Да — сам herdr должен быть установлен локально (herdrm запустит его автоматически, если он не работает) и на любой удалённой машине, к которой вы хотите подключаться. Удалённым устройствам нужны доступ OpenSSH, Tailscale SSH 1.98.0+ или пароль, хранящийся в Связке ключей.
Достаточно ли стабилен herdrm для ежедневного использования?Это явно ранняя стадия без полного покрытия тестами, так что баги ожидаемы; CI-шлюза пока нет, и контрибьюторов просят вручную запускать make build и make kit-test.
Он работает на Intel Mac или только на Apple Silicon?Он поставляется как универсальный бинарник и требует macOS 14 или новее, так что работает и на Apple Silicon, и на Intel Mac.
Где хранятся SSH-пароли для удалённых устройств?Когда аутентификация по ключам недоступна, herdrm переключается на запрос пароля внутри приложения, значение которого сохраняется в связке ключей macOS и никогда не записывается в файл.
Можно ли пользоваться herdrm бесплатно, в том числе в коммерческих целях?Он лицензирован под PolyForm Noncommercial 1.0.0: бесплатно использовать, изменять и делиться можно для любых некоммерческих целей, а коммерческое использование требует отдельной лицензии от сопровождающего.
К каким агентам для кодинга может подключаться herdrm?Он показывает заявившие о себе CLI, найденные в PATH вашей login-оболочки, включая claude, codex, gemini, grok, opencode и pi, плюс обычные shell-терминалы как «обычные панели Herdr shell».
Можно ли перемещать файлы между моим Mac и удалённым SSH-хостом?Да — двухпанельный файловый менеджер показывает Local и любой настроенный SSH-девайс рядом, с загрузкой/выгрузкой, прогрессом, отменой и явной обработкой конфликтов с выбором «заменить» или «оставить оба».
Зачем herdrm, если можно просто подключаться через tmux по SSH?Вы получаете ту же модель herdr (пространства, живой статус, настоящие PTY) через нативную кликабельную боковую панель с уведомлениями и поиском Cmd+K, так что не нужно жить внутри мультиплексора, чтобы следить за несколькими агентами на разных машинах.
Что такое HerdrKit?HerdrKit — слой транспорта socket-RPC/SSH/устройств и слой домена, поставляемый как отдельный независимо тестируемый Swift-пакет, отделённый от кода интерфейса на SwiftUI.
What are similar projects?WindTerm, herdr-web-ui, tuios, OpenYoink, AceShell, herdr-gpui, Codync, MacPacker
Which topics is it in?pty, remote-development, ssh-client, terminal-emulator, file-manager, remote-access, swiftui, ssh, coding-agents, macos-app, homebrew, apple-silicon
Creator
missuo
Size
44.6 MB
Stars
763
Updated
CommitOct 17Releasev0.6.18Oct 17
Age
2mo
Commits · 90 Days