用 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>。
日常使用
从项目目录启动 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+qdetach，让后台任务继续运行。
稍后在同一台机器上再次运行 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 restart | workspace、tab、pane、cwd、布局和焦点；符合条件的原生 agent session 可恢复 | 任意 shell、测试、服务器或其他进程继续存活 |
herdr update --handoff | 尝试跨 server replacement 保留 pane PTY、进程、agent identity 和持久 metadata | 进行中的请求 、流、消息或瞬时协调状态 |
普通 herdr update 默认使用常规停止和重启流程。只有显式添加 --handoff 才会尝试 live handoff。即使 integration 能恢复对话，也不代表任意进程会被复活。
多代理使用边界
推荐把 Herdr 当作终端控制面：
- 一个 workspace 对应一个明确项目或任务；
- 一个 writer 对应一个 checkout 或 worktree；
- 用 Pi、Codex 或
agy的项目规则限制各自范围； - 让 Herdr 提供状态、布局、detach 和重新连接；
- 用 Git diff、测试和独立 review 判断工作是否完成。
如果侧栏状态不对，先运行 herdr integration status，确认代理确实在 Herdr pane 中启动，并检查 integration 是否以同一用户安装。随后可按官方 agent 命令说明使用 herdr agent list 和 herdr agent explain <target> --json 查看检测依据。