plannotator/herdr-annotate

What is herdr‑annotate?

herdf‑annotate is a Rust‑based plugin for the Herdr terminal/AI‑agent environment. It lets you:

• Select any terminal output and turn it into a numbered Markdown annotation that can be sent to the active LLM agent.
• Review whole Markdown documents or the agent’s previous replies in a TUI powered by the companion project plannotator‑tui.
• Manage, copy, archive, or paste those annotations directly into the agent’s prompt, all from within Herdr.

In short, it bridges the gap between the raw text you see in the terminal and the feedback loop of an LLM‑powered assistant.

---

Key Features

Feature	Description
Full vs. Lite install	Full adds document‑review UI; Lite only provides terminal‑text annotation.
Keyboard‑driven workflow	Bindings like prefix+a (capture), prefix+ctrl+s (send & archive), prefix+o (open folder review) let you stay in the terminal.
Markdown feedback format	Annotations are emitted as ## Annotation N blocks with workspace/tab metadata and quoted source text – ready for LLM consumption.
Clipboard‑aware	Uses system clipboard on macOS/Linux (wl‑clipboard, xclip, xsel) and PowerShell on Windows; also emits OSC 52 for remote sessions.
Agent‑agnostic	Works with Claude Code, Codex, pi, Copilot CLI, Droid, Hermes CLI, OpenCode, etc.
Remote‑session support	Can be invoked over SSH or herdr --remote without needing a local keypress, by calling herdr plugin action invoke annotate.capture.
Links add‑on	Optional add‑on to make Ctrl‑click on file://*.md links open them in the plannotator‑tui reviewer.
Cross‑platform	macOS, Linux, Windows (preview Full variant).

---

Installation

# Full install (default) – includes document review UI
herdr plugin install plannotator/herdr-annotate

# Lite install – only terminal annotation
herdr plugin install plannotator/herdr-annotate/lite

# Windows Full (preview) – requires Herdr ≥ 0.9.0
herdr plugin install plannotator/herdr-annotate/windows-full

The command downloads a pre‑built herdr-annotate binary, verifies its SHA‑256 checksum, and registers it as a Herdr plugin. No additional runtime is needed.

---

Basic Usage (Full install)

Key	Action
prefix+a	Capture selected terminal text as an annotation.
prefix+shift+a	Copy all annotations (Markdown) to clipboard.
prefix+ctrl+a	Copy and archive all annotations.
prefix+ctrl+v	Paste annotations into the focused agent’s prompt (no send).
prefix+ctrl+s	Send annotations as the next agent message and archive them.
prefix+m	Open the annotation manager (list, copy, archive, delete).
prefix+o	Open the folder‑wide document reviewer (plannotator‑tui).
prefix+shift+o	Review the agent’s most recent reply.
prefix+ctrl+o	Review the newest reply without a picker.

The manager pane shows annotations in the order they were created, ensuring the LLM receives feedback sequentially.

---

Document Review (Full install)

• Press prefix+o to launch a file‑tree view of the current folder.
• Use prefix+shift+o or prefix+ctrl+o to browse recent agent replies.
• Inside the TUI you can edit, comment, and send the review back to the agent (E to send, q to quit).
• Install the optional Links add‑on to make Ctrl‑click on file://*.md links open directly in the reviewer:

  herdr plugin install plannotator/herdr-annotate/links
  

---

Remote / SSH Workflows

1. Keep selection on the remote server: set copy_on_select = false in the server’s ~/.config/herdr/config.toml.
2. From your local machine, invoke the capture action without a keypress:

   ssh host herdr plugin action invoke annotate.capture
   

3. The plugin reads the selection via Herdr’s API, bypassing the need for a local clipboard.

---

Development & Extensibility

• The plugin lives in rust/ and is built with Cargo.
• Typical dev cycle:

  cargo test --manifest-path rust/Cargo.toml
  cargo clippy --manifest-path rust/Cargo.toml -- -D warnings
  bash scripts/stage-local.sh   # builds and stages the binary
  herdr plugin link $PWD        # link for local testing
  

• You can swap between Lite and Full variants by linking the respective directory.
• The Links add‑on has no compiled component; it merely registers a plugin that forwards file:// clicks to the Full binary.

---

Who Might Use This?

• LLM‑powered developers who work in the terminal and want a quick way to annotate code output, error messages, or logs and feed that back to their assistant.
• Researchers iterating on prompt engineering; the manager lets them archive and replay past feedback.
• Teams using Herdr as a shared AI‑assistant interface and needing a consistent annotation format across sessions.

---

Quick Reference Cheat‑Sheet

# Example key bindings (place in ~/.config/herdr/config.toml)
[[keys.command]]
key = "prefix+a"
type = "plugin_action"
command = "annotate.capture"
description = "annotate text"

# … add the rest as shown in the README …

---

In a nutshell: herdr‑annotate turns terminal selections into structured, LLM‑ready feedback and lets you review whole documents—all without leaving the Herdr environment.