notabene

Comments on the rendered page become agent instructions

notabene turns the Markdown or MDX in a repository into a browsable doc site where reviewers comment on the rendered page itself: a selected passage, a whole page, a diagram or an image. An AI agent then reads those comments, edits the source files, resolves each thread and writes a journal entry saying what changed and why. The anchored comment replaces the prompt that had to quote the passage and name the section before the agent could find the right spot. An article on why a prompt can ask but can't point goes further into that problem.

notabene is a Z29K project, and Z29K publishes this site: the repository and the copyright on the code belong to z29k, and the npm package is @z29k/notabene.

Plain JSON in git, a plain-text protocol for any agent

• Every comment is its own JSON file under .notabene/, stored in the repository rather than in a SaaS or a database, so git merges feedback without conflicts and it shows up in pull request diffs.
• The agent only reads and writes files, with no server, port or MCP involved. notabene init writes the spec to .notabene/protocol.md and points to it from AGENTS.md, which Codex CLI, Cursor, Gemini CLI and Zed read at startup. Claude Code gets the same procedure as a skill, shipped in a plugin.
• An anchor stores the quoted text, the text around it and the nearest heading, and the agent matches it against the source with some tolerance.
• Approve mode (review: "approve") keeps the agent from resolving anything on its own. Each edit waits on /review next to its actual git diff, even when one comment touches several pages, and a rejection reopens the thread with the reason for the agent's next pass.
• notabene comments verify audits statuses and the links between comments and journal entries, and exits non-zero when something is off, so it can gate CI. notabene lint checks internal links against the routes the last build actually emitted.
• The doc site handles MDX and CommonMark/GFM, commentable Mermaid diagrams, multilingual docs with comments kept per language, and PDF export. build --public outputs a read-only static site with llms.txt, optional Pagefind search and a ready-made GitHub Pages workflow.

A loopback dev server for reviews, still at 0.x

Comments can only be written through the dev server. The comment API and the in-page editor exist only under notabene dev, bound to 127.0.0.1 by default. Letting other people join a review means starting it with --host, which the docs limit to trusted networks and recommend pairing with a NOTABENE_TOKEN. There are no user accounts: on a shared host, each visitor types a name and, optionally, an email. The public build carries no comment interface and no comment data.

It needs Node 22.12 or later and git-tracked files. notabene reads Markdown or MDX that lives in a repository, and the in-page editor refuses to write a file git does not track unless told otherwise. Bookmarked PDFs from notabene pdf also require Puppeteer, which drives a headless Chromium; printing from the browser does not.

The project describes itself as a protocol first. Its docs promise Google Docs-style comments kept in git, and state that the protocol, not the viewer, is the product. The .notabene store is a versioned public contract, currently at schema version 3, and every format change ships with a migrator (notabene migrate).

The latest release is 0.17.0, from 12 October 2026. It moves the renderer to Astro 7. GitHub lists 27 releases, from 0.3.0 on 3 July 2026 to 0.17.0.