herdr

Herdr

Herdr 的 CLI 通过本地套接字控制终端窗格；它既不提供原生 Agent 间通信，也不提供共享内存。它适用于 Pi、Codex、Claude Code、Cursor CLI 和其他终端 Agent。原生集成可改善检测效果、状态准确性和会话恢复能力。

前置条件

在 Ghostty 中通过 Herdr 运行控制 Agent。验证访问权限和工作区范围：

test "${HERDR_ENV:-}" = "1"
test -n "${HERDR_WORKSPACE_ID:-}"

如果任一项验证失败，请告知用户必须在 Herdr 中启动此 Agent；不要声称可以访问其他 Agent。

一次性安装：

npx skills add ogulcancelik/herdr --skill herdr -g

检查、发送消息、等待、读取

为每条 Herdr 命令追加 --session <name>。单独使用 HERDR_SESSION 可能会悄悄选中一个已运行的服务。查找窗格 ID；切勿猜测。

herdr pane list --workspace "$HERDR_WORKSPACE_ID" --session <name>
herdr pane read <pane-id> --source recent-unwrapped --lines 200 --session <name>

# For TUI agent composers, separate text from Enter
herdr pane send-text <pane-id> "Check the failing tests and report back." --session <name>
sleep 1
herdr pane send-keys <pane-id> enter --session <name>

# Confirm submission, then wait for completion (idle if the integration uses it)
herdr agent wait <pane-id> --status working --timeout 120000 --session <name>
herdr agent wait <pane-id> --status done --timeout 120000 --session <name>
herdr pane read <pane-id> --source recent-unwrapped --lines 200 --session <name>

留在当前工作区。先读取再发送消息；对于仅检查的请求，不要发送任何内容。按下 Enter 后，通过原生状态转换为 working/blocked 来确认提交，切勿仅凭窗格内容发生变化来确认。等待状态变为 done、idle 或 blocked，然后再次读取；不要假定提示词已被执行。按照下文所述，通过窗格文本核实 idle 状态。

协调 Agent 时，补充缺失的上下文，避免重复工作，并返回一份合并后的摘要。

不要关闭、重命名、移动、调整大小或重新配置你未创建的窗格。仅在用户明确要求时创建或关闭窗格。“使用 Herdr 技能”意味着执行 CLI 工作流，而不只是解释它。

操作详情

会话和目标

• 对于破坏性操作，使用命名的 herdr session stop <name> / herdr session delete <name>。切勿使用 herdr server stop；它会操作当前服务器。
• 目标格式为 <session>:<pane-id>。窗格 ID 中包含冒号（w1:p2）；只在第一个冒号处分割。
• CLI 调用不会自动启动服务。使用 herdr server --session <name> 以无头模式启动。
• 受管理的进程会收到 HERDR_ENV=1 和 HERDR_PANE_ID。在嵌套 tmux 中，$TMUX 的优先级更高：将该窗格视为 tmux。
• 进行有风险的实验时，使用隔离的命名会话，切勿使用 default。在停止或删除前，立即重新检查 herdr session list --json --session <name>。

输入

• pane send-text 只输入文本，不会提交。pane run 会发送文本并按下 Enter，在 shell 提示符下可正常工作，但 TUI 编辑器（Claude Code、Cursor CLI）可能会将 Enter 视为粘贴内容的一部分。对于 TUI，请分别调用 send-text、暂停约 1 秒，然后调用 send-keys <pane> enter。
• C0 控制字节（例如 ASCII 0x1f）会触发终端操作，并可能擦除已输入的文本。不可见文本标记请使用 U+2063 INVISIBLE SEPARATOR。
• 斜杠命令自动补全可能会占用第一次 Enter 来关闭弹窗或填入参数占位符。使用 escape 可在保留文本的同时关闭弹窗。

读取和状态

• 如果 N 小于视口高度，pane read --lines N 会返回空输出。请求至少 200 行，且不少于视口高度；然后在本地使用 tail -n N 裁剪。
• pane get 的 .cwd 在创建时固定；.foreground_cwd 则实时更新。
• 使用 pane read --format ansi 区分占位文本和人工草稿：建议文本为暗淡色（SGR-2）或深色真彩色；输入内容则正常显示。纯文本无法可靠地区分两者。
• herdr agent get <pane> 会报告原生的 working/idle/done/blocked/unknown 状态；优先使用它，而不是基于正则表达式进行猜测。长时间运行的前台工具仍可能报告 idle；在将窗格视为空闲或过期之前，请检查“esc to interrupt”等忙碌横幅。
• 原生等待命令：herdr agent wait <pane> --status <s> --timeout MS、herdr wait agent-status <pane> --status <s> --timeout MS 和 herdr wait output <pane> --match <text>。
• 套接字协议 >=16 提供 pane.agent_status_changed 和 pane.output_matched 事件。优先使用事件，并以轮询作为后备方案。
• 脚本可通过 pane report-agent 注册，并报告 idle/working/blocked 状态。

