Herdr (by herdrdev, Apache-2.0, ~33k stars) is a "terminal runtime" for coding agents: merges tmux-style persistent sessions, workspace/worktree management, agent/terminal panes and remote-host access into one local server + CLI. Unlike ruflo, it does not give you orchestration logic; it gives you a terminal environment where agents live — sessions don't get lost, worktrees stay tidy, and multiple agents each get their own pane.

In one sentence: your coding agent lives inside herdr instead of spawning a temporary terminal every time.

You want persistent sessions on top of agent CLIs: keep several workspaces/worktrees alive, switch between them, get notifications — herdr is a persistent multi-session manager for agent CLIs: sessions, workspaces, worktrees, tabs, notifications, agent/pane/integration. The two things people trip on: the binary download from GitHub direct is slow on mainland networks (use the gh-proxy prefix), and after you exit a session the server may keep running (stop it with herdr server stop).

When to use it:

• Managing several persistent sessions/workspaces/worktrees for agent CLIs;
• Background agent runs with notifications;
• Needing a session terminal surface that survives reconnects.

When not to use it: one-off single commands — a plain shell is enough; the control plane itself starts a background server.

note: why gh-proxy: mainland GitHub direct is slow, verified path

# Source: Trove detailed guide · verified 2026-08-28
curl -sL -o herdr https://gh-proxy.com/https://github.com/herdrdev/herdr/releases/download/v0.8.2/herdr-linux-x86_64
chmod +x herdr
./herdr --version

Expected output: herdr 0.8.2

Step 1: Confirm the command and config surface

Why: status and config check are this tool's two self-checks — status shows version and server state, config check validates config; both passing means the client environment is fine.

# Source: Trove detailed guide · verified 2026-08-28
herdr status
herdr config check

Expected output: version 0.8.2 + channel stable + server state; config: ok

Stuck? How to recover:

• status abnormal → look at the socket path and log locations in the output;
• config check errors → fix config as prompted (defaults pass).

Step 2: Confirm a session can be entered (optional, starts the background server)

Why: being able to enter the --session main persistent session terminal means the binary-to-runtime path is fully working; remember to stop the resident server with herdr server stop after exit.

# Source: Trove detailed guide · verified 2026-08-28
herdr --session main

Expected output: enters the persistent session terminal surface (first run creates ~/.config/herdr/ + ~/.local/state/herdr/)

Stuck? How to recover:

• session won't start → run status/config check first to inspect the environment;
• server resident, want it stopped → herdr server stop.

Single binary (Linux x86_64, no runtime deps): download + chmod and it works. herdr --session main enters a persistent session terminal surface; first run creates ~/.config/herdr/ (config) + ~/.local/state/herdr/ (state/agent detection); after exiting, the server may stay resident (socket + logs + session files), stopped via herdr server stop.

Key concepts:

• session: persistent session terminal surface (herdr --session <name>);
• server: background process started by the full client (socket API);
• config check: validates config (passes even without config.toml — first run uses defaults).

Where it writes: ~/.config/herdr/ + ~/.local/state/herdr/ (created after starting a session).

Measured command = release binary download (verified in this environment 2026-08-28, v0.8.2, gh-proxy accelerated; direct GitHub slow); Rust single binary, no runtime deps; starting the full client launches a background server (socket + logs + session.json under ~/.config/herdr/, agent manifests under ~/.local/state/herdr/agent-detection/); tmux-like terminal surface (session/workspace/worktree/tab/pane); stop surface exists via herdr server stop

Step 1: Install the binary (why gh-proxy: mainland GitHub direct is slow, verified path)

Why: single binary download + chmod, no runtime deps. Mainland GitHub direct is slow, so download URLs use the gh-proxy prefix. Verify with --version after install.

# Source: Trove detailed guide · verified 2026-08-28
curl -sL -o herdr https://gh-proxy.com/https://github.com/herdrdev/herdr/releases/download/v0.8.2/herdr-linux-x86_64
chmod +x herdr
./herdr --version

