herdr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Herdr

Herdr is terminal orchestration, not native agent-to-agent communication or shared memory. Agents call the

herdr

CLI, which controls panes through Herdr's local socket. This works across Pi, Codex, Claude Code, Cursor CLI, and other terminal agents. Native integrations only improve detection, status accuracy, and session restoration.

Herdr是终端编排工具，而非原生Agent间通信或共享内存工具。Agent通过调用

herdr

CLI，借助Herdr的本地套接字来控制窗格。它适用于Pi、Codex、Claude Code、Cursor CLI及其他终端Agent。原生集成仅能提升检测能力、状态准确性和会话恢复功能。

Preconditions

前置条件

The controlling agent must run inside Herdr in Ghostty. Verify access and workspace scope:

bash

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

If either fails, do not pretend to access other agents; tell the user the agent must be launched inside Herdr.

One-time installation:

bash

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

控制Agent必须在Ghostty的Herdr内部运行。请验证访问权限和工作区范围：

bash

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

如果任一验证失败，请勿假装可以访问其他Agent；请告知用户该Agent必须在Herdr内部启动。

一次性安装命令：

bash

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

CLI workflow

CLI 工作流

bash

undefined

bash

undefined

Discover pane IDs in this workspace; never guess them

发现当前工作区中的窗格ID；请勿猜测

herdr pane list --workspace "$HERDR_WORKSPACE_ID"

Read the target's recent context

读取目标的近期上下文

herdr pane read <pane-id> --source recent-unwrapped --lines 120

Send a prompt and press Enter

发送提示并按下回车

herdr pane run <pane-id> "Check the failing tests and report back."

Wait for completion; use idle instead if that integration reports idle

等待完成；如果集成支持idle状态，则改用idle

herdr wait agent-status <pane-id> --status done --timeout 120000

Read the result

读取结果

herdr pane read <pane-id> --source recent-unwrapped --lines 120


Stay inside the current workspace. Read before messaging; for inspection-only requests, send nothing. After messaging, wait for `done`, `idle`, or `blocked`, then read the output again. Never assume the prompt was acted on.

Do not close, rename, move, resize, or reconfigure panes you did not create. Do not create or close panes unless the user explicitly asks. “Use the Herdr skill” means execute these CLI operations, not merely explain them.

herdr pane read <pane-id> --source recent-unwrapped --lines 120


请保持在当前工作区内操作。发送消息前先读取内容；对于仅需检查的请求，请勿发送任何消息。发送消息后，等待状态变为`done`、`idle`或`blocked`，然后再次读取输出内容。请勿假设提示已被执行。

请勿关闭、重命名、移动、调整大小或重新配置非你创建的窗格。除非用户明确要求，否则请勿创建或关闭窗格。“使用Herdr技能”意味着执行这些CLI操作，而非仅仅解释它们。

Sharp edges (empirically verified)

注意事项（经验证）

Hard-won facts from driving herdr in production. Trust these over intuition.

这些是在生产环境中使用Herdr总结出的重要结论，请优先遵循这些规则而非凭直觉操作。

Sessions & targeting

会话与目标定位

Always append
```
--session <name>
```
to every command. The
```
HERDR_SESSION
```
env var alone silently falls back to whatever server is already running.
Destructive ops only via
```
herdr session stop <name>
```
/
```
herdr session delete <name>
```
(explicit positional name). Never
```
herdr server stop
```
— it acts on whatever server is ambient.
Target shape is
```
<session>:<pane-id>
```
; the pane id itself contains a colon (
```
w1:p2
```
). Split on the FIRST colon only.
A bare CLI call does not auto-start a server. Start headless with
```
herdr server --session <name>
```
.
Every herdr-managed process gets
```
HERDR_ENV=1
```
and
```
HERDR_PANE_ID
```
. Inside nested tmux,
```
$TMUX
```
wins — treat that pane as tmux.

