herdr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Herdr

Herdr organizes terminals into workspaces, tabs, and panes, recognizes coding agents running inside panes, and exposes the current session through the

herdr

CLI.

Before issuing any control command, verify that this agent is running inside a Herdr-managed pane:

bash

test "${HERDR_ENV:-}" = 1

If the check fails, say that you are not running inside Herdr and stop. Do not inspect or control the focused Herdr session from outside Herdr.

When the check passes, the

herdr

binary in

PATH

talks to the current session. Use it to inspect neighboring work, create terminal layout, start agents and commands, read output, and wait for state changes.

Herdr将终端组织为工作区、标签页和窗格，识别在窗格内运行的编码Agent，并通过

herdr

CLI暴露当前会话。

在执行任何控制命令之前，请验证当前Agent是否运行在Herdr管理的窗格中：

bash

test "${HERDR_ENV:-}" = 1

如果检查失败，请告知用户当前未运行在Herdr环境中并停止操作。不要从Herdr外部检查或控制已聚焦的Herdr会话。

如果检查通过，

PATH

中的

herdr

二进制文件会与当前会话通信。可使用它来查看相邻任务、创建终端布局、启动Agent和命令、读取输出以及等待状态变更。

Learn the current CLI

了解当前CLI

The installed binary is the authority for command syntax. Start with:

bash

herdr --help

Then print the relevant command group by running the group without a subcommand:

bash

herdr agent
herdr pane
herdr workspace
herdr tab
herdr worktree
herdr terminal
herdr notification
herdr integration
herdr session

Do not run bare

herdr

for discovery; it launches or attaches the TUI. Do not probe a mutating nested command by omitting arguments. Commands such as

herdr workspace create

are valid with defaults and will execute.

Most control commands return JSON. Read identifiers and state from those responses instead of predicting them.

已安装的二进制文件是命令语法的权威来源。从以下命令开始：

bash

herdr --help

然后通过不带子命令的方式运行命令组，查看相关命令组的信息：

bash

herdr agent
herdr pane
herdr workspace
herdr tab
herdr worktree
herdr terminal
herdr notification
herdr integration
herdr session

不要运行裸

herdr

命令来探索功能；它会启动或附加到TUI。不要通过省略参数来尝试可变嵌套命令。诸如

herdr workspace create

的命令在使用默认值时是有效的，并且会直接执行。

大多数控制命令会返回JSON。请从这些响应中读取标识符和状态，而非自行预测。

Understand layout, panes, and agents

理解布局、窗格和Agent

Choose the primitive that matches the job:

Workspace, tab, and pane topology organize terminal locations.
Pane commands control raw terminals, shells, tests, servers, input, and output.
Agent commands control the recognized coding agent currently occupying a pane.

A pane exists whether or not it contains an agent.

agent start

requires an existing available shell pane and never creates, splits, or moves layout. Use pane commands for ordinary processes. Use agent commands when Herdr must validate agent identity or interpret

idle

working

blocked

done

, and

unknown

lifecycle states.

Agent commands accept either a unique live agent name or the pane ID currently hosting that agent. They do not accept terminal IDs or bare agent-kind labels. Names must match

[a-z][a-z0-9_-]{0,31}

and be unique among live agents. A name follows the current pane occupant and is cleared when that agent exits, is released, or is replaced.

idle

means the agent is ready for input and its tab has been seen in the focused Herdr UI.

done

is the same underlying idle state after unseen background work finishes. Focusing the tab or targeting the pane or agent with a focus command marks it seen. CLI reads do not mark it seen.

blocked

means Herdr recognized an approval or question UI.

unknown

means an agent is present but Herdr cannot classify it confidently; it does not prove completion.

选择与任务匹配的基本单元：

工作区、标签页和窗格的拓扑结构用于组织终端位置。
窗格命令用于控制原始终端、Shell、测试、服务器、输入和输出。
Agent命令用于控制当前占用窗格的已识别编码Agent。

无论窗格中是否包含Agent，窗格都存在。

agent start

命令需要一个已有的可用Shell窗格，且不会创建、拆分或移动布局。对于普通进程，请使用窗格命令。当Herdr需要验证Agent身份或解释

idle

、

working

、

blocked

、

done

和

unknown

生命周期状态时，请使用Agent命令。

Agent命令接受唯一的活跃Agent名称或当前托管该Agent的窗格ID。不接受终端ID或裸Agent类型标签。名称必须匹配

[a-z][a-z0-9_-]{0,31}

