Herdr（herdrdev 出品，Apache-2.0，约 3.3 万星）是编码 agent 的"终端运行时"：把 tmux 式的持久会话、工作区/工作树管理、agent/终端面板、远程主机接入整合成一个本地 server + CLI。它不像 ruflo 那样给你编排逻辑，而是给你一个 agent 常驻的终端环境——会话不丢、工作树不乱、多 agent 各占一窗格。

一句话：你的 coding agent 住在 herdr 里，而不是每次临时开个终端。

这个工具解决什么问题：多个 Agent 会话在终端里各干各的，没有统一的面板和管理。Herdr 是面向编码 Agent 的终端运行时：持久会话、工作区/worktree 管理、Agent 面板与集成（session/workspace/worktree/tab/notification/agent/pane/integration/server/config/channel/api）。

什么时候用：

• 你要持久会话（herdr --session main），退出后还能附着回来；
• 你要在终端里管多个工作区/worktree；
• 你要一个 Agent 面板/通知面统一看各 Agent 状态。

什么时候别用：单会话、不需要后台 server 与状态管理时——完整客户端会拉起后台进程。

注意事项：重档条目——启动完整客户端会拉起后台 server（socket + 日志 + session 文件）；Rust 单二进制，无运行时依赖。

note: release 二进制（本环境实测，gh-proxy 加速）；国内 GitHub 直连慢必须加速

# 来源: Trove 详细指南 · 验证于 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

预期输出: herdr 0.8.2

第 1 步：确认命令与配置面正常

讲解：status 与 config check 是本工具的两个自检入口——status 看版本与 server 状态，config check 校验配置；两者都过，说明客户端环境是好的。

# 来源: Trove 详细指南 · 验证于 2026-08-28
herdr status
herdr config check

预期输出: 版本 0.8.2 + channel stable + server 状态；config: ok

卡住怎么办：

• status 异常 → 看输出里的 socket 路径与日志位置；
• config check 报错 → 按提示修正配置（默认配置即可通过）。

第 2 步：确认会话能进（可选，会拉起后台 server）

讲解：能进入 --session main 的持久会话终端面，说明二进制到运行链路全部通；退出后记得用 herdr server stop 停掉常驻 server。

# 来源: Trove 详细指南 · 验证于 2026-08-28
herdr --session main

预期输出: 进入持久会话终端面（首次运行创建 ~/.config/herdr/ + ~/.local/state/herdr/）

卡住怎么办：

• 会话起不来 → 先跑 status/config check 看环境；
• server 常驻想停 → herdr server stop。

它怎么工作：Rust 单二进制（22.7MB，Linux x86_64），release 资产 gh-proxy 下载即用。herdr status/config check 不拉起 server；herdr --session main 进入持久会话终端面（首次运行创建 ~/.config/herdr/ + ~/.local/state/herdr/agent-detection/，退出会话 server 可能常驻）；herdr server stop 停后台 server。

关键概念：

• server：后台进程（socket + 日志 + session 文件）；
• session：持久会话（--session 指定名字）；
• 子命令面：session/workspace/worktree/tab/notification/agent/pane/integration/server/config/channel/api。

装完它动哪里：~/.config/herdr/ + ~/.local/state/herdr/（启动会话后创建）。

实测命令 = release 二进制下载（2026-08-28 本环境验证，v0.8.2，gh-proxy 加速；GitHub 直连慢）；Rust 单二进制，无运行时依赖；启动完整客户端会拉起后台 server（~/.config/herdr/ 下 socket + 日志 + session.json，~/.local/state/herdr/agent-detection/ 下 agent 清单）；tmux 类终端面（session/workspace/worktree/tab/pane）；有 herdr server stop 停止面

第 1 步：装二进制（为什么 gh-proxy：国内 GitHub 直连慢，实测路径）

讲解：单二进制下载 + chmod 即用，无运行时依赖。国内 GitHub 直连慢，下载地址统一走 gh-proxy 前缀。装完 --version 验证。

# 来源: Trove 详细指南 · 验证于 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

预期输出: herdr 0.8.2

装好确认：

• --version 输出 0.8.2；
• herdr --help 能看到完整子命令面。

卡住怎么办：

• 下载超时 → 确认网络能到 gh-proxy；换网络（校园网/代理切换）重试；
• 想全局用 → 把二进制放到 PATH（如 /usr/local/bin）。

第 2 步：状态与配置检查（不拉起 server）

讲解：status 看客户端版本 + channel + server 状态（not running 时给出 socket 路径）；config check 校验配置（无 config.toml 也通过——首次运行以默认配置为准）。这两条先跑，确认环境再进会话。

# 来源: Trove 详细指南 · 验证于 2026-08-28
herdr status

预期输出: client 版本 0.8.2 + channel stable + server 状态（not running 时给出 socket 路径）

# 来源: Trove 详细指南 · 验证于 2026-08-28
herdr config check

预期输出: config: ok（无 config.toml 时也通过——首次运行以默认配置为准）