请始终在每个命令后追加
```
--session <name>
```
。仅依赖
```
HERDR_SESSION
```
环境变量会静默回退到当前运行的任意服务器。
仅通过
```
herdr session stop <name>
```
/
```
herdr session delete <name>
```
执行破坏性操作（需明确指定会话名称）。切勿使用
```
herdr server stop
```
——它会作用于当前运行的任意服务器。
目标格式为
```
<session>:<pane-id>
```
；窗格ID本身包含冒号（如
```
w1:p2
```
）。请仅按第一个冒号进行拆分。
直接调用CLI不会自动启动服务器。请使用
```
herdr server --session <name>
```
启动无头服务器。
每个由Herdr管理的进程都会获得
```
HERDR_ENV=1
```
和
```
HERDR_PANE_ID
```
。在嵌套的tmux中，
```
$TMUX
```
优先级更高——请将该窗格视为tmux窗格。

Sending input

发送输入

```
pane send-text
```
types but does NOT submit — follow with
```
pane send-keys <pane> enter
```
.
```
pane run
```
= text + Enter in one call.
```
pane run
```
is reliable into a shell prompt, but TUI agent composers (Claude Code, Cursor CLI) treat its text+Enter burst as a paste and swallow the Enter — text sits typed but unsubmitted. To message a TUI agent:
```
send-text
```
, sleep ~1s, then a separate
```
send-keys <pane> enter
```
.
C0 control bytes (e.g. ASCII 0x1f) are consumed as terminal control actions and can erase already-typed text. For invisible markers use U+2063 INVISIBLE SEPARATOR — it travels as text.
Slash commands open an autocomplete popup; the first Enter may only close the popup or fill an argument placeholder, not submit.
```
escape
```
dismisses the popup and keeps the text.
Never verify a submit by "pane content changed". Confirm via native agent status flipping to
```
working
```
/
```
blocked
```
after Enter.

```
pane send-text
```
仅输入文本但不提交——需后续执行
```
pane send-keys <pane> enter
```
。
```
pane run
```
= 输入文本+回车一步完成。
```
pane run
```
在shell提示符下是可靠的，但TUI Agent编辑器（如Claude Code、Cursor CLI）会将其文本+回车的连续输入视为粘贴操作并忽略回车——文本已输入但未提交。要向TUI Agent发送消息：先执行
```
send-text
```
，等待约1秒，再单独执行
```
send-keys <pane> enter
```
。
C0控制字节（如ASCII 0x1f）会被当作终端控制操作消耗，可能会删除已输入的文本。如需使用不可见标记，请使用U+2063不可见分隔符——它会作为文本传输。
斜杠命令会打开自动补全弹窗；第一次回车可能仅关闭弹窗或填充参数占位符，而非提交。
```
escape
```
会关闭弹窗并保留文本。
请勿通过“窗格内容已更改”来验证提交是否成功。请通过Enter后原生Agent状态切换为
```
working
```
/
```
blocked
```
来确认。

Reading panes

读取窗格

```
pane read --lines N
```
returns COMPLETELY EMPTY output when N is smaller than the pane's viewport height. Always request >=200 lines and trim locally (
```
tail -n N
```
).
```
pane get
```
```
.cwd
```
is frozen at pane creation. Use
```
.foreground_cwd
```
for the live working directory.
```
pane read --format ansi
```
preserves styling. Ghost/placeholder composer text (rotating suggestions, hints) renders dim (SGR-2) or dark truecolor; real typed input renders normal. This is the only reliable way to tell an empty composer from a human draft.

当N小于窗格视口高度时，
```
pane read --lines N
```
会返回完全空的输出。请始终请求至少200行，然后在本地修剪（如
```
tail -n N
```
）。
```
pane get
```
```
.cwd
```
的值在窗格创建时就固定了。请使用
```
.foreground_cwd
```
获取实时工作目录。
```
pane read --format ansi
```
会保留样式。Ghost/占位符编辑器文本（轮换建议、提示）会以暗淡（SGR-2）或深色真彩色显示；实际输入的文本会以正常样式显示。这是区分空编辑器和人工草稿的唯一可靠方法。

