Note Review Comments

Leave comments while reading in Obsidian, then ask Claude or another LLM to edit the document using your feedback.

1. Highlight text in Reading view. A small popup opens; start typing your comment.
2. Save your comments as you read. The sidebar stays closed until you open it.
3. Copy the review prompt from the sidebar and give it to your AI agent, along with access to the note and comments file.

Processed comments are marked Resolved, even if an attempt fails. Reopen them when you want another pass.

Obsidian plugin listing · Release files · Install · Report an issue · VS Code companion

Desktop only · Reading view · Obsidian 1.8.0+

Install

1. Open Settings → Community plugins in Obsidian. If prompted, select Turn on community plugins.
2. Select Browse and search for Note Review Comments.
3. Select Install, then Enable.
4. Open a Markdown document and switch to Reading view to add your first comment.

You can also open the Obsidian Community listing and choose Add to Obsidian. You do not need Node.js or a build tool.

Manual installation

Use these steps if you prefer to install the release files yourself:

1. Download main.js, manifest.json, and styles.css from the latest release.

2. Create a folder named note-review-comments and place the three downloaded files inside.

3. Open your Obsidian vault’s .obsidian/plugins/ directory. You can use the Open plugins folder folder icon in Settings → Community plugins. If navigating manually, show hidden folders to find .obsidian, and create plugins if it is missing.

4. Copy the note-review-comments folder into plugins. The final layout should be:

   <your-vault>/.obsidian/plugins/note-review-comments/
   ├── main.js
   ├── manifest.json
   └── styles.css
   

5. Restart Obsidian, then open Settings → Community plugins and enable Note Review Comments.

6. Open a Markdown document and switch to Reading view to add your first comment.

Requires Obsidian 1.8.0 or newer on desktop. The core workflow has been tested in Obsidian 1.14.5 on macOS.

If upgrading from a manual installation of Reading Comments 0.1.3 or earlier, disable and remove its reading-comments plugin folder before installing this version. Keep the vault’s .comments folder: existing reviews remain compatible.

Add your first comment

Open a Markdown document and switch to Reading view using the view toggle in the note header.

1. Highlight a passage in Reading view. A small popup opens beside the passage as soon as you finish selecting, with the comment field already focused. Start typing immediately.
2. Write your feedback, then choose Save or press Cmd+Enter / Ctrl+Enter.
3. Use Escape, Cancel, or a click outside the popup to cancel a draft.

Saving leaves the comments panel as it is: closed stays closed, and an open panel updates in place. Open it when you want using a comment marker, the message icon in the ribbon, or the Note Review Comments: Open reading comments command.

Open and Resolved

Resolved means processed, even if the result was incorrect or the attempt failed. Use Reopen whenever you want another pass. You can also resolve comments manually.

The sidebar provides Show passage, Resolve/Reopen, Edit, and Delete. Commenting and changing statuses do not modify the note’s Markdown.

Send your comments to Claude or another LLM

1. Choose Copy review prompt in the sidebar.
2. Paste it into Claude Code or another AI agent that can read and edit files in your vault.
3. Let the agent process the review. Obsidian picks up saved note and status changes automatically.

If you use a chat-based LLM without local file access, also attach or paste the Markdown document and its .comments JSON file. Local paths alone will not give the model access. Save its revised Markdown and updated comments JSON back to the same files to see the edits and statuses in Obsidian.

The copied prompt includes absolute paths to the note and its comments file. It instructs the agent to:

1. Process only open comments, in stored order.
2. Apply each request while preserving unrelated content.
3. Set that comment’s resolved field to true immediately after the attempt, including unsuccessful attempts.
4. Preserve the comment text, IDs, and other JSON data.
5. Leave unprocessed comments open if the review stops early.
6. Summarize what happened, including failures.

The plugin does not call an AI service. Processing and status updates depend on the agent following the prompt and saving its changes. Copy review prompt is disabled when no open comments remain.

Your notes stay portable

Reviews are stored in a vault-root .comments folder that mirrors your notes:

Your vault/
├── docs/
│   └── proposal.md
└── .comments/
    └── docs/
        └── proposal.md.comments.json

Each comment records its selected text, line hints, feedback, ID, creation time, and optional resolution status and surrounding context. The version 1 JSON format is compatible with the VS Code Comment Tool; existing fields are preserved on updates. Use this plugin’s prompt when you want resolution-aware AI processing.

The plugin makes no network requests. If your vault uses a sync service, include .comments in that service’s configuration if you want reviews synced too.

Passage tracking and current limits

1. Unique quotes are found again after surrounding text changes. Repeated quotes use saved context; ambiguous or missing passages remain listed for manual review.
2. When an AI rewrites the quoted passage, the original quote stays in the comment’s history. Its highlight may disappear because the old text is gone.
3. Note and folder moves performed inside Obsidian move the corresponding review files. Conflicting destinations are preserved and reported. Moves performed externally while Obsidian is closed require moving the review files and updating their source paths manually.
4. Obsidian renders long notes in sections. A passage may not have a visible marker until its section is rendered.
5. Embedded notes are excluded from selection capture to avoid attaching feedback to the wrong file.
6. In-plugin saves are serialized and stale edits are rejected. Separate applications writing the same review at exactly the same time can still race.
7. Invalid JSON is preserved and reported. Repair or restore it, then choose Refresh.

Build and test

Use Node.js 24 or newer:

git clone https://github.com/hello1101n/obsidian-reading-comments.git
cd obsidian-reading-comments
npm ci
npm test
npm run build

The installable plugin files are written to dist/note-review-comments/.

The test suite covers DOM selections, status persistence, storage conflicts, malformed JSON, renames, and refresh races. A simulated Obsidian host uses real temporary files. The core workflow has also been checked in the native app; see verification coverage.

Uninstall

Disable Note Review Comments and remove <your-vault>/.obsidian/plugins/note-review-comments. Your notes remain ordinary Markdown. Keep .comments to retain your review history.

License

MIT.