herdr

herdr.dev · install · quick start · supported agents · docs · socket api · sponsor

---

v.0.4.0.mp4

run all your coding agents in one terminal. see who's blocked, working, or done at a glance.

run your agents where they already run; your machine, a server, anywhere you can ssh. each one gets its own real terminal, not an app's imitation of one, so even full-screen TUIs render right. click, drag, and split panes into workspaces and tabs, and watch each agent go blocked, working, done. close the laptop and nothing dies; reattach from another terminal, or from your phone over ssh. one local rust binary, not an app: no gui, no electron, no mac-only wrapper, no account, no telemetry. (if you've used tmux: it's that, rebuilt for agents.)

---

what you get

• a real terminal per agent. you see each agent's own screen, not an app's imitation of one, so even full-screen TUIs render right.
• agent state at a glance. the sidebar rolls every agent up to 🔴 blocked, 🟡 working, 🔵 done, or 🟢 idle, so you always know who needs you. zero config, no hooks required.
• workspaces, tabs, panes. organize by repo or folder, click, drag, and split, mouse-native throughout.
• nothing dies on detach. a background server keeps panes and agents alive; detach and reattach from any terminal, including your phone over ssh.
• runs anywhere. single ~10MB rust binary, linux and macos (windows beta), no dependencies, runs inside the terminal you already use.
• scriptable. a local socket api and cli that agents can drive, plus plugins you can write in any language.

how it compares

	tmux	gui managers	herdr
persistent sessions	✓	—	✓
detach / reattach	✓	—	✓
runs anywhere, over ssh	✓	—	✓
panes, tabs, workspaces	✓	✓	✓
agent awareness	—	✓	✓
lives in your terminal	✓	—	✓
real terminal views	✓	—	✓
mouse-native	—	✓	✓
lightweight binary	✓	—	✓
agents can orchestrate	?	?	✓

tmux gives you persistence and panes, but it was built before agents existed. it has no idea which pane is blocked, working, or done; you can bolt a bell character and per-harness hooks onto it, but you wire each one yourself and still have no shared view of the fleet. the gui agent managers (conductor, cmux, emdash) do show agent state, so call that table stakes. the difference is everything around it. they are apps, often mac-only and closed, that redraw the terminal inside a wrapper. herdr is a single binary that runs in the terminal you already use, anywhere you can ssh, and shows each agent's real screen on a server that keeps it alive when you disconnect. see the full comparison with tmux, zellij, cmux, warp, conductor, and more.

install

curl -fsSL https://herdr.dev/install.sh | sh

windows preview beta:

powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

also available with brew install herdr, mise use -g herdr, nix run github:ogulcancelik/herdr, or as a stable Linux/macOS binary from releases.

herdr update upgrades an installer-managed install; Homebrew, mise, and Nix update through their own package managers. channel, preview, restart, and restore details are in the install docs.

quick start

herdr

herdr starts or attaches to a background server and opens a workspace. run an agent in the pane.

herdr is mouse-native, so clicking and dragging panes, tabs, and split borders gets you everywhere without a single keybinding. for the keyboard, ctrl+b is the prefix: press it, release, then press the action key, so ctrl+b then c makes a tab. one reserved key keeps herdr out of your shell's way.

• ctrl+b then shift+n for a new workspace
• ctrl+b then v or minus to split panes
• ctrl+b then c for a new tab
• ctrl+b then w to switch workspaces
• ctrl+b then q to detach; agents keep running, run herdr again to reattach

press ctrl+b then ? for every binding. the keyboard guide explains the prefix model and how to go prefix-free; the full keymap, copy mode, and config syntax live in the configuration docs.

remote

run herdr on a VPS and reach it from your local terminal. herdr --remote makes your local terminal the client of the remote server, so pasting images into your agents keeps working, the thing plain ssh + tmux breaks.

herdr --remote workbox
herdr --remote ssh://you@yourserver:2222

see the persistence and remote docs for named sessions, keepalives, direct attach, and handoff.

supported agents

detection works out of the box with process-name matching plus terminal-output heuristics.

agent	idle / done	working	blocked
pi	✓	✓	partial
claude code	✓	✓	✓
codex	✓	✓	✓
droid	✓	✓	✓
amp	✓	✓	✓
opencode	✓	✓	✓
grok cli	✓	✓	✓
hermes agent	✓	✓	✓
kilo code cli	✓	✓	✓
devin cli	✓	✓	✓
cursor agent	✓	✓	✓
antigravity cli	✓	✓	✓
kimi code cli	✓	✓	✓
github copilot cli	✓	✓	✓
qodercli	✓	✓	✓
kiro cli	✓	✓	—

detected but not fully tested: gemini cli, cline. any other agent still works; herdr runs it as a terminal multiplexer, and custom integrations can report labels and state over the socket api.

official integrations add native session restore, and some report semantic state directly. install one with herdr integration install <agent>, available for pi, omp, claude, codex, copilot, devin, droid, kimi, opencode, kilo, hermes, qodercli, and cursor. see the integrations docs.

agents can use herdr too

the local Unix socket lets agents create workspaces, split or zoom panes, spawn helpers, read output, and subscribe to state changes instead of polling. install the reusable skill with:

npx skills add ogulcancelik/herdr --skill herdr -g

start with the agent skill docs, socket API docs, and SKILL.md.

docs

• quick start: first session, panes, copy, and named sessions
• concepts: server and client, workspaces, tabs, and panes
• install: install, update, channels, Homebrew, mise, and Nix
• session state: detach, restart restore, agent restore, and live handoff
• configuration: keybindings, copy mode, themes, notifications, environment variables
• integrations: native session restore and semantic state per agent
• socket api: socket protocol and cli reference
• SKILL.md: reusable agent skill

agent instructions

if you are an ai agent helping with this repository, read AGENTS.md before making changes and read CONTRIBUTING.md before opening issues or PRs.

development

git clone https://github.com/ogulcancelik/herdr
cd herdr
cargo build --release
./target/release/herdr

just test        # unit tests
just check       # formatting, tests, and maintenance checks

sponsors

herdr is built full-time, in the open, with no revenue behind it. sponsoring directly funds development, stability, and the path to a real agent runtime.

→ become a sponsor · enterprise / partnership: hey@herdr.dev · see SPONSORS.md for tiers. thank you 🐑

license

Herdr is dual-licensed:

1. Open source: GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).
2. Commercial: commercial licenses are available for organizations that cannot comply with AGPL.

Contact: hey@herdr.dev

mandatory star history