Expected output: herdr 0.8.2

After install, confirm:

• --version prints 0.8.2;
• herdr --help shows the full subcommand surface.

Stuck? How to recover:

• download timeout → confirm the network can reach gh-proxy; switch networks (campus/proxy) and retry;
• want it globally → put the binary on PATH (e.g. /usr/local/bin).

Step 2: Status and config check (does not start the server)

Why: status shows client version + channel + server state (prints a socket path when not running); config check validates config (passes even without config.toml — first run uses defaults). Run these two first to confirm the environment before entering sessions.

# Source: Trove detailed guide · verified 2026-08-28
herdr status

Expected output: client version 0.8.2 + channel stable + server state (prints socket path when not running)

# Source: Trove detailed guide · verified 2026-08-28
herdr config check

Expected output: config: ok (passes even without config.toml — first run uses defaults)

After install, confirm:

• status prints version and server state normally;
• config check prints config: ok.

Stuck? How to recover:

• status abnormal → look at the socket path and log locations in the output;
• config check errors → fix config as prompted (defaults pass).

Step 3: Enter a persistent session (starts the background server)

Why: herdr --session main enters a persistent session terminal surface. First run creates config and state directories; after exiting, the server may stay resident — use herdr server stop when not in use.

# Source: Trove detailed guide · verified 2026-08-28
herdr --session main

Expected output: enters the persistent session terminal surface (first run creates ~/.config/herdr/ + ~/.local/state/herdr/agent-detection/; server may stay resident after exit)

After install, confirm:

• you enter the session terminal;
• after exit, herdr status shows the server state.

Stuck? How to recover:

• session won't start → run status/config check first to inspect the environment;
• server resident, want it stopped → herdr server stop.

Startup and entry

• Sessions: herdr --session <name>;
• Status: herdr status;
• Background server: stop with herdr server stop.

Common operations

Operation 1: View the command surface (verified here)

# Source: Trove detailed guide · verified 2026-08-28
herdr --help

Expected output: session/workspace/worktree/tab/notification/agent/pane/integration/server/config/channel/api subcommands

Operation 2: Status check (verified here; does not start the server)

# Source: Trove detailed guide · verified 2026-08-28
herdr status

Expected output: client version 0.8.2 + channel stable + server state (prints socket path when not running)

Operation 3: Config validation (verified here)

# Source: Trove detailed guide · verified 2026-08-28
herdr config check

Expected output: config: ok (passes even without config.toml — first run uses defaults)

Operation 4: Start/attach a persistent session (starts the background server)

# Source: Trove detailed guide · verified 2026-08-28
herdr --session main

Expected output: enters the persistent session terminal surface (first run creates ~/.config/herdr/ + ~/.local/state/herdr/agent-detection/; server may stay resident after exit)

Operation 5: Stop the background server

# Source: Trove detailed guide · verified 2026-08-28
herdr server stop

Expected output: server stopped (via socket API)

Data and directories

• Config: ~/.config/herdr/;
• State/agent detection: ~/.local/state/herdr/.

Same source as the tool-page matrix — 19 pairs total (6 measured compatible / 13 inferred possibly compatible / 0 inferred possibly conflicting); full pairs, states and evidence: Conflict pairs (co-install matrix).

• No standalone handbook yet; for install/uninstall issues first see the agent-executable guide notes

# Source: Trove detailed guide · verified 2026-08-28
rm -f /usr/local/bin/herdr ~/.local/bin/herdr; rm -rf ~/.config/herdr ~/.local/state/herdr

note: remove the single binary (per actual install path); own directories auto-deleted; stop a running server first

# Source: Trove detailed guide · verified 2026-08-28
herdr server stop 2>/dev/null || true
rm -f /usr/local/bin/herdr ~/.local/bin/herdr
rm -rf ~/.config/herdr ~/.local/state/herdr
command -v herdr >/dev/null 2>&1 && echo '残留: herdr 仍存在' || echo 'herdr removed: OK'

