---
name: plannotator-tui
description: Open a Markdown plan or document for the human to review and annotate in a Herdr pane; their feedback arrives as your next message. Use when you have written a plan, spec, or design document that needs human review before you act on it. Draft; not yet wired into an installer.
---

# plannotator-tui: hand a document to the human for review

Only when `HERDR_ENV=1` (you are running inside Herdr). Otherwise tell the human where the
file is and ask them to review it.

1. Write the document to a file. Do not paste it into chat as well.
2. Open it for review, from your own pane:

   ```bash
   plannotator-tui herdr open docs/plans/auth.md
   ```

   plannotator-tui opens beside you (or wherever the user configured it), already knowing that
   feedback comes back to this pane.
3. **End your turn.** Do not wait, poll, or read the pane. The review arrives as the next
   user message, as numbered feedback:

   ```
   # Annotations on docs/plans/auth.md

   ## Annotation 1 (line 12)
   Comment on: "Rotate the token on every…"
   > Rotation on every privilege change will log people out…
   ```

   Address every item, then continue.

When you list files you want the human to open, print them as `file://` hyperlinks (OSC 8)
so Ctrl-click in Herdr opens them in plannotator-tui:

```bash
printf '\e]8;;file://%s\e\\%s\e]8;;\e\\\n' "$PWD/docs/plans/auth.md" "docs/plans/auth.md"
```

If `plannotator-tui` is not on `PATH`, the raw Herdr command is:

```bash
herdr plugin pane open --plugin annotate --entrypoint doc --placement split \
  --direction right --target-pane "$HERDR_PANE_ID" --focus --cwd "$PWD" \
  --env PLANNOTATOR_TUI_FILE="$PWD/docs/plans/auth.md" --env PLANNOTATOR_TUI_DELIVER_TO="$HERDR_PANE_ID"
```