herdr

herdr.dev · install · quick start · supported agents · integrations · configuration · socket api

---

v.0.4.0.mp4

agent multiplexer that lives in your terminal.

workspaces, tabs, panes. mouse-native: click, drag, split. every agent at a glance: blocked, working, done. detach and reattach, agents keep running. no gui app, no electron, no mac-only native wrapper. you see the agent's own terminal, not someone's interpretation of it.

---

install

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

or download the binary from releases. requires linux or macos.

update

herdr notifies you when a new version is available. run manually to update:

herdr update

quick start

herdr

by default herdr launches or attaches to a background session server. ctrl+b q detaches the client. agents keep running. use herdr server stop to stop the server. use --no-session for the old single-process mode.

1. press n to create a workspace
2. run an agent in the root pane
3. press ctrl+b to enter navigate mode
4. use v or - to split panes, or c to create a new tab
5. watch the sidebar for blocked, working, and done states

on first run herdr opens a short onboarding flow. after that, restored sessions land in terminal mode; fresh sessions start in navigate mode.

how it compares

	tmux	gui managers	herdr
persistent sessions	✓	—	✓
detach / reattach	✓	—	✓
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. gui managers show agent state, but they make you leave your terminal and use their wrapped view. herdr is persistence and awareness in one tool that stays out of your way.

persistence

start herdr on your desktop or server. run your agents, split panes, do your work. press ctrl+b q to detach. close your terminal, close your laptop; your agents keep running. open a new terminal, run herdr, you're back. same session, same panes, same agents.

from anywhere

need to check on your agents from your phone? just ssh in and run herdr. any ssh client works. no app to download, no account to create.

ssh you@yourserver
herdr

same session, same agents, same state.

agent awareness

the sidebar shows which agents are blocked, working, or done. workspaces roll up to their most urgent state so you can scan the full list at a glance.

states:

• 🔴 blocked — agent needs input or approval
• 🟡 working — agent is actively running
• 🔵 done — work finished, you have not looked at it yet
• 🟢 idle — done and seen

detection works by reading foreground process and terminal output. zero config, no hooks required. for agents that expose hooks, the socket api integration gives more robust state reporting.

lives in your terminal

not a gui window, not a web dashboard, not electron. herdr runs inside whatever terminal you already use. single rust binary, no dependencies. works inside tmux.

what you get

• workspaces — organized around git repos or folder names, each with its own tabs and panes
• tabs — first-class in the socket api and cli
• mouse-native — click panes, drag borders, select text to copy; not keyboard-only
• notifications — sounds and toasts for background events; tab-aware suppression
• 9 built-in themes — catppuccin (default), tokyo night, dracula, nord, gruvbox, one dark, solarized, kanagawa, rosé pine
• session persistence — pane processes survive client detach; sessions restore after full restart

agents can use herdr too

the local unix socket lets agents create workspaces, split panes, spawn helpers, read output, and wait for state changes.

# create a workspace and tab
herdr workspace create --cwd ~/project --label "api"
herdr tab create --label "logs"

# split a pane and run
herdr pane split 1-1 --direction right
herdr pane run 1-2 "npm test"

# wait for an agent
herdr wait agent-status 1-1 --status done

# read output
herdr pane read 1-2 --source recent --lines 50

full reference: SOCKET_API.md and SKILL.md.

supported agents

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

agent	idle / done	working	blocked
pi	✓	✓	partial
claude code	✓	✓	✓
codex	✓	✓	✓
droid	✓	✓	✓
amp	✓	✓	✓
opencode	✓	✓	✓

detected but not fully tested: gemini cli, cursor agent, cline, kimi, github copilot cli.

for agents outside the built-in list, herdr still works as a terminal multiplexer with workspaces, panes, and tiling. custom integrations can report agent labels over the socket api. see SOCKET_API.md.

direct integrations

the built-in pi, claude code, codex, and opencode integrations forward semantic state to herdr over the socket api. install with:

herdr integration install pi
herdr integration install claude
herdr integration install codex
herdr integration install opencode

see INTEGRATIONS.md for setup details.

keybindings

press ctrl+b to enter navigate mode.

key	action
n	new workspace
shift+n	rename workspace
shift+d	close workspace
c	new tab
v / -	split pane
x	close pane
b	toggle sidebar
f	fullscreen pane
r	resize mode
q	detach (quit client)

resize mode: h/l resize width, j/k resize height, esc exit.

mouse is supported throughout. full reference: CONFIGURATION.md.

configuration

config file: ~/.config/herdr/config.toml

herdr --default-config   # print full default config

in-app settings screen for theme, sound, and toast preferences. full reference: CONFIGURATION.md.

docs

• CONFIGURATION.md — keybindings, themes, notifications, environment variables
• INTEGRATIONS.md — pi, claude code, codex, opencode integrations
• SKILL.md — reusable agent skill
• SOCKET_API.md — socket protocol and cli reference

building from source

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

testing

just test        # unit tests
just test-all   # full local test suite

license

AGPL-3.0: free to use, modify, and distribute. modified versions must be open-sourced under the same license.