Expected output: herdr removed: OK

• Runtime preflight (Linux x86_64; no runtime dependencies)
• Official release binary (measured here, gh-proxy accelerated); direct GitHub from China is slow and must be accelerated
• Each operation = one command block + expected output
• Single binary removed (per actual install path); dedicated directories auto-removed; stop a running server first
• Heavy entry: startup launches a background server (socket + logs + session files); run herdr server stop after use

• Q: Why is the server still there after exiting a session? A: persistent-session design — the server may stay resident; use herdr server stop when not in use.
• Q: Download slow? A: use the gh-proxy prefix from the install section; the official install.sh (herdr.dev) is not tested.
• Q: Conflicts with other tools? A: no conflict-matrix pairs — own-directory write surface, does not touch shared registration surfaces like ~/.claude.json.
• Q: Where to report problems? A: install/uninstall issues on this marketplace go through the entry feedback channel; project issues go to the author's repository.

• Version: [0.8.2, 0.8.2] locked (verified collection version).
• Environment: Linux x86_64; no runtime deps; /usr/local/bin writable (or put it on the user PATH).
• Network: GitHub direct slow, must use the gh-proxy prefix (verified path); official install.sh goes through herdr.dev (not tested).
• Write surface: ~/.config/herdr/ + ~/.local/state/herdr/ (created after starting a session).
• Background process: the full client starts a server (socket + logs + session files).
• Co-install: no conflict-matrix pairs (own-directory write surface, no overlap with common tools); member of combos combo-governance-stack / combo-env-init.

• Verified: local repro log (2026-08-28, release binary download + version/help/status/config check smoke).
• Not tested: persistent sessions and server startup (starts a background process, not long-run here); official install.sh (herdr.dev).

Third-party tutorials are not individually verified; check against this page and official docs.

• 官方文档：herdr.dev/agent-guide.md（概念模型 / 首次运行 / 键盘 / 配置 / 诊断） [官方文档 · herdr 官方 · 2026-08-30（v0.8.2）]
  官方专为 Agent 写的教学文档——概念模型五件套（Session=后台 server 命名空间 / Workspace=项目容器 / Tab=布局 / Pane=真实终端、分离后继续运行 / Agent=面板内被识别的进程，状态 working/blocked/done/idle/unknown）+ 三种模式（terminal/prefix/navigate）；首次运行走查 6 步（herdr 启动→面板里起 agent→鼠标操作→分割面板 prefix+v/prefix+-/prefix+c→prefix+q 分离→herdr server stop 全停）；键盘（prefix=ctrl+b，prefix+? 看全部绑定，[keys] 可配置）；配置（~/.config/herdr/config.toml，herdr --default-config 打印默认，herdr server reload-config 热重载）；诊断食谱（herdr agent list / herdr agent explain <target> --json / herdr status server|client / 日志位置）
• 官方 README：install 与启动语义（安装方式矩阵 / herdr 启动 / ctrl+b q 分离） [官方文档 · herdr 官方 · 2026-08-30（v0.8.2）]
  安装四路径——curl install.sh（Linux/macOS）/ brew install herdr / mise use -g herdr / Windows PowerShell install.ps1（含 endpoint 受限时 cmd 版）；`herdr` 在项目目录启动（后台持久会话，自动建 workspace），`ctrl+b q` 分离（后台继续跑），再 `herdr` 重连
• 官方文档：Herdr SKILL 安装（给 coding agent 装 herdr 控制技能） [官方文档 · herdr 官方 · 2026-08-30（v0.8.2）]
  `npx skills add herdrdev/herdr --skill herdr -g`（open skills CLI 给支持的 agent 装 herdr 控制技能；无技能系统的 agent 用 GitHub 副本加进全局自定义指令）；SKILL.md 教 agent 分割面板/不抢焦点跑命令/读输出/等别的 agent