Agent state

Agent状态

```
herdr agent get <pane>
```
reports
```
working
```
/
```
idle
```
/
```
done
```
/
```
blocked
```
/
```
unknown
```
— native detection, better than regex-guessing.
Known gap: status reads
```
idle
```
during a long-running foreground tool call (the model finished its turn; the tool is still grinding). Corroborate an
```
idle
```
verdict with pane text (busy banners like "esc to interrupt") before treating a pane as free or stale.

Blocking waits exist:

herdr agent wait <pane> --status <s> --timeout MS

and

herdr wait output <pane> --match <text>

Push events over the socket (protocol >=16):
```
pane.agent_status_changed
```
,
```
pane.output_matched
```
. Use as the fast path; keep polling as the backstop.
Any script can register itself as an agent via
```
pane report-agent
```
and report idle/working/blocked.

```
herdr agent get <pane>
```
会报告
```
working
```
/
```
idle
```
/
```
done
```
/
```
blocked
```
/
```
unknown
```
——这是原生检测，比正则猜测更准确。
已知缺陷：在长时间运行的前台工具调用期间，状态会显示为
```
idle
```
（模型已完成其轮次，但工具仍在运行）。在将窗格视为空闲或失效前，请结合窗格文本（如“esc to interrupt”等忙碌提示）来确认
```
idle
```
状态的准确性。

支持阻塞等待：

herdr agent wait <pane> --status <s> --timeout MS

和

herdr wait output <pane> --match <text>

。

套接字推送事件（协议版本>=16）：
```
pane.agent_status_changed
```
、
```
pane.output_matched
```
。请将其作为快速路径；将轮询作为后备方案。
任何脚本都可以通过
```
pane report-agent
```
注册为Agent，并报告idle/working/blocked状态。

Workspace / tab lifecycle

工作区/标签页生命周期

NO label uniqueness anywhere: workspaces and tabs can share labels. Do your own duplicate checks; find-by-label adopts the first match. An unlabeled workspace displays its cwd basename as its label — a real collision hazard (once caused an adapter to kill a live agent pane it wrongly adopted).
```
workspace create
```
seeds one default tab labeled
```
1
```
. Closing a workspace's LAST tab deletes the workspace. Closing a tab's only pane closes the tab.
```
--no-focus
```
is respected on workspace/tab create, except the very first workspace in an empty session (always focuses).
```
pane split --no-focus
```
still shrinks the host tab's viewport — the flag governs focus, not geometry.
Workspace/tab/pane IDs and labels survive a server restart within a named session. The processes and agent registrations do NOT — panes return as husks (fresh shell,
```
agent get
```
reports
```
agent_not_found
```
). Close-and-replace husks; don't treat them as live duplicates.

任何地方都不保证标签唯一性：工作区和标签页可以共享相同的标签。请自行检查重复项；按标签查找会采用第一个匹配项。未标记的工作区会将其当前工作目录的基名显示为标签——这存在实际冲突风险（曾导致适配器错误地终止了它错误识别的活跃Agent窗格）。
```
workspace create
```
会创建一个标记为
```
1
```
的默认标签页。关闭工作区的最后一个标签页会删除该工作区。关闭标签页的唯一窗格会关闭该标签页。
在创建工作区/标签页时，
```
--no-focus
```
参数会被遵守，但空会话中的第一个工作区除外（始终会获得焦点）。
```
pane split --no-focus
```
仍会缩小宿主标签页的视口——该参数控制焦点，而非几何尺寸。
在命名会话中，工作区/标签页/窗格的ID和标签在服务器重启后会保留。但进程和Agent注册不会保留——窗格会变为空壳（全新shell，
```
agent get
```
会报告
```
agent_not_found
```
）。请关闭并替换空壳窗格；不要将它们视为活跃的重复项。

Misc

其他

