跳到主要内容

用 Herdr 管理 Pi、Codex 与 Antigravity CLI 工作区

Herdr 是面向 AI 编程代理的终端工作区管理器。后台 server 持有真实终端进程，客户端关闭、detach 或 SSH 断开后，pane 里的任务仍可继续运行。它还会识别 pane 中的代理，并在侧栏汇总 working、blocked、done、idle 等状态。

Herdr 适合解决“多个终端和代理在哪里、现在是什么状态、怎样重新接上”的问题。它不负责代码隔离、权限审批或 Git 所有权。并行写代码时仍应让每个 writer 使用独立 worktree。

工作区如何划分​

按照官方的概念模型，可以这样分层：

  • session 是独立的后台 server 命名空间。多数人使用默认 session 即可；
  • workspace 对应一个仓库、任务或调查；
  • tab 把 agents、logs、server 等视图分开；
  • pane 是真实终端，可以运行 shell、代理、测试或服务；
  • agent 是 Herdr 在 pane 中识别出的进程。

这种组织方式把终端布局和代码所有权分开。Herdr 可以在一个 workspace 中展示三个代理，但不能阻止它们同时覆盖同一文件。

安装并接入三个代理​

官方安装说明给出的 Linux 和 macOS 直接安装方式如下：

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

按照官方integration 安装列表，为已安装的 CLI 添加对应 integration：

herdr integration install pi
herdr integration install codex
herdr integration install antigravity-cli
herdr integration status

根据 Herdr 的integration 说明，三者上报的信息并不相同：

代理integration 的作用状态从哪里来
Pi上报生命周期状态和原生会话引用Pi extension 直接上报
Codex CLI上报 session identity，供重启后恢复Herdr 的屏幕检测
Antigravity CLI首次 prompt 后上报 conversation ID，供重启后恢复Herdr 的屏幕检测

Antigravity CLI 的 hook 在 PreInvocation 触发。新开的 agy pane 至少要发送一次 prompt，Herdr 才能记录该 conversation。恢复时 Herdr 使用 agy --conversation <id>。

2026-10-01 补充。 从 0.9.2（9 月 29 日）起，不在上表里的代理也可以自己向 Herdr 报告恢复命令，server 重启后 Herdr 会用这条命令重新打开同一个会话，不再需要内置集成；代理回到空闲 shell 后，这条记录会被清除。代理作者可参考接入指南。当前稳定版是 0.9.3，修复了以 Escape 开头的终端快捷键。

日常使用​

从项目目录启动 Herdr，再在不同 pane 中运行代理：

cd ./repository
herdr

# 分别在 pane 中运行
pi
codex
agy

初次使用可以只靠鼠标：点击 pane 或 tab 切换，拖动边界调整 split，右键打开操作菜单。需要键盘时，键盘指南规定默认 prefix 为 ctrl+b；按下后松开，再按 ? 可查看当前生效的快捷键。官方入门动作包括：

  • prefix+v 向右 split；
  • prefix+minus 向下 split；
  • prefix+c 新建 tab；
  • prefix+q detach，让后台任务继续运行。

稍后在同一台机器上再次运行 herdr 即可重新连接。要真正停止默认后台 session，使用官方 CLI reference 中的 herdr server stop：

herdr server stop

远程使用时，最简单的方式是先 SSH 到目标机，再在远程 shell 中运行 Herdr。官方远程工作说明也支持经 SSH 连接的本地薄客户端，例如 SSH config 中的 herdr --remote workbox，或显式目标 herdr --remote ssh://you@server:2222。认证与主机校验仍由 SSH 负责，不需要把 Herdr 的本地 socket 暴露到网络。

哪些状态会保留​

Session state 文档区分了以下几种容易混淆的恢复行为：

场景会保留什么不会保证什么
客户端 detach 后重新连接pane 进程、布局、最近屏幕内容和对话客户端本身的临时 UI 状态
普通 server restartworkspace、tab、pane、cwd、布局和焦点；符合条件的原生 agent session 可恢复任意 shell、测试、服务器或其他进程继续存活
普通 herdr update兼容的 endpoint-generation-1 server 及其 pane 进程继续运行更旧的 server 可能需要停止；新的 server 端功能需要更新 server
herdr update --handoff尝试跨 server replacement 保留 pane PTY、进程、agent identity 和持久 metadata进行中的请求、流、消息或瞬时协调状态

按照更新说明，普通 herdr update 会安装新二进制文件，并让兼容的 endpoint-generation-1 server 及其 pane 进程继续运行。用更新后的客户端重新连接即可；server 端的变更要等之后重启 server 或执行受支持的 handoff 才会生效。endpoint generation 1 之前的 server 在更新时需要最后停止一次。Live handoff 仍是实验性功能，必须显式添加 --handoff 才会尝试，包管理器更新不会执行它。恢复代理对话仍不等于复活任意进程。

多代理使用边界​

推荐把 Herdr 当作终端控制面：

  1. 一个 workspace 对应一个明确项目或任务；
  2. 一个 writer 对应一个 checkout 或 worktree；
  3. 用 Pi、Codex 或 agy 的项目规则限制各自范围；
  4. 让 Herdr 提供状态、布局、detach 和重新连接；
  5. 用 Git diff、测试和独立 review 判断工作是否完成。

如果侧栏状态不对，先运行 herdr integration status，确认代理确实在 Herdr pane 中启动，并检查 integration 是否以同一用户安装。随后可按官方 agent 命令说明使用 herdr agent list 和 herdr agent explain <target> --json 查看检测依据。

来源与工具定义​

探索关联

相关讨论 (4)

被引用 (4)

同主题的其他笔记 (25)

打开关联网络