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…

761 ·GitHub
Herdrm
What is this?herdrm is a native macOS console app that sits on top of herdr, a background daemon that owns your coding agents' terminals, letting you see live status and attach to any agent or shell terminal across local and remote (SSH) devices from one sidebar.
Is this a GUI app or a terminal multiplexer like tmux?It is a fully native SwiftUI macOS app, not an Electron wrapper or a chat UI - it gives you a real PTY terminal through a clickable sidebar instead of requiring tmux-style keyboard navigation.
How do I install herdrm?Install it via Homebrew, or download the herdrm-x.y.z.zip from the Releases page, unzip it, and drag herdrm.app into /Applications. It self-updates afterward through Sparkle.
Do I need herdr installed separately?Yes - herdr itself must be installed locally (herdrm will start it automatically if it isn't running) and on any remote machine you want to connect to. Remote devices need OpenSSH access, Tailscale SSH 1.98.0+, or a Keychain-stored password.
Is herdrm stable enough for daily use?It's explicitly early-stage software without full test coverage, so bugs are expected; there's no CI gate yet and contributors are asked to run make build and make kit-test manually.
Does it work on Intel Macs or only Apple Silicon?It ships as a universal binary and requires macOS 14 or later, so it runs on both Apple Silicon and Intel Macs.
Where are SSH passwords for remote devices stored?When key-based auth isn't available, herdrm falls back to an in-app password prompt whose value is stored in the macOS login Keychain, never written to a file.
Can I use herdrm for free, including commercially?It's licensed under PolyForm Noncommercial 1.0.0: free to use, modify, and share for any noncommercial purpose, but commercial use requires a separate license from the maintainer.
Which coding agents can herdrm attach to?It lists advertised CLIs found on your login-shell PATH, including claude, codex, gemini, grok, opencode, and pi, plus plain shell terminals as 'ordinary Herdr shell panes'.
Can I move files between my Mac and a remote SSH host?Yes - a two-pane file manager browses Local and any configured SSH device side by side, with upload/download, progress, cancellation, and explicit Replace/Keep Both conflict handling.
Why use herdrm instead of just attaching with tmux over SSH?You get the same herdr model (spaces, live status, real PTYs) through a native clickable sidebar with notifications and Cmd+K search, so you don't have to live inside a multiplexer to track multiple agents across machines.
What is HerdrKit?HerdrKit is the socket-RPC/SSH/device transport and domain layer, shipped as its own independently testable Swift package separate from the SwiftUI interface code.
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.4 MB
Stars
761
Updated
CommitOct 17Releasev0.6.17Oct 14
Age
1mo
Commits · 90 Days