Skip to content
Back to search

herdr-annotate

Annotate terminal text, review documents and agent replies in Herdr, and send the feedback straight back to the agent.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/plannotator/herdr-annotate with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/plannotator/herdr-annotate'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/plannotator--herdr-annotate/badge.svg)](/listings/plannotator--herdr-annotate)

HTML

<a href="/listings/plannotator--herdr-annotate"><img src="/api/listings/plannotator--herdr-annotate/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Pick one. Installing another later just swaps it (same plugin id). An install stays on the commit it came from; run the same command again to move to the current release.

**Full:** annotate terminal text, review documents and agent replies, send feedback to the agent. Wraps [Plannotator TUI](https://github.com/plannotator/plannotator-tui) (macOS and Linux; Windows via the windows-full variant below). [Demo](https://x.com/plannotator/status/2093419561077154287)

herdr plugin install plannotator/herdr-annotate

<br clear="all">

**Lite:** the simple version: select text, `prefix+a`, comment in a popover. [Demo](https://x.com/plannotator/status/2092757422322627008)

herdr plugin install plannotator/herdr-annotate/lite

<br clear="all">

**Windows Full (preview):** the Full install on Windows, opt-in. Requires Herdr 0.9.0 or later on Windows.

herdr plugin install plannotator/herdr-annotate/windows-full

It stages `plannotator-tui` natively, so no launcher sits between Herdr and the TUI. It shares the same native runtime as the Lite and Full installs, so annotations and archives stay in one place.

This is a preview. The pane and path handling were verified on Windows 11 x86_64 ([PR #49](https://github.com/plannotator/herdr-annotate/pull/49), [issue #43](https://github.com/plannotator/herdr-annotate/issues/43)). Native ARM64 is untested. Report results on [issue #43](https://github.com/plannotator/herdr-annotate/issues/43).

> **Required.** Bind the keys in Herdr's config. These keys are free in Herdr's defaults; if you changed yours, check for clashes with `herdr --default-config` and your own config.

<details open> <summary><b>Full install keys:</b> terminal annotations + document and agent-reply review</summary>

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

[[keys.command]]
key = "prefix+shift+a"
type = "plugin_action"
command = "annotate.copy-context"
description = "copy annotations as context"

[[keys.command]]
key = "prefix+ctrl+a"
type = "plugin_action"
command = "annotate.copy-archive"
description = "copy annotations as context and archive them"

[[keys.command]]
key = "prefix+ctrl+v"
type = "plugin_action"
command = "annotate.paste-archive"
description = "paste annotations into the agent's prompt and archive them"

[[keys.command]]
key = "prefix+ctrl+s"
type = "plugin_action"
command = "annotate.send-archive"
description = "send annotations to the agent and archive them"

[[keys.command]]
key = "prefix+m"
type = "plugin_action"
command = "annotate.manage"
description = "manage annotations"

# Document review (plannotator-tui)
[[keys.command]]
key = "prefix+d"
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"

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

</details>

<details> <summary><b>Lite install keys:</b> terminal annotations only</summary>

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

[[keys.command]]
key = "prefix+shift+a"
type = "plugin_action"
command = "annotate.copy-context"
description = "copy annotations as context"

[[keys.command]]
key = "prefix+ctrl+a"
type = "plugin_action"
command = "annotate.copy-archive"
description = "copy annotations as context and archive them"

[[keys.command]]
key = "prefix+ctrl+v"
type = "plugin_action"
command = "annotate.paste-archive"
description = "paste annotations into the agent's prompt and archive them"

[[keys.command]]
key = "prefix+ctrl+s"
type = "plugin_action"
command = "annotate.send-archive"
description = "send annotations to the agent and archive them"

[[keys.command]]

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 388 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ![Herdr Annotate](assets/herdr-annotate.webp)
  2. # herdr-annotate
  3. Annotate inside [Herdr](https://github.com/herdrdev/herdr): comment on any terminal text, review whole Markdown documents and your agent's replies, and send the feedback straight back to the agent. Document review is powered by [plannotator-tui](https://github.com/plannotator/plannotator-tui), which also runs on its own outside Herdr.
  4. <p align="center">
  5. <a href="https://github.com/backnotprop/plannotator">
  6. <img src="./assets/star-plannotator.svg" width="280" alt="Like this? Star Plannotator">
  7. </a>
  8. </p>
  9. **Watch the demos**
  10. [![Demo: Full install](https://img.shields.io/badge/%E2%96%B6%20Demo%3A%20Full%20install-f7ca5e?style=flat-square&labelColor=171429)](https://x.com/plannotator/status/2093419561077154287)
  11. [![Demo: Lite install](https://img.shields.io/badge/%E2%96%B6%20Demo%3A%20Lite%20install-c9c6f1?style=flat-square&labelColor=171429)](https://x.com/plannotator/status/2092757422322627008)
  12. ## Requirements
  13. - Herdr 0.8.0 or later
  14. - macOS, Linux, or Windows
  15. There is no runtime to install. Both installs download a small prebuilt `herdr-annotate` binary and verify its SHA-256 checksum.
  16. On Linux, install `wl-clipboard`, `xclip`, or `xsel` for clipboard access.
  17. On Windows, native Herdr plugin support is preview/best-effort. Lite installs on Herdr 0.8.0 or later; Full installs through the Windows Full variant below, which needs Herdr 0.9.0 or later. Clipboard access uses PowerShell; no extra clipboard package is required. The install, keybinding, configuration check, reload, and use instructions below also apply on Windows.
  18. ## Install
  19. Pick one. Installing another later just swaps it (same plugin id). An install stays on the commit it came from; run the same command again to move to the current release.
  20. <img src="assets/install-full.svg" width="200" align="left" alt="Full">
  21. **Full:** annotate terminal text, review documents and agent replies, send feedback to the agent.
  22. Wraps [Plannotator TUI](https://github.com/plannotator/plannotator-tui) (macOS and Linux; Windows via the windows-full variant below). [Demo](https://x.com/plannotator/status/2093419561077154287)
  23. ```sh
  24. herdr plugin install plannotator/herdr-annotate
  25. ```
  26. <br clear="all">
  27. <img src="assets/install-lite.svg" width="200" align="left" alt="Lite">
  28. **Lite:** the simple version: select text, `prefix+a`, comment in a popover. [Demo](https://x.com/plannotator/status/2092757422322627008)
  29. ```sh
  30. herdr plugin install plannotator/herdr-annotate/lite
  31. ```
  32. <br clear="all">
  33. **Windows Full (preview):** the Full install on Windows, opt-in. Requires Herdr 0.9.0 or later on Windows.
  34. ```sh
  35. herdr plugin install plannotator/herdr-annotate/windows-full
  36. ```
  37. It stages `plannotator-tui` natively, so no launcher sits between Herdr and the TUI. It shares the same native runtime as the Lite and Full installs, so annotations and archives stay in one place.
  38. This is a preview. The pane and path handling were verified on Windows 11 x86_64 ([PR #49](https://github.com/plannotator/herdr-annotate/pull/49), [issue #43](https://github.com/plannotator/herdr-annotate/issues/43)). Native ARM64 is untested. Report results on [issue #43](https://github.com/plannotator/herdr-annotate/issues/43).
  39. > **Required.** Bind the keys in Herdr's config. These keys are free in Herdr's defaults; if you changed yours, check for clashes with `herdr --default-config` and your own config.
  40. <details open>
  41. <summary><b>Full install keys:</b> terminal annotations + document and agent-reply review</summary>
  42. ```toml
  43. # Terminal annotations
  44. [[keys.command]]
  45. key = "prefix+a"
  46. type = "plugin_action"
  47. command = "annotate.capture"
  48. description = "annotate text"
  49. [[keys.command]]
  50. key = "prefix+shift+a"
  51. type = "plugin_action"
  52. command = "annotate.copy-context"
  53. description = "copy annotations as context"
  54. [[keys.command]]
  55. key = "prefix+ctrl+a"
  56. type = "plugin_action"
  57. command = "annotate.copy-archive"
  58. description = "copy annotations as context and archive them"
  59. [[keys.command]]
  60. key = "prefix+ctrl+v"
  61. type = "plugin_action"
  62. command = "annotate.paste-archive"
  63. description = "paste annotations into the agent's prompt and archive them"
  64. [[keys.command]]
  65. key = "prefix+ctrl+s"
  66. type = "plugin_action"
  67. command = "annotate.send-archive"
  68. description = "send annotations to the agent and archive them"
  69. [[keys.command]]
  70. key = "prefix+m"
  71. type = "plugin_action"
  72. command = "annotate.manage"
  73. description = "manage annotations"
  74. # Document review (plannotator-tui)
  75. [[keys.command]]
  76. key = "prefix+d"
  77. type = "plugin_action"
  78. command = "annotate.open"
  79. description = "review documents in this folder"
  80. [[keys.command]]
  81. key = "prefix+shift+o"
  82. type = "plugin_action"
  83. command = "annotate.last"
  84. description = "review the agent's last reply"
  85. [[keys.command]]
  86. key = "prefix+ctrl+o"
  87. type = "plugin_action"
  88. command = "annotate.last-newest"
  89. description = "review the agent's newest reply"
  90. ```
  91. </details>
  92. <details>
  93. <summary><b>Lite install keys:</b> terminal annotations only</summary>
  94. ```toml
  95. [[keys.command]]
  96. key = "prefix+a"
  97. type = "plugin_action"
  98. command = "annotate.capture"
  99. description = "annotate text"
  100. [[keys.command]]
  101. key = "prefix+shift+a"
  102. type = "plugin_action"
  103. command = "annotate.copy-context"
  104. description = "copy annotations as context"
  105. [[keys.command]]
  106. key = "prefix+ctrl+a"
  107. type = "plugin_action"
  108. command = "annotate.copy-archive"
  109. description = "copy annotations as context and archive them"
  110. [[keys.command]]
  111. key = "prefix+ctrl+v"
  112. type = "plugin_action"
  113. command = "annotate.paste-archive"
  114. description = "paste annotations into the agent's prompt and archive them"
  115. [[keys.command]]
  116. key = "prefix+ctrl+s"
  117. type = "plugin_action"
  118. command = "annotate.send-archive"
  119. description = "send annotations to the agent and archive them"
  120. [[keys.command]]
  121. key = "prefix+m"
  122. type = "plugin_action"
  123. command = "annotate.manage"
  124. description = "manage annotations"
  125. ```
  126. </details>
  127. Check and reload:
  128. ```sh
  129. herdr config check
  130. herdr server reload-config
  131. ```
  132. ## Use
  133. ### Annotate terminal text
  134. | Key | Action |
  135. |---|---|
  136. | `Ctrl+B A` | comment on the selected text · `Ctrl+S` saves |
  137. | `Ctrl+B Shift+A` | copy all annotations as Markdown |
  138. | `Ctrl+B Ctrl+A` | copy all annotations as Markdown, then archive them |
  139. | `Ctrl+B Ctrl+V` | paste all annotations into the focused agent's prompt without sending, then archive them |
  140. | `Ctrl+B Ctrl+S` | send all annotations as the focused agent's next message, then archive them |
  141. | `Ctrl+B M` | manage · `Enter` jump to the pane it came from · `e` edit the selected comment · `y` copy one · `c` copy all · `Shift+C` copy and archive · `Tab` archives (`y` copy · `u` restore · `d d` delete) |
  142. In the manager's active view, `e` opens the selected comment in the editor. `Ctrl+S` saves it;
  143. `Esc` cancels. Editing leaves the selected text, capture metadata, and original ordering unchanged.
  144. If another pane saves that comment first, saving your stale draft is rejected and the draft stays
  145. open. To edit the latest version, cancel with `Esc`, then press `r` in the manager to reload.
  146. `Enter` focuses the Herdr pane the selected annotation was captured from and closes the manager.
  147. Agent panes are focused directly; for any other pane, Herdr focuses the tab that holds it. If the
  148. pane has closed, or the annotation has no pane recorded, the manager says so and stays open. Herdr
  149. cannot scroll a pane to the annotated text, so the jump stops at the pane.
  150. Annotations are listed and handed off oldest first, in the order you wrote them, so the agent
  151. reads your feedback in the same order you went through the text. The Markdown uses Plannotator's
  152. feedback format: one numbered `## Annotation N` per note, headed with the workspace and tab it came
  153. from, then `Comment on:` with the selected text and your comment as a `>` quote.
  154. Copies made inside the manager pane also emit OSC 52, so on Herdr 0.9.0 they reach the clipboard of
  155. the machine you are viewing from even when the plugin runs on a remote server with no clipboard tool
  156. installed; `Ctrl+B Shift+A` and `Ctrl+B Ctrl+A` do not, because those actions run outside a pane and
  157. have no terminal to write to.
  158. `Ctrl+B Ctrl+V` and `Ctrl+B Ctrl+S` skip the clipboard and put the same Markdown straight into the
  159. prompt of the agent in the focused pane. Both first ask Herdr whether the agent is ready. When
  160. that pane has no running agent Herdr recognises, the agent is still launching, or it is waiting at
  161. an approval or question prompt, they refuse, type nothing, and leave your annotations active.
  162. ### Review documents and agent replies
  163. Full install. Works with Claude Code, Codex, pi, Copilot CLI, Droid, Oh My Pi, Hermes CLI, OpenCode (1 and 2), Command Code and Antigravity CLI.
  164. | Key | Opens |
  165. |---|---|
  166. | `Ctrl+B O` | this folder, with a file tree |
  167. | `Ctrl+B Shift+O` | the agent's recent replies |
  168. | `Ctrl+B Ctrl+O` | the agent's newest reply, with no picker |
  169. | Ctrl-click a `file://…md` link | that file, only with the opt-in Links add-on below |
  170. `annotate.terminal` opens the focused pane's recent terminal output (the last 200 lines) for
  171. review in the same way. It has no default key; to use it, bind one yourself, for example:
  172. ```toml
  173. [[keys.command]]
  174. key = "prefix+t"
  175. type = "plugin_action"
  176. command = "annotate.terminal"
  177. description = "review this pane's recent output"
  178. ```
  179. `annotate.review` opens a code review of the focused pane's git changes. Comment on lines of
  180. the diff, then send the comments to the agent in that pane. A folder with no repository or no
  181. changes shows an error instead. It works on macOS and Linux, and has no default key:
  182. ```toml
  183. [[keys.command]]
  184. key = "prefix+ctrl+r"
  185. type = "plugin_action"
  186. command = "annotate.review"
  187. description = "review this repo's changes"
  188. ```
  189. `annotate.gate` opens the same folder review as `annotate.open`, with an **Approve** button
  190. (`A`). The agent gets `The user approved.` (with any notes as non-blocking guidance), or your
  191. numbered feedback as usual. Use it when an agent should wait for your sign-off. It has no
  192. default key either:
  193. ```toml
  194. [[keys.command]]
  195. key = "prefix+ctrl+d"
  196. type = "plugin_action"
  197. command = "annotate.gate"
  198. description = "review documents here, with Approve"
  199. ```
  200. #### Ctrl-click Markdown links (opt-in)
  201. Annotate does not capture Ctrl-click on links by default, so `file://…md` links open the way
  202. Herdr normally opens them. To send Ctrl-clicked `file://` Markdown links (`.md`, `.markdown`,
  203. `.mdx`) to Annotate instead, install the Links add-on next to the Full install (on Windows, next
  204. to Windows Full):
  205. ```sh
  206. herdr plugin install plannotator/herdr-annotate/links
  207. ```
  208. To turn it off again:
  209. ```sh
  210. herdr plugin uninstall annotate-links
  211. ```
  212. The add-on has no binary of its own; it opens the file with the Full (or Windows Full) plugin's
  213. plannotator-tui. If neither is installed, Ctrl-click shows a notification saying which one to install.
  214. > **Upgrading from 0.8.0 or earlier:** up to plugin 0.8.0, the Full install captured these clicks
  215. > itself. From 0.9.0 it does not
  216. > ([#69](https://github.com/plannotator/herdr-annotate/issues/69)). Install the Links add-on to keep
  217. > the old behavior.
  218. **Send** (or `E`) makes the review the agent's next message. `q` closes. On an agent reply, `S`
  219. sends and closes in one key; `E` and `q` are unchanged.
  220. | Option | Where |
  221. |---|---|
  222. | Agents request reviews themselves | `npx skills add plannotator/herdr-annotate --skill plannotator-tui -g` |
  223. | Open as full tab, split, or popup | `[herdr] placement = "overlay" \| "split" \| "popup"` in `~/.config/plannotator-tui/config.toml` |
  224. | Use without Herdr | [plannotator-tui](https://github.com/plannotator/plannotator-tui) |
  225. ### Remote sessions
  226. Over SSH or `herdr --remote`, the plugin runs on the **server**, and two things get in the way:
  227. Herdr's default copy-on-select clears the selection on mouse-up, and the prefix keypress
  228. clears whatever selection remains before a bound action runs
  229. ([herdrdev/herdr#3380](https://github.com/herdrdev/herdr/issues/3380)). A headless server also
  230. has no clipboard for the plugin to fall back to.
  231. What works today:
  232. 1. On the server, keep the selection after mouse-up:
  233. ```toml
  234. # remote server: ~/.config/herdr/config.toml
  235. [ui]
  236. copy_on_select = false # the selection stays; copy explicitly with Ctrl+C
  237. ```
  238. plannotator-tui has the same setting in its own config
  239. (`~/.config/plannotator-tui/config.toml`, `[ui] copy_on_select = false`); press `y` on a
  240. selection there to copy it.
  241. 2. Trigger the action **without a keypress in Herdr**, while the selection is still
  242. highlighted. From your laptop, bound to any key in your terminal or OS:
  243. ```sh
  244. ssh <host> herdr plugin action invoke annotate.capture
  245. # named session on the server: ssh <host> HERDR_SESSION=<name> herdr plugin action invoke annotate.capture
  246. ```
  247. The action reads the focused pane's selection through Herdr's API, which never touches the
  248. keyboard path, so the text arrives. Verified: the same selection gives `selected_text` this
  249. way and nothing through `prefix+a`.
  250. 3. In Neovim, use the mapping below; it hands the selection over in a file.
  251. Server-side key bindings and `herdr --remote <host> --remote-keybindings server` are still
  252. needed for the manager (`prefix+m`) and other plugin keys; without the flag, `herdr --remote`
  253. uses your local keys and drops plugin bindings. `prefix+a` itself will work once
  254. herdrdev/herdr#3380 is fixed.
  255. ## Selection limits
  256. Herdr Annotate reads text that Herdr copies to the system clipboard. The plugin cannot read selection state from Neovim or another terminal application.
  257. ## Development
  258. The plugin is a Rust binary in `rust/`.
  259. ```sh
  260. cargo test --manifest-path rust/Cargo.toml
  261. cargo clippy --manifest-path rust/Cargo.toml --all-targets -- -D warnings
  262. bash scripts/stage-local.sh # build and stage bin/herdr-annotate.exe
  263. herdr plugin link "$PWD" # or "$PWD/lite" for the Lite variant
  264. ```
  265. `herdr plugin link` does not run manifest build hooks, so stage the binary first. It also replaces
  266. any existing `annotate` link; link the other directory to switch back.
  267. The Links add-on has no build step: `herdr plugin link "$PWD/links"` links it as `annotate-links`.
  268. `bash scripts/lite-regression.sh` checks the runtime against goldens recorded from the retired Bun
  269. runtime. [docs/lite-testing.md](docs/lite-testing.md) covers what it compares and everything else
  270. that guards Lite.
  271. To test a local plannotator-tui build instead of the pinned release, put it in `bin/`
  272. before linking: `PLANNOTATOR_TUI_BIN=/path/to/plannotator-tui bash scripts/fetch-plannotator-tui.sh`.
  273. Before a release, `HERDR_SESSION=<disposable session> bash scripts/smoke.sh` installs fresh, upgrades
  274. from the first shipped commit, installs lite, swaps to full, and opens the manager and review panes,
  275. then restores whatever was installed.
  276. ## Neovim integration
  277. Add this visual-mode mapping to `~/.config/nvim/lua/config/keymaps.lua` for LazyVim, or to `init.lua`:
  278. ```lua
  279. vim.keymap.set("x", "<leader>a", function()
  280. -- Hand the selection to the plugin through a file: works on headless servers too.
  281. vim.cmd('normal! "zy')
  282. local base = os.getenv("XDG_RUNTIME_DIR")
  283. if not base or base == "" then base = vim.fn.fnamemodify(vim.fn.tempname(), ":h") end
  284. local dir = base .. "/herdr-annotate-" .. vim.loop.getuid()
  285. vim.fn.mkdir(dir, "p", "0700")
  286. vim.fn.writefile(vim.split(vim.fn.getreg("z"), "\n"), dir .. "/selection")
  287. vim.fn.jobstart({ "herdr", "plugin", "action", "invoke", "annotate.capture" })
  288. end, { desc = "Annotate in Herdr" })
  289. ```
  290. Select text with the mouse or Visual mode. Then press `<leader>a` to open Herdr Annotate.
  291. The file is read once and removed; a file older than 15 seconds is ignored.
  292. LazyVim uses `Space` as `<leader>` by default. The mapping keeps mouse support and leaves normal Neovim commands unchanged.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.