markdown-commenter

markdown-commenter

A desktop markdown viewer with Google-Docs-style commenting and an AI review loop powered by your own Claude Code.

Read a markdown file, highlight text, and leave comments in the margin. A watcher notices each new comment and has Claude revise the document to address it — replying to every comment as it goes — and the editor live-reloads to show the changes. Comments are stored in a hidden sidecar next to each file, so they travel with the document and play nicely with git.

highlight + comment  ──▶  mdc revises via your Claude Code  ──▶  editor live-reloads
        ▲                                                              │
        └──────────────────────── you review ◀─────────────────────────┘

How it works

The editor is the human side; a small CLI (mdc) is the AI side; a hidden .<file>.md.comments.json sidecar is the shared state both read and write. The revision shells out to your installed claude CLI (claude -p) — so there are no API keys to manage and no separate billing; it uses your existing Claude Code session.

Prerequisites

1. Node.js 18+
2. Claude Code installed and authenticated — the AI revision relies on the claude CLI being on your PATH. See https://code.claude.com/docs. Verify with claude --version.

Install

Installs straight from GitHub — no registry involved:

npm install -g github:geminiicode/markdown-commenter

Electron ships as a dependency, so the editor launches with no extra build step.

Usage

The whole loop in one command:

mdc review notes.md     # a single file
mdc review ./docs       # or a whole folder

This opens the editor and starts a watcher that auto-revises whenever you add a comment:

1. Highlight text and click 💬 Comment to leave a note.
2. The watcher waits a few seconds, then has Claude revise the doc.
3. The editor live-reloads: a diff banner shows what changed, Claude's replies appear in the margin, and the comments flip to Addressed.

Closing the window (or Ctrl-C) stops the watcher.

If you'd rather drive the pieces yourself:

mdc address <file.md>   # one-shot: revise the doc to address open comments
mdc watch <file.md>     # just the auto-address watcher (no editor)
mdc list <file.md>      # print comments and their statuses

You can also launch just the editor with npm start and open files from the UI.

Use it from inside Claude Code

This repo doubles as a Claude Code plugin. Add it as a marketplace and install:

/plugin marketplace add geminiicode/markdown-commenter
/plugin install markdown-commenter

Then run the review loop from a Claude Code session (plugin skills are namespaced by plugin name):

/markdown-commenter:review-md notes.md

The plugin handles the mdc prerequisite itself: on the first session after install it pre-installs the CLI in the background, and if that hasn't completed by the time you invoke the skill, the skill offers to run the install interactively. Installing via npm yourself (above) also works and skips both.

Security note

The review loop runs Claude with edit access to the document's directory (--permission-mode acceptEdits), and both the document and your comments are part of the prompt. That means reviewing a markdown file is effectively granting its author edit access to files in that directory — a malicious document could instruct Claude to make unwanted edits. Claude is restricted to Read,Edit (not Write), so it edits existing files in place but can't create new ones, which bounds the blast radius.

Note that pointing mdc review (or mdc watch) at a folder runs Claude automatically and unattended on every document in the tree as you comment, so the trust requirement extends to every file under that folder. Only run the review loop on documents you trust.

Comment storage

Comments live in a hidden sidecar beside each file: notes.md → .notes.md.comments.json. Each comment carries the quoted text it anchors to, a status (open → addressed → resolved), and a thread of replies. The schema is plain JSON — the editor and CLI are just two clients of it.

License

MIT — see LICENSE.