herdr-faq

# Herdr FAQ Launch and drive coding agents through [Herdr](https://herdr.dev) (>= 0.9.0) without losing prompts. Command semantics: `herdr --skill` (the binary ships its own current doc and is the tiebreaker for any dispute with this file). This file covers only what goes wrong and the recipes that avoid it. Read the Invariants, then go straight to your agent's section in **Per kind** - each one is a complete launch-to-first-prompt recipe. Everything after that is shared reference: Launch for pane and name mechanics, Shapes for composing commands, Drive for the turn loop, Failures for triage. ## Invariants 1. **Exit 0 is submission, never completion.** `agent prompt` writes text and Enter as one ordered submission and reports success only after both land - that still does not prove a turn started. `send-keys` proves nothing at all: it 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 spawns background shells or a background MCP task ends and reports `idle` while that work run...