装好确认：

• status 正常输出版本与 server 状态；
• config check 输出 config: ok。

卡住怎么办：

• status 异常 → 看输出里的 socket 路径与日志位置；
• config check 报错 → 按提示修正配置（默认配置即可通过）。

第 3 步：进持久会话（会拉起后台 server）

讲解：herdr --session main 进入持久会话终端面。首次运行创建配置与状态目录；退出会话后 server 可能常驻，不用时 herdr server stop。

# 来源: Trove 详细指南 · 验证于 2026-08-28
herdr --session main

预期输出: 进入持久会话终端面（首次运行创建 ~/.config/herdr/ + ~/.local/state/herdr/agent-detection/；退出会话 server 可能常驻）

装好确认：

• 进入会话终端；
• 退出后 herdr status 显示 server 状态。

卡住怎么办：

• 会话起不来 → 先跑 status/config check 看环境；
• server 常驻想停 → herdr server stop。

启动与入口

• 会话：herdr --session <名字>；
• 状态：herdr status；
• 后台 server：herdr server stop 停止。

常用操作

操作一：查看命令面（本环境实测）

# 来源: Trove 详细指南 · 验证于 2026-08-28
herdr --help

预期输出: session/workspace/worktree/tab/notification/agent/pane/integration/server/config/channel/api 等子命令

操作二：状态检查（本环境实测；不拉起 server）

# 来源: Trove 详细指南 · 验证于 2026-08-28
herdr status

预期输出: client 版本 0.8.2 + channel stable + server 状态（not running 时给出 socket 路径）

操作三：配置校验（本环境实测）

# 来源: Trove 详细指南 · 验证于 2026-08-28
herdr config check

预期输出: config: ok（无 config.toml 时也通过——首次运行以默认配置为准）

操作四：启动/附着持久会话（会拉起后台 server）

# 来源: Trove 详细指南 · 验证于 2026-08-28
herdr --session main

预期输出: 进入持久会话终端面（首次运行创建 ~/.config/herdr/ + ~/.local/state/herdr/agent-detection/；退出会话 server 可能常驻）

操作五：停止后台 server

# 来源: Trove 详细指南 · 验证于 2026-08-28
herdr server stop

预期输出: server stopped（通过 socket API）

数据与目录

• 配置：~/.config/herdr/；
• 状态/agent 检测：~/.local/state/herdr/。

与工具页矩阵同源，共 19 对（6 实测兼容 / 13 推断可能兼容 / 0 推断可能冲突）；完整对子、状态与证据见 冲突对子（共装矩阵）。

• 暂无独立排障手册；安装/卸载问题先看 Agent 执行版 guide 注意事项

# 来源: Trove 详细指南 · 验证于 2026-08-28
rm -f /usr/local/bin/herdr ~/.local/bin/herdr; rm -rf ~/.config/herdr ~/.local/state/herdr

note: 单二进制删除（按实际安装路径）；专属目录自动删；运行中的 server 先停

# 来源: Trove 详细指南 · 验证于 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'

预期输出: herdr removed: OK

• 运行环境预检（Linux x86_64；无运行时依赖）
• 官方 release 二进制（本环境实测，gh-proxy 加速）；国内 GitHub 直连慢必须加速
• 每条操作 = 一个命令块 + 预期输出
• 单二进制删除（按实际安装路径）；专属目录自动删；运行中的 server 先停
• 重档条目：启动会拉起后台 server（socket + 日志 + session 文件），用后 herdr server stop

• 问：为什么退出会话后 server 还在？答：持久会话设计——server 可能常驻；不用时 herdr server stop。
• 问：下载慢？答：用安装段的 gh-proxy 前缀；官方 install.sh（herdr.dev）未实测。
• 问：和别的工具冲突吗？答：冲突矩阵无对子——专属目录写面，不碰 ~/.claude.json 等共享注册面。
• 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。

• 版本：[0.8.2, 0.8.2] 锁定（收录实测版本）。
• 环境：Linux x86_64；无运行时依赖；/usr/local/bin 可写（或放用户 PATH）。
• 网络：GitHub 直连慢，必须 gh-proxy 前缀（实测路径）；官方 install.sh 走 herdr.dev（未实测）。
• 写面：~/.config/herdr/ + ~/.local/state/herdr/（启动会话后创建）。
• 后台进程：完整客户端会拉起 server（socket + 日志 + session 文件）。
• 共装：冲突矩阵无对子（专属目录写面，与常用工具不重叠）；组合包 combo-governance-stack / combo-env-init 均有其成员位。

• 条目签名：herdrdev/herdr（Apache-2.0，原样收录 v0.8.2 二进制）

• 实测：实测记录（本地留存）（2026-08-28，release 二进制下载 + version/help/status/config check 冒烟）。
• 未实测：持久会话与 server 启动（会拉起后台进程，未在本环境长跑）；官方 install.sh（herdr.dev）。

第三方教学未逐条实测，仅供学习；有出入以本页与官方文档为准。

• 官方文档：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