herdr-subagents
Spawn and coordinate subagents as real herdr panes. Use when the user asks to delegate work to subagents — review, implement, research, or parallel tasks — while running inside herdr; when the user says "subagent", "spawn an agent", "delegate to", "parallel agents", "use herdr panes", or wants visible/detachable agent workers. Requires HERDR_ENV=1.
iuhoay · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add iuhoay/skills --skill herdr-subagentsAbout this skill
name: herdr-subagents description: Spawn and coordinate subagents as real herdr panes. Use when the user asks to delegate work to subagents — review, implement, research, or parallel tasks — while running inside herdr; when the user says "subagent", "spawn an agent", "delegate to", "parallel agents", "use herdr panes", or wants visible/detachable agent workers. Requires HERDR_ENV=1. allowed-tools:
- Bash
- Read
- Grep
Herdr Subagents
Subagents are real coding-agent processes running in sibling herdr panes — visible in the TUI, detachable, with herdr tracking their idle/working/blocked state. The parent agent (you) orchestrates them through the herdr CLI.
Guardrail
Before doing anything, verify this agent is inside a herdr-managed pane:
test "${HERDR_ENV:-}" = 1
If the check fails, say you are not running inside herdr and stop. Never control a herdr session you do not own.
How it works
- Each subagent is a separate
piprocess in its own pane, with its own context window and session file. herdr agent startwaits for the subagent to be detected and ready before returning (default 30s timeout).- State (
idle/working/blocked/done) comes from herdr's agent detection, not from guesswork. - The subagent shares your working directory unless you pass a different
--cwdat split time.
Workflow
1. Inspect before spawning
herdr agent list # existing agents and unique names
herdr pane current --current # your own pane id
herdr pane layout --pane "$HERDR_PANE_ID" # pick the right split direction
Agent names must match [a-z][a-z0-9_-]{0,31} and be unique among live agents.
2. Split a sibling pane and start the subagent
Default to a sibling pane in the current tab, current directory, and never steal focus:
herdr pane split --current --direction right --cwd "$PWD" --no-focus
Read the new pane id from .result.pane.pane_id in the JSON response — never guess it. Split a wide pane to the right, a narrow or tall pane down; avoid repeated same-direction splits.
Then start a pi subagent in that pane with a useful name:
herdr agent start reviewer --kind pi --pane <pane-id>
Pass native agent arguments after -- (e.g. a specific model or cwd). If the pane is at a shell prompt and the agent does not appear within the timeout, inspect the pane with herdr pane read <pane-id> --lines 60 before retrying.
3. Submit the task
herdr agent prompt reviewer "<task>" --wait --timeout 120000
--wait blocks until the first settled idle, done, or blocked state. The task prompt must be self-contained: the subagent has its own context and only sees what you tell it, plus the shared filesystem.
Failure mode: a prompt submitted from a non-working state must produce an observed lifecycle change within five seconds, or the CLI returns agent_prompt_stalled instead of waiting. Also, --wait tracks lifecycle state, not individual turns — if the subagent was already working, completion of the active turn may satisfy it. On either symptom, inspect herdr agent read <name> --source recent-unwrapped and re-submit if the prompt never landed; use --until <status> only when you need a specific state.
4. Inspect and collect the result
herdr agent get reviewer # lifecycle state, session file, diagnostics
herdr agent read reviewer --source recent-unwrapped --lines 120
recent-unwrapped joins soft wraps and is the right source for transcripts. If the read ends too early, the subagent's TUI may be on the terminal's alternate screen — rows that leave it never enter herdr's scrollback. Fallback: ask the subagent to write its complete response to a file in a temp directory and reply only with the path, then read that file.
If the agent is blocked, read its output before sending input:
herdr agent read reviewer --source recent-unwrapped --lines 120
herdr agent send-keys reviewer ctrl+c # or esc — only after inspecting
5. Clean up
herdr pane close <pane-id>
Only close panes you created. Never close workspaces, tabs, or panes that existed before, and never run herdr server stop.
Fire-and-forget with callback
For long-running work (watching CI, waits, background research), do not block on --wait. Delegate, end your turn, and let the completion come back to you:
-
Submit the task without
--wait— the call returns immediately, and the task prompt must include the exact callback path (your pane's directory, so the file lands where YOUR watcher listens — see protocol below):herdr agent prompt watcher "watch CI; when it finishes, write the result to ~/.pi/agent/callbacks/$HERDR_PANE_ID/ci.done" -
End your turn and keep serving the user.
-
The subagent writes its completion file. The
herdr-callbacksextension (see Install below) injects it into your session as a user message:[subagent-callback:ci.done] CI passed, 42 tests green -
On that message, collect the result (
herdr agent read watcher --source recent-unwrapped --lines 120) and close the pane.
Callback protocol:
- Every pi instance loads this extension — parent and subagents alike. A shared directory would race: whichever watcher grabs the file first delivers it (possibly to the wrong session) and deletes it. Isolation is per-pane: this extension watches
~/.pi/agent/callbacks/<HERDR_PANE_ID>/in your session, so the file must be written there. Always embed the exact callback path in the task prompt —$HERDR_PANE_IDin the parent shell expands to the parent's pane id, and the subagent inherits the parent's pane id only if you pass it explicitly. - Files are named
<source>.done; the file name identifies the subagent, the content is the message. - Files are one-shot — deleted after delivery. An empty file is retried, so write co