41.02
item · Working in the open / Open source

annotations.nvim

Neovim plugin

Two parties, realistically one person and one AI, work on a markdown document without ever editing each other’s text. One writes the document. The other annotates it in a sidecar file, {file}.notes.md. While the notes file exists, the document is frozen. To answer, the writer rewrites the document to take in every note and deletes the notes file. All or nothing; git is the archive.

The freeze is what makes it cheap. Annotations never have to survive an edit, so they anchor to line numbers and nothing else: no fuzzy matching, no orphaned comments, none of the machinery a real review tool needs.

The plugin enforces the freeze on the human side by making the buffer read-only, with an escape hatch on purpose. The AI’s side is enforced by writing the rule down where it will read it. This is the annotating convention from loom, with an editor attached.

github.com/JeffryGonzalez/annotations.nvim