格式，且在活跃Agent中唯一。名称会跟随当前窗格的占用者，当该Agent退出、被释放或被替换时，名称会被清除。

idle

表示Agent已准备好接收输入，且其标签页已在聚焦的Herdr UI中被查看过。

done

是后台任务完成后，与

idle

相同的底层空闲状态。聚焦标签页或使用聚焦命令定位窗格或Agent会将其标记为已查看。CLI读取操作不会标记为已查看。

blocked

表示Herdr识别到了需要审批或交互的UI。

unknown

表示存在Agent，但Herdr无法可靠地对其进行分类；这并不代表任务已完成。

Use IDs and caller context

使用ID和调用者上下文

Public IDs are opaque stable handles:

workspace:
```
w1
```
tab:
```
w1:t1
```
pane:
```
w1:p1
```

Closed tab and pane IDs are not reused. A pane moved into another workspace receives a new workspace-qualified pane ID. After

pane move

, continue with

.result.move_result.pane.pane_id

or the live agent name. The old value is reported as

.result.move_result.previous_pane_id

; only the moved process's inherited caller context keeps resolving that old ID, so do not use it as a general agent target.

Herdr injects the caller's context into each managed pane:

bash

printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"

Prefer

--current

when a pane command should target the calling pane. Omitting a target may use the UI-focused pane, which can belong to the user or another client.

Discover live state with:

bash

herdr workspace list
herdr tab list --workspace "$HERDR_WORKSPACE_ID"
herdr pane current --current
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
herdr agent list

Creation responses expose the IDs to use next.

workspace create

returns

.result.workspace

.result.tab

, and

.result.root_pane

tab create

returns

.result.tab

and

.result.root_pane

pane split

returns the new pane as

.result.pane

公开ID是不透明的稳定句柄：

工作区：
```
w1
```
标签页：
```
w1:t1
```
窗格：
```
w1:p1
```

已关闭的标签页和窗格ID不会被复用。当窗格被移动到另一个工作区时，会获得一个新的工作区限定窗格ID。执行

pane move

后，请使用

.result.move_result.pane.pane_id

或活跃Agent名称继续操作。旧值会被报告为

.result.move_result.previous_pane_id

；只有被移动进程继承的调用者上下文会继续解析该旧ID，因此不要将其用作通用Agent目标。

Herdr会将调用者的上下文注入每个受管理的窗格：

bash

printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"

当窗格命令需要定位调用者所在窗格时，优先使用

--current

参数。省略目标参数可能会使用UI聚焦的窗格，该窗格可能属于用户或其他客户端。

通过以下命令发现实时状态：

bash

herdr workspace list
herdr tab list --workspace "$HERDR_WORKSPACE_ID"
herdr pane current --current
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
herdr agent list

创建操作的响应会暴露后续要使用的ID。

workspace create

会返回

.result.workspace

、

.result.tab

和

.result.root_pane

。

tab create

会返回

.result.tab

和

.result.root_pane

。

pane split

会返回新窗格的

.result.pane

。

Start and coordinate an agent

启动并协调Agent

Default to a sibling pane in the current tab and the current working directory. Do not create a workspace, tab, worktree, or different cwd unless the user explicitly requests that topology or location.

Honor a direction requested by the user. Otherwise inspect the caller pane:

bash

herdr pane layout --pane "$HERDR_PANE_ID"

Split a wide pane to the right and a narrow or tall pane down. Avoid repeated same-direction splits that create unusably narrow columns or short rows. Keep the user's focus in the calling pane and explicitly preserve the caller's working directory:

bash

herdr pane split --current --direction right --cwd "$PWD" --no-focus

Replace

right

with

down

when appropriate. Read the new pane ID from

.result.pane.pane_id

An available shell pane must be at its interactive prompt, with the shell itself in the foreground and no foreground command, editor, or agent running. Start a supported agent in that pane with a useful unique name:

bash

herdr agent start reviewer --kind codex --pane <returned-pane-id>

Use the kind requested by the user. Run

herdr agent

to inspect the installed kind list and options. Pass native agent arguments only after

--

bash

herdr agent start reviewer --kind codex --pane <returned-pane-id> -- <agent-args...>

agent start

returns only after Herdr detects the expected agent in the same pane and considers it ready for interactive input. It defaults to a 30-second startup timeout.

Submit work through the agent surface:

bash

herdr agent prompt reviewer "Review the current diff and report only actionable findings." --wait --timeout 120000

