SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsgrok-pi-herdr-orchestration

grok-pi-herdr-orchestration

Agents & models

View repository

Updated 10-21 12:40

About this skill

Herdr + grok-pi subagent orchestration

This skill puts grok-pi into a new tab/pane managed by Herdr, and uses shell scripts to submit prompts, read terminal status, wait for completion, and clean up. It is "visible PTY orchestration," not treating the TUI as an ordinary stdout pipe.

Key constraints

  1. Do not wait without staying connected. After creating a subagent or submitting a prompt, you must immediately enter wait/run polling. The default polling interval is 5 seconds, the maximum allowed is 60 seconds, and never use a single sleep。
  2. Prefer using run。 run to complete creation, submission, polling, and output within the same command, to avoid the main agent forgetting to track after creation.
  3. Read-only by default. The script by default only exposes read,grep,find,ls. Only when the user explicitly requests code modifications should you explicitly expose write-related tools via --tools , and you still need to check periodically.
  4. Each task gets its own tab. Do not reuse the user's existing pane; the script creates its own tab and saves tab_id、pane_id and the running status to ~/.local/state/grok-pi-herdr/(can be overridden with GROK_PI_HERDR_STATE_DIR ).
  5. Completion judgment must have evidence. idle can only indicate that the current pane has no work indicator; the final report should also read the most recent output to confirm there is an answer or a clear error.blocked、exited and timeouts must not be reported as success.
  6. Do not treat grok-pi as an ordinary headless CLI. grok-pi --print-capabilities indicates that it internally uses Pi JSONL RPC, but grok-pi itself is responsible for the TUI/PTY; in Herdr, driving it via pane send-text + pane send-keys is the most stable. Do not directly pipe the user prompt to grok-pi 's stdin.

Do an environment check first

herdr --version
grok-pi --version
herdr status --json
herdr api snapshot

You must confirm that the Herdr server is running. When you need to understand the protocol boundaries, run:

grok-pi --print-capabilities  # 注意：正确命令是 grok-pi，不是 grok

The output should include Pi JSONL RPC over stdio、bridge: pi-grok-adapter -> ACP and prompt/get_state and other RPC commands. This result is only for research and does not change the orchestration approach: the current skill reads visible progress through the Herdr PTY.

Script location

~/.pi/agent/skills/grok-pi-herdr-orchestration/scripts/herdr-grok-pi.sh

For ease of copying, it is denoted below as $RUNNER：

RUNNER="$HOME/.pi/agent/skills/grok-pi-herdr-orchestration/scripts/herdr-grok-pi.sh"

Recommended: one-shot research task

Put the complete task after -- , and the script will start a read-only grok-pi in a new tab and continuously poll until it finishes:

"$RUNNER" run \
  --cwd "$PWD" \
  --label "仓库结构研究" \
  --model grok-4.3 \
  --thinking high \
  --timeout 1800 \
  --output /tmp/grok-pi-research.txt \
  -- \
  '只读研究当前仓库：梳理模块、入口、调用关系和风险。不要修改文件。完成后给出有文件路径依据的结构化报告。'

run 's output path is the terminal text actually read from the Herdr pane, not the assumed response from the model API. The success condition is that the command exit code is 0 and there is a final answer in the output; the timeout exit code is 124, andblocked/exited is non-zero.

Staged control

1. Create

run_id=$("$RUNNER" start \
  --cwd "$PWD" \
  --label "探索代理" \
  --model grok-4.3 \
  --thinking high)
printf 'run_id=%s\n' "$run_id"

start is only responsible for starting and waiting for the TUI to be ready; after it returns, it does not mean the task is complete. After it returns, you must immediately submit the prompt and start wait, and you must not sleep for a long time between the two commands or end this round of work.

2. Submit the task and wait

"$RUNNER" prompt "$run_id" \
  '只读阅读 README、入口文件和相关配置，输出研究结论及证据路径。不要写文件。'
"$RUNNER" wait "$run_id" --timeout 1800

wait Each check:

  • Whether the foreground process of the Herdr pane (grok-pi/pi-rpc) still exists;
  • Whether the most recent pane output shows Thinking、Waiting for response、Responding and other work indicators;
  • Whether there are blocking prompts such as user selection/approval;
  • Whether it has already returned to the input prompt when there is no working indicator.

3. Check progress at any time

"$RUNNER" status "$run_id"
"$RUNNER" read "$run_id" 120

status Output JSON, where state is working、idle、blocked or exited. During long tasks, the main agent should perform status or wait polling no later than every 60 seconds; if it needs to report to the user, read recent_output, and do not judge progress based only on the process existing.

4. Stop and clean up

"$RUNNER" stop "$run_id"

The script first sends ctrl+q, then closes the tab it created itself, and marks the state file as stopped. Do not close or take over other tabs.

Orchestration choices

Task Method Default permissions
Repository reconnaissance, architecture research, read-only review run read,grep,find,ls
Multi-round research, requiring follow-up questions start + prompt + wait read,grep,find,ls
The user explicitly requests that the subagent modify code start --tools ..., then in stages prompt/wait Only explicitly specified
Long tasks that need to be canceled Save run_id，status after stop Do not expand permissions

If it is explicitly intended for the subagent to write code, use the minimal tool set, for example:

run_id=$("$RUNNER" start \
  --cwd "$PWD" \
  --label "实现代理" \
  --tools read,grep,find,ls,bash,edit,write)
"$RUNNER" prompt "$run_id" '先检查现状并提出计划；得到用户确认后再修改。'
"$RUNNER" wait "$run_id" --timeout 1800

Do not open bash/edit/writeby default, and do not treat --always-approve as a necessary condition for research tasks.

Troubleshooting

  • herdr status shows that the server is not running: first start Herdr, confirm that herdr status --json 's server.running is true, then retry.
  • grok-pi exits immediately after startup: run grok-pi --version, check authentication and herdr pane read <pane>; do not repeatedly create a large number of tabs.
  • The status is blocked: read the pane output and explain to the user what approval/input is needed; do not poll indefinitely to mask the blockage.
  • The status is exited: keep the state file and the pane's last output, and report the reason for exit; do not treat "the process ended" as "the research succeeded".
  • Only the TUI is visible with no agent record: this is possible. If extensions were disabled at startup, Herdr will not receive the Pi lifecycle hook; this skill can still monitor through the pane process/output. Do not switch to the user's existing agent pane because of this.
  • Incomplete output: use read RUN_ID 500 or specify run --output PATH, and keep the output file path in the final report.

Final report format

After completion, report to the user:

  1. run_id, cwd, and the model/thinking level used;
  2. The last observed status and whether polling complied with the <=60 second constraint;
  3. Research conclusions and key evidence paths;
  4. Output file paths (if any);
  5. If it is blocked、exited, timeout, or incomplete output, mark it clearly; do not package it as success.