工作区和标签页生命周期

• 标签并非唯一。请自行检查重复项；按标签查找时会采用第一个匹配项。未标记的工作区会显示其 cwd 的基本名称，这可能与显式标签冲突。
• workspace create 会创建标签页 1。关闭最后一个标签页会删除工作区；关闭标签页唯一的窗格会关闭该标签页。
• 创建工作区/标签页时会遵循 --no-focus，但空会话中的第一个工作区除外。pane split --no-focus 仍会缩小宿主视口：焦点和几何布局是相互独立的。
• 命名会话重启后会保留 ID 和标签，但不会保留进程或 Agent 注册信息。恢复的窗格是全新的 shell（agent_not_found），并非仍在运行的副本；只能在上述窗格权限范围内关闭并替换它们。

其他细节

• 不要在通过 pane run 启动的脚本中使用 tput cols 进行布局；它可能会报告过时的默认值 80。
• herdr integration install <harness>（claude、codex、cursor、pi 等）可启用原生状态检测。herdr notification show <title> 会显示提醒。

仅在用户提出要求时启动 Agent

始终使用自动批准模式启动 Agent — 否则，无人值守的工作进程可能会卡在等待未响应的提示上：

• Cursor CLI：cursor-agent --yolo "task"（--force 的别名）
• Codex CLI：codex --yolo "task"
• Claude Code：claude --dangerously-skip-permissions "task"

这依赖于已在各个 Agent 中安装适当的拒绝列表钩子。首次运行时仍可能出现信任对话框；启动后请检查窗格。每个集成只需安装一次，即可启用原生状态检测。

使用 herdr agent wait <pane> --status working --timeout MS 或 herdr wait output <pane> --match <text> 验证是否成功启动，然后读取输出。切勿使用 sleep N && pane read 验证启动；上文提到的短暂输入提交等待用于其他目的。

Cursor CLI

在脚本中使用 cursor-agent。agent 是一个别名/新文档中的名称；David 的交互式 cur 简写会展开为 cursor-agent --yolo，但别名不会在脚本中展开。

在向现有 shell 窗格启动之前，使用 cursor-agent --list-models 查找可用的模型 slug：

herdr pane run <pane-id> "cd <worktree> && cursor-agent --model <verified-model-slug> --yolo 'fix the failing tests'" --session <name>

• 交互模式： cursor-agent "task"，或不带参数以启动空会话。无头模式： cursor-agent -p "task" --output-format text|json|stream-json。
• 权限： --force / --yolo 可跳过逐命令批准；--sandbox enabled|disabled 用于控制沙盒。脚本认证：CURSOR_API_KEY。
• 模型： 启动时使用 --model <slug>，会话内使用 /model。Slug 因版本/账户而异；切勿凭记忆编造。
• 推理强度： 没有 --effort 标志。请使用以 -low、-medium、-high 或 -xhigh 结尾的完整 slug（例如 gpt-5.3-codex-xhigh、claude-opus-4-8-thinking-high）。-fast 控制速度，而非推理强度。尽管 --help 有此说明，model[effort=high] 并不受支持。
• 某些构建版本会静默丢弃 --model 的推理后缀。启动后使用 /model 验证；--disable-auto-update 可保留可正常工作的构建版本。
• 恢复会话： cursor-agent resume（最新会话）、--resume <chatId>，或使用 cursor-agent ls 列出会话。

直接快捷键

大多数默认快捷键使用 Ctrl+B。直接使用 Ctrl+Alt 的快捷键很少发生冲突。添加到 ~/.config/herdr/config.toml：

[keys]
new_workspace = "ctrl+alt+n"
workspace_picker = "ctrl+alt+w"
goto = "ctrl+alt+g"
new_tab = "ctrl+alt+c"

使用以下命令应用：

herdr server reload-config --session <name>

若要保留带前缀的快捷键但更换前缀，请在 [keys] 下设置 prefix = "ctrl+a"。