agent prompt

atomically submits text and encoded Enter while honoring the pane's live bracketed-paste mode. For normal agent work,

--wait

is enough: it waits for the first settled

idle

done

, or

blocked

state. Do not repeat those defaults with

--until

A prompt sent from a non-working state must produce an observed lifecycle change within five seconds. Otherwise Herdr returns

agent_prompt_stalled

instead of waiting indefinitely. This wait tracks lifecycle state, not an individual turn; if the agent is already working, completion of the active turn may satisfy it.

Use

--until

only for a state-specific workflow, such as waiting for an already-running agent to request input:

bash

herdr agent wait reviewer --until blocked --timeout 120000

Without

--until

, standalone

agent wait

uses the same settled-state defaults as

agent prompt --wait

Use logical keys for interactive agent UI controls:

bash

herdr agent send-keys reviewer esc
herdr agent send-keys reviewer ctrl+c

Herdr validates all keys before writing any bytes. Read the result through the resolved agent:

bash

herdr agent get reviewer
herdr agent read reviewer --source recent-unwrapped --lines 120

If a wait fails or returns

blocked

, inspect

agent get

and

agent read

before deciding what input to send. Use the pane surface only when raw terminal control is intentional.

默认在当前标签页的同级窗格中启动，并使用当前工作目录。除非用户明确请求特定拓扑结构或位置，否则不要创建工作区、标签页、工作树或使用不同的工作目录。

遵循用户请求的方向。否则，请检查调用者所在的窗格：

bash

herdr pane layout --pane "$HERDR_PANE_ID"

宽窗格向右拆分，窄窗格或高窗格向下拆分。避免重复同一方向的拆分，以免创建无法使用的窄列或短行。保持用户焦点在调用者所在窗格，并明确保留调用者的工作目录：

bash

herdr pane split --current --direction right --cwd "$PWD" --no-focus

适当时将

right

替换为

down

。从

.result.pane.pane_id

中读取新窗格的ID。

可用的Shell窗格必须处于交互式提示符状态，Shell本身位于前台，且没有前台命令、编辑器或Agent在运行。在该窗格中使用一个有用的唯一名称启动受支持的Agent：

bash

herdr agent start reviewer --kind codex --pane <returned-pane-id>

使用用户请求的Agent类型。运行

herdr agent

查看已安装的类型列表和选项。仅在

--

之后传递原生Agent参数：

bash

herdr agent start reviewer --kind codex --pane <returned-pane-id> -- <agent-args...>

只有当Herdr在同一窗格中检测到预期的Agent并认为其已准备好接收交互式输入时，

agent start

才会返回。它默认设置30秒的启动超时时间。

通过Agent界面提交任务：

bash

herdr agent prompt reviewer "Review the current diff and report only actionable findings." --wait --timeout 120000

agent prompt

会在尊重窗格实时括号粘贴模式的前提下，自动提交文本并模拟按下回车键。对于常规Agent任务，

--wait

参数足够：它会等待第一个稳定的

idle

、

done

或

blocked

状态。不要使用

--until

重复这些默认设置。

从未工作状态发送的提示必须在5秒内产生可观察到的生命周期变更。否则，Herdr会返回

agent_prompt_stalled

，而非无限等待。此等待跟踪的是生命周期状态，而非单个交互回合；如果Agent已经在工作，完成当前交互回合即可满足条件。

仅针对特定状态的工作流使用

--until

，例如等待已运行的Agent请求输入：

bash

herdr agent wait reviewer --until blocked --timeout 120000

如果不使用

--until

，独立的

agent wait

命令会使用与

agent prompt --wait

相同的稳定状态默认设置。

使用逻辑键控制交互式Agent UI：

bash

herdr agent send-keys reviewer esc
herdr agent send-keys reviewer ctrl+c

Herdr会在写入任何字节之前验证所有按键。通过已解析的Agent读取结果：

bash

herdr agent get reviewer
herdr agent read reviewer --source recent-unwrapped --lines 120

如果等待失败或返回

blocked

状态，请先检查

agent get

和

agent read

的结果，再决定发送什么输入。仅当需要原始终端控制时，才使用窗格界面。

Run an ordinary command in another pane

在另一个窗格中运行普通命令

Create a sibling pane with the same geometry rule, preserve the caller's working directory, and keep user focus unchanged:

bash

herdr pane split --current --direction right --cwd "$PWD" --no-focus

Read the new pane ID from

.result.pane.pane_id