```
tput cols
```
inside a script launched via
```
pane run
```
reports a stale default (80). Never trust it for layout math.
For risky experiments use an isolated named session (never
```
default
```
), and re-check
```
herdr session list --json
```
immediately before any stop/delete.
```
herdr integration install <harness>
```
(claude, codex, cursor, pi, ...) enables native status detection per agent.
```
herdr notification show <title>
```
fires a desktop-style alert.

通过
```
pane run
```
启动的脚本内，
```
tput cols
```
会报告过时的默认值（80）。请勿依赖它进行布局计算。
进行风险实验时，请使用独立的命名会话（切勿使用
```
default
```
），并在执行任何stop/delete操作前立即重新检查
```
herdr session list --json
```
。
```
herdr integration install <harness>
```
（claude、codex、cursor、pi等）可为每个Agent启用原生状态检测。
```
herdr notification show <title>
```
会触发桌面样式的提醒。

Launching agents in new panes (when the user asks)

在新窗格中启动Agent（当用户要求时）

ALWAYS launch agents with auto-approval — a worker in an unattended pane stalls forever on a y/n prompt nobody answers:

Cursor CLI:
```
cursor-agent --yolo "task"
```
(alias for
```
--force
```
)
Codex CLI:
```
codex --yolo "task"
```

Claude Code:

claude --dangerously-skip-permissions "task"

This is safe only if a global agent guardrails deny-list hook is installed across all agents. First-run trust dialogs may still appear despite these flags — peek the pane after launch.

herdr integration install <cursor|codex|claude>

(once each) enables native agent-status detection.

NEVER verify a launch with

sleep N && pane read

— that is a non-herdr antipattern. Use the native waits:

herdr agent wait <pane> --status working --timeout MS

(agent picked up the task) or

herdr wait output <pane> --match <text>

, then read the pane.

请始终以自动批准模式启动Agent——无人值守窗格中的Worker会因无人应答y/n提示而永久停滞：

Cursor CLI:
```
cursor-agent --yolo "task"
```
（
```
--force
```
的别名）
Codex CLI:
```
codex --yolo "task"
```

Claude Code:

claude --dangerously-skip-permissions "task"

仅当所有Agent都安装了全局Agent防护禁用列表钩子时，此操作才是安全的。即使使用这些标志，首次运行的信任对话框仍可能出现——启动后请查看窗格内容。

herdr integration install <cursor|codex|claude>

（每个Agent执行一次）可启用原生Agent状态检测。

切勿使用

sleep N && pane read

来验证启动是否成功——这是非Herdr的反模式。请使用原生等待：

herdr agent wait <pane> --status working --timeout MS

（Agent已接手任务）或

herdr wait output <pane> --match <text>

，然后读取窗格内容。

Cursor CLI specifics

Cursor CLI 特定说明

The real binary is

cursor-agent

