/herdr-faq

name: herdr-faq
description: Launch and drive coding agents (codex, claude, agy) through the Herdr CLI; requires a herdr pane (HERDR_ENV=1). Use before starting or prompting a herdr subagent, and when a herdr command fails or an agent seems stuck or silently lost a prompt.
metadata:
  version: "0.4.1"
  categories: "agents, operations"
  topics: "herdr, troubleshooting, agent-orchestration, terminal-multiplexer"
  upstream: "herdr@0.9.0"
  openclaw:
    homepage: https://github.com/tenequm/skills/tree/main/skills/herdr-faq
    emoji: "🐑"

Herdr FAQ

Launch and drive coding agents through [Herdr](https://herdr.dev) (>= 0.9.0) without losing prompts.

Syntax authority

`herdr --skill` (~13k chars) is the vendor reference: command model, IDs, lifecycle states, prompt and wait mechanics, read sources, safety rules. Read it once per session before your first herdr command - this file assumes it and repeats none of it. For flags, run the command group bare (`herdr agent`, `herdr pane`) or `--help`; never bare `herdr` (it launches the TUI). If a syntax question is not answered here, it is answered there - go get it, never guess a flag.

When this lane

test "${HERDR_ENV:-}" = 1     # never drive herdr from outside a pane

Unset means this shell is not herdr-managed: no `$HERDR_PANE_ID`, no `--current`, and an untargeted command lands on whatever pane the USER has focused. Use acpx instead (acpx-faq). In-session fan-out stays on the harness's own subagent tool.

Invariants

1. **Exit 0 is submission, never completion** - and `send-keys` can return `{"type":"ok"}` for keystrokes that never reach the pane. Confirm by effect: state moved, or the text is visible in the pane. 2. **Screens no detection rule matches read as `idle`.** agy has no idle rule at all, so every agy `idle` is a guess. Read the screen before the first prompt, always. 3. **`agent start` timeout = the child never launched** (bad flag, PATH, or a wrapper process). `pane read` has the real error; `pane process-info` and herdr's own message do not. 4. **`idle` is not "finished".** A claude turn that spawned background shells or a background MCP task ends and reports `idle` while that work runs on; `--wait` tracks lifecycle state, not turns. 5. **The driving harness is a second gate.** Dangerous passthrough flags (`--dangerously-*`, `danger-full-access`) get classifier-blocked, and so can ordinary brief *content* inlined into a shell command. `sleep N; herdr ...` polling is banned - use one backgrounded `prompt`, or wait on a file.

Per kind

Model defaults unless the task argues otherwise: codex `gpt-5.6-sol` at `reasoning_effort high` (set via codex's own flags/config - check `codex --help`), claude `claude-opus-5`, agy `gemini-3.7-flash-medium` (measured on par with Opus for rubric-driven bulk work and far faster; `gemini-3.8-flash-high` measured worse on the same task). One directory per agent, always.

codex

P=$(herdr pane split --current --direction right --cwd "$D" --no-focus | jq -r .result.pane.pane_id)
herdr agent start cx1 --kind codex --pane "$P" --timeout 90000 -- --approve-for-me --no-alt-screen
herdr agent read cx1 --source detection --lines 40        # ALWAYS, before the first prompt
herdr agent prompt cx1 "Carry out $D/brief.md." --wait --timeout 1800000 &

Never `--full-auto`: removed in 0.15x, it surfaces as a bare `timeout` and can wedge the pane in startup-pending. The trust-directory and startup-update dialogs are detected, so an untrusted dir fails fast with `agent_not_ready` rather than eating the first prompt. The one-time post-`integration install` hooks-review gate is NOT detected (WONTFIX) - answer it once per machine. Session ref binds at the first prompt for a fresh start; an explicit `-- resume <id>` is persisted at launch.

claude (alias `claude-code`)

# Pre-trust first - the folder-trust dialog IS detected, so an untrusted dir fails the
# start. Trust is INHERITED: a new dir under an already-trusted parent needs nothing.
CFG=/tmp/agentcfg; mkdir -p "$CFG"                        # isolated from your real config
printf '{"projects":{"%s":{"hasTrustDialogAccepted":true}}}' "$D" > "$CFG/.claude.json"

P=$(herdr pane split --current --cwd "$D" --no-focus --env CLAUDE_CONFIG_DIR="$CFG" \
    | jq -r .result.pane.pane_id)
herdr agent start cl1 --kind claude --pane "$P" --timeout 90000 -- --model claude-opus-5
herdr agent read cl1 --source detection --lines 40        # ALWAYS, before the first prompt
herdr agent prompt cl1 "Carry out $D/brief.md." --wait --timeout 1800000 &

• **The safe key differs per dialog.** The folder-trust dialog puts the cursor on

`No, exit`, so a bare `enter` kills the agent - send `down enter`. The Bash-permission dialog puts the cursor on `1. Yes`.

• **`idle` lies in a specific way here.** Background *shells* end the turn and report

`idle` while they run; background *agents* and *MCP tasks* keep it `working`, and a background MCP task can hold `idle` for its whole 3-10 minute life.

• **Grey next-prompt-suggestion text reads as real unsubmitted text** in a plain

read - disambiguate with `--format ansi` (the suggestion carries the dim attribute `ESC[2m`).

• Session ref binds at launch. A Claude Code UI update can break detection

(`herdr server update-agent-manifests`). Native-launcher installs run under a version-string process herdr cannot identify: launch via `HERDR_AGENT=claude exec <path>`, then `agent rename`.

• Under a different `CLAUDE_CONFIG_DIR` the agent loads its **own** skills. Confirm

they are current *before its first turn* - a running session has already snapshotted the old text.

agy (aliases `antigravity`, `antigravity-cli`)

Thinnest detection of the three: no idle rule at all (invariant 2), and nothing in the pre-flight is recoverable once the agent is up.

D=/abs/dir/for/this/agent                   # ONE dir per agent - agy reads si