plannotator/herdr-annotate: Send Terminal and Document Feedback Back to Your Agent

What herdr-annotate solves, and who it is for

Terminal work with a coding agent has a feedback problem. You read a diff, a plan or a Markdown spec in a pane, and your response has to be retyped into a prompt. The context you were looking at, and the exact lines you objected to, get lost in the retelling. herdr-annotate targets that gap: you select text in the terminal or open a document, leave comments, and the plugin hands the collection back to the agent as its next message.

The audience is narrow and specific. You need Herdr 0.8.0 or later, on macOS, Linux or Windows, and an agent CLI from the supported list: Claude Code, Codex, pi, Copilot CLI, Droid, Oh My Pi, Hermes CLI, and OpenCode 1 and 2. If you drive your agent from a plain shell without Herdr, this plugin has nothing to attach to. Document review is powered by plannotator-tui, which the README notes also runs on its own outside Herdr, so the document half of the feature is available separately.

How annotations travel from selection to agent message

The mechanism is a plugin action, not a copy-paste buffer. Herdr binds a key to a named action such as annotate.capture, and the action reads the focused pane's selection through Herdr's API. That detail matters for remote work: the README states the API path never touches the keyboard path, which is why an action invoked over SSH can still retrieve a highlighted selection that a prefix keypress would have cleared.

Annotations accumulate in a store the plugin manages. From there, two output paths exist. Copies made inside the manager pane emit OSC 52, so on Herdr 0.9.0 they reach the clipboard of the machine you are viewing from even when the plugin runs on a remote server with no clipboard tool installed. The direct copy actions, Ctrl+B Shift+A and Ctrl+B Ctrl+A, do not emit OSC 52, because the README explains they run outside a pane and have no terminal to write to. The document side is a different component: plannotator-tui renders the file tree or the agent's recent replies, and pressing Send, or E, makes the review the agent's next message. The full install wraps that TUI; the lite install does not include it.

Installing herdr-annotate and binding the keys

There is no runtime to install. Both variants download a small prebuilt herdr-annotate binary and verify its SHA-256 checksum. Pick one install; the README notes that installing the other later just swaps it under the same plugin id, and that an install stays on the commit it came from, so running the same command again moves you to the current release.

The full install adds terminal annotations plus document and agent-reply review:

herdr plugin install plannotator/herdr-annotate

The lite install is terminal annotations only:

herdr plugin install plannotator/herdr-annotate/lite

Binding keys is described as required, not optional. The full install expects entries like these in Herdr's config:

[[keys.command]]
key = "prefix+a"
type = "plugin_action"
command = "annotate.capture"
description = "annotate text"

[[keys.command]]
key = "prefix+o"
type = "plugin_action"
command = "annotate.open"
description = "review documents in this folder"

[[keys.command]]
key = "prefix+shift+o"
type = "plugin_action"
command = "annotate.last"
description = "review the agent's last reply"

Then check the config and reload the server. If either command reports a problem, the keybinding block is the first place to look.

herdr config check
herdr server reload-config

On Linux, install wl-clipboard, xclip or xsel for clipboard access. On Windows, native Herdr plugin support is described as preview and best-effort, clipboard access goes through PowerShell, and no extra clipboard package is needed.

The remote-session caveat is the real limitation

Over SSH or herdr --remote, the plugin runs on the server, and the README is unusually candid about what breaks. Herdr's default copy-on-select clears the selection on mouse-up, and the prefix keypress clears whatever selection remains before a bound action runs, a behaviour tracked as herdrdev/herdr#3380. A headless server also has no clipboard for the plugin to fall back to.

The documented workaround is to stop using the keybinding for capture. Set copy_on_select = false under [ui] in the server's ~/.config/herdr/config.toml so the selection survives mouse-up, then invoke the action from your laptop with no keypress inside Herdr:

ssh <host> herdr plugin action invoke annotate.capture
# named session on the server: ssh <host> HERDR_SESSION=<name> herdr plugin action invoke annotate.capture

That is a real constraint, not a rough edge. The normal interaction model, select and press prefix+a, is the one that fails remotely, and the replacement requires shell access from the client machine. The README also states that server-side key bindings and herdr --remote guidance are incomplete, so treat remote use as a path you assemble yourself. If your workflow is entirely local, none of this applies.

Full versus lite, and where plannotator-tui fits

The two installs are not versions of the same thing. Lite gives you select text, prefix+a, comment in a popover, plus the copy and manage actions. Full adds the plannotator-tui document reviewer, which is what makes Ctrl+B O open the current folder with a file tree, Ctrl+B Shift+O open the agent's recent replies, and Ctrl-click on a file://...md link open that file. If your review work is mostly reading a spec or a plan and marking it up, lite is the wrong choice.

The closest alternative is plannotator-tui on its own, which the README links as the way to use the reviewer without Herdr. The difference in approach is integration versus independence. Running plannotator-tui standalone gives you document and agent-reply review with none of the Herdr plugin machinery, but you lose the terminal-text capture action and the keybinding layer, and you have to move the review into the agent's context yourself. herdr-annotate's value is that Send makes the review the agent's next message, which the standalone tool does not do by itself.

One more option is worth knowing: the README documents that agents can request reviews themselves with npx skills add plannotator/herdr-annotate --skill plannotator-tui -g. Placement of the reviewer is configurable through [herdr] placement in ~/.config/plannotator-tui/config.toml, with the values "overlay", "split" or "popup".

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-10, the same day as the rust-lite-v0.1.0 release. That is a recent single release rather than a long history, and the version string in the release name suggests the lite variant is the one that just shipped its first tag. The README does not document a rollback path, so the upgrade story rests on the install behaviour: an install stays on the commit it came from, and re-running the install command moves it to the current release.

Upgrade cost is low in one sense and non-zero in another. There is no runtime to manage and the binary is prebuilt with a SHA-256 checksum, so moving versions is a single install command. The friction is the config: keybindings live in Herdr's config, and placement for the document reviewer lives in ~/.config/plannotator-tui/config.toml, so a swap between full and lite changes which actions exist without changing those files. The project is MIT licensed, which permits commercial and private use, modification and redistribution with the licence and copyright notice retained. That is a summary of the licence terms, not legal advice; read LICENSE in the repository for the binding text.

Editorial conclusion

Adopt the full install if you already run Herdr 0.8.0 or later and want the agent to receive your review as its next message, and the lite install if you only need terminal annotations. Skip it if you work outside Herdr: the plugin is bound to Herdr's keybinding and plugin-action model, and remote sessions still fight Herdr's selection handling. Before committing, verify the plugin id swap between full and lite, whether your agent CLI is among the supported list, and whether your server has a clipboard tool or Herdr 0.9.0 for OSC 52.

Frequently asked questions

Official sources

1. License: MIT
2. plannotator/herdr-annotate on GitHub
3. Project website
4. README
5. Releases