(

agent

is an alias/new docs name — don't rely on it in scripts). The user's shorthand

cur

cursor-agent --yolo

: fine to type into an interactive pane, but use the full binary in scripts — aliases don't expand there. Launch into an existing pane:

bash

herdr pane run <pane-id> "cd <worktree> && cursor-agent --model gpt-5.3-codex-high --yolo 'fix the failing tests'"

Interactive:

cursor-agent "task"

(or no arg for empty session). Headless:

cursor-agent -p "task" --output-format text|json|stream-json

Permissions:
```
--force
```
runs commands without per-command approval (alias
```
--yolo
```
);
```
--sandbox enabled|disabled
```
. Auth for scripts:
```
CURSOR_API_KEY
```
env var.
Model:
```
--model <slug>
```
at launch,
```
/model
```
in-session. Enumerate with
```
cursor-agent --list-models
```
— slugs are version/account-dependent, never hardcode from memory.
Reasoning effort: there is NO
```
--effort
```
flag — effort is baked into the slug suffix:
```
-low
```
/
```
-medium
```
/
```
-high
```
/
```
-xhigh
```
(e.g.
```
gpt-5.3-codex-xhigh
```
,
```
claude-opus-4-8-thinking-high
```
).
```
-fast
```
is speed, not effort. Bracket syntax
```
model[effort=high]
```
shown in
```
--help
```
is NOT actually supported — always use full slugs.
Known bug (mid-2026): some CLI builds silently drop the reasoning suffix passed via
```
--model
```
and fall back to default effort. Verify with
```
/model
```
after launch;
```
--disable-auto-update
```
keeps a working build stable.

Resume:

cursor-agent resume

(latest),

--resume <chatId>

cursor-agent ls

to list.

真实的二进制文件是

cursor-agent

（

agent

是别名/新文档名称——请勿在脚本中依赖它）。用户的简写

cur

cursor-agent --yolo

：在交互式窗格中输入是可行的，但在脚本中请使用完整的二进制文件名——别名不会在脚本中展开。在现有窗格中启动：

bash

herdr pane run <pane-id> "cd <worktree> && cursor-agent --model gpt-5.3-codex-high --yolo 'fix the failing tests'"

交互式：

cursor-agent "task"

（或无参数启动空会话）。无头模式：

cursor-agent -p "task" --output-format text|json|stream-json

。

权限：
```
--force
```
会无需逐命令批准即可运行命令（别名
```
--yolo
```
）；
```
--sandbox enabled|disabled
```
。脚本认证：使用
```
CURSOR_API_KEY
```
环境变量。
模型： 启动时使用
```
--model <slug>
```
，会话内使用
```
/model
```
。可通过
```
cursor-agent --list-models
```
枚举模型——slug依赖于版本/账号，切勿凭记忆硬编码。
推理力度： 没有
```
--effort
```
标志——力度已内置在slug后缀中：
```
-low
```
/
```
-medium
```
/
```
-high
```
/
```
-xhigh
```
（例如
```
gpt-5.3-codex-xhigh
```
、
```
claude-opus-4-8-thinking-high
```
）。
```
-fast
```
代表速度，而非力度。
```
--help
```
中显示的括号语法
```
model[effort=high]
```
实际上不受支持——请始终使用完整的slug。
已知bug（2026年年中）： 部分CLI版本会静默丢弃通过
```
--model
```
传递的推理后缀，并回退到默认力度。启动后请通过
```
/model
```
验证；
```
--disable-auto-update
```
可保持可用版本的稳定性。
恢复会话：
```
cursor-agent resume
```
（恢复最近会话）、
```
--resume <chatId>
```
、
```
cursor-agent ls
```
列出会话。

Prompt patterns

提示模板

Inspect: “Use the Herdr skill. Inspect every agent in this workspace, read its recent output, and summarize its task and status. Do not send anything.”
Ask: “Use Herdr to find the testing agent, read its context, ask whether the test suite passes, wait for its response, and report back.”
Coordinate: “Act as lead agent. Inspect all agents, share missing context, prevent duplicate work, wait for results, and give me one combined summary.”

检查： “使用Herdr技能。检查此工作区中的所有Agent，读取其近期输出，总结其任务和状态。请勿发送任何消息。”
询问： “使用Herdr找到测试Agent，读取其上下文，询问测试套件是否通过，等待其回复并反馈结果。”
协调： “作为主Agent，检查所有Agent，共享缺失的上下文，避免重复工作，等待结果，并向我提供一份合并后的总结。”

Direct shortcuts

快捷方式

Most defaults use the

Ctrl+B

prefix. Prefer direct

Ctrl+Alt

shortcuts, which rarely conflict. Add to

~/.config/herdr/config.toml

toml

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

Apply changes:

bash

herdr server reload-config

To keep prefixed shortcuts but change the prefix, set

prefix = "ctrl+a"

under

[keys]

大多数默认快捷方式使用

Ctrl+B

前缀。建议使用直接的

Ctrl+Alt

快捷方式，它们很少冲突。请将以下内容添加到

~/.config/herdr/config.toml

：

toml

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

应用更改：

bash

herdr server reload-config

如果要保留带前缀的快捷方式但更改前缀，请在

[keys]

下设置

prefix = "ctrl+a"

。