Comment Tool

Review rendered Markdown or ordinary source files inside VS Code and save comments under one workspace-level .comments directory.

When installed, Commentable Markdown Preview can be configured as VS Code's default editor for *.md, so Markdown files open directly in the review experience.

The .comments directory mirrors the source tree so files with the same name do not collide:

docs/proposal.md
.comments/docs/proposal.md.comments.json

src/Services/Auth.cs
.comments/src/Services/Auth.cs.comments.json

The JSON source field contains the workspace-relative source path, such as src/Services/Auth.cs. For a standalone file outside a VS Code workspace, the extension creates .comments in that file's directory and uses its filename as source.

Run the extension locally

1. Run corepack pnpm install in this folder.
2. Open this folder in VS Code.
3. Press F5 and choose Run Extension if VS Code asks for a configuration.
4. In the Extension Development Host, open review-me.md from the automatically opened examples folder.
5. Run Comment Tool: Open Commentable Preview from the Command Palette, click the comment icon in either the Markdown source or built-in preview title, or right-click the file in Explorer.

Review a document

1. Select text with the mouse in the rendered commentable preview.
2. The comment composer opens automatically.
3. Write the comment and press Cmd+Enter or choose Save comment.
4. Use Open JSON in the preview toolbar to inspect the comments file under .comments.
5. Use Copy LLM prompt to copy both absolute file paths and instructions to apply the comments one by one.

The extension uses its own VS Code preview panel because the selection UI and JSON persistence need two-way communication with the extension host. Use Open Commentable Preview instead of VS Code's standard Open Preview command.

Use as the default Markdown editor

1. Open the Command Palette and run View: Reopen Editor With... for any Markdown file.
2. Choose Configure default editor for '*.md'....
3. Choose Commentable Markdown Preview.

After this, Markdown files open directly in the commentable preview. Use View: Reopen Editor With... → Text Editor whenever you temporarily need raw Markdown source.

Review code and other text files

Markdown continues to use the rendered commentable preview. Every other local text or code file keeps VS Code's normal editor, including its syntax highlighting, IntelliSense, navigation, and debugging support.

1. Open a non-Markdown text or code file, such as Example.cs.
2. Select a code range, or place the pointer beside a single line.
3. Hover in the editor gutter and choose the + comment control.
4. Write and save the comment in VS Code's native inline comment box.
5. Use Open Comments JSON from the editor's top-right file-code button or its right-click menu.
6. Use Copy Review Prompt for LLM from the copy button beside it or the same right-click menu.

For example, comments for src/Example.cs are stored in .comments/src/Example.cs.comments.json. Saved comments are restored as native comment threads when the source file is reopened and are also visible in VS Code's Comments panel.

JSON format

{
  "version": 1,
  "source": "examples/review-me.md",
  "comments": [
    {
      "id": "8a17df1b-7d3b-4ce3-ab2b-8ee66f6e8726",
      "line": 9,
      "endLine": 9,
      "highlightedText": "The rollout should happen soon.",
      "comment": "Replace 'soon' with a target date.",
      "createdAt": "2026-08-01T10:00:00.000Z"
    }
  ]
}

For plain rendered text, the extension searches the source to recover the most precise line range. When Markdown formatting prevents an exact text match, it falls back to the source line attached to the rendered block.

Comments created in normal source editors also record optional one-based startColumn and endColumn fields so selected code ranges can be restored precisely. Markdown comment files remain compatible with the same version 1 format and do not require these fields.

When the extension finds an older adjacent <source>.comments.json file, it copies the comments into the new mirrored .comments location and updates source to the workspace-relative path. The old file is left untouched.

Ask Claude to process the review

After saving at least one comment, choose Copy LLM prompt in the preview toolbar. The copied prompt contains the absolute Markdown and JSON paths and asks the LLM to process every comment sequentially without changing the JSON file.

The generated prompt follows this shape:

Read examples/review-me.md and .comments/examples/review-me.md.comments.json.
Apply every review comment to the Markdown file, then summarize what changed.

Development

1. Run corepack pnpm run compile to compile the extension.
2. Run corepack pnpm test to compile and execute the unit tests.
3. Run corepack pnpm run watch while developing.

The extension supports local Markdown and ordinary text/code files. The .comments directory is created after the first comment is saved or when an older adjacent comments file is migrated.