, then run and inspect the command:

bash

herdr pane run <returned-pane-id> "just test"
herdr pane wait-output <returned-pane-id> --match "test result" --timeout 120000
herdr pane read <returned-pane-id> --source recent-unwrapped --lines 120

pane run

atomically sends command text and Enter.

pane wait-output

searches the selected snapshot immediately, so output that already exists can match. Use

--match <text>

for a literal substring or

--regex <pattern>

for a Rust regular expression. Omitting

--timeout

allows an indefinite wait.

Use the read source that matches the task:

```
visible
```
: the currently rendered viewport.
```
recent
```
: recent rendered output, including soft wraps.
```
recent-unwrapped
```
: recent output with soft wraps joined; prefer it for logs and transcripts.
```
detection
```
: the plain-text bottom-buffer snapshot used for agent detection.

Use

--format ansi

when colors and terminal styling are evidence. Otherwise use text.

--lines

asks Herdr for more rows from the pane's available screen and host scrollback. If increasing it does not reveal more of a completed response, the pane is probably running the agent on the terminal's alternate screen. Rows that leave the alternate screen do not enter Herdr's host scrollback, so a larger line count cannot recover them.

After that failed read, ask the agent to write its complete response as Markdown in a temporary directory and reply only with the file path, then read the file directly. Use this only as a fallback; do not request file output in the initial prompt.

按照相同的几何规则创建同级窗格，保留调用者的工作目录，并保持用户焦点不变：

bash

herdr pane split --current --direction right --cwd "$PWD" --no-focus

从

.result.pane.pane_id

中读取新窗格的ID，然后运行并检查命令：

bash

herdr pane run <returned-pane-id> "just test"
herdr pane wait-output <returned-pane-id> --match "test result" --timeout 120000
herdr pane read <returned-pane-id> --source recent-unwrapped --lines 120

pane run

会自动发送命令文本并按下回车键。

pane wait-output

会立即搜索选定的快照，因此已存在的输出也可以匹配。使用

--match <text>

匹配字面子字符串，或使用

--regex <pattern>

匹配Rust正则表达式。省略

--timeout

参数会允许无限等待。

选择与任务匹配的读取源：

```
visible
```
：当前渲染的视口。
```
recent
```
：最近渲染的输出，包括软换行。
```
recent-unwrapped
```
：合并软换行后的最近输出；对于日志和记录，优先使用此选项。
```
detection
```
：用于Agent检测的纯文本底部缓冲区快照。

当颜色和终端样式作为证据时，使用

--format ansi

。否则使用文本格式。

--lines

参数会请求Herdr从窗格的可用屏幕和主机回滚缓冲区中获取更多行。如果增加该参数无法显示完整响应的更多内容，那么该窗格可能在终端的交替屏幕上运行Agent。离开交替屏幕的行不会进入Herdr的主机回滚缓冲区，因此更大的行数也无法恢复它们。

如果读取失败，请要求Agent将完整响应以Markdown格式写入临时目录，并仅回复文件路径，然后直接读取该文件。仅将此作为后备方案；不要在初始提示中请求文件输出。

Safety and coordination rules

安全与协调规则

Use
```
--no-focus
```
for background work unless the user asked to switch context.
Use
```
--current
```
, an explicit pane ID, or a unique agent name. Do not rely on another client's focused pane.
Parse IDs from JSON responses. Do not derive them from sidebar order or examples.
Do not close workspaces, tabs, panes, or sessions you did not create unless the user explicitly asked.
Never run
```
herdr server stop
```
from an active session unless the user explicitly intends to stop the server and its pane processes.
Never kill the main Herdr process. Use named test sessions for experiments that need an isolated server.
CLI server errors are JSON on stderr with exit status 1. CLI syntax errors exit with status 2.

除非用户要求切换上下文，否则对后台任务使用
```
--no-focus
```
。
使用
```
--current
```
、明确的窗格ID或唯一的Agent名称。不要依赖其他客户端的聚焦窗格。
从JSON响应中解析ID。不要从侧边栏顺序或示例中推导ID。
除非用户明确要求，否则不要关闭你未创建的工作区、标签页、窗格或会话。
除非用户明确打算停止服务器及其窗格进程，否则不要从活动会话中运行
```
herdr server stop
```
。
永远不要终止主Herdr进程。对于需要隔离服务器的实验，请使用命名测试会话。
CLI服务器错误会以JSON格式输出到stderr，退出状态为1。CLI语法错误的退出状态为2。