herdr-faq

# 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 ```bash 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...