inline-comments

The Inline Comments project facilitates effortless text highlighting and comment attachment without altering the original file. Comments are stored in a dedicated .comments.json file located at the root of the workspace, enabling both agents (such as Claude via MCP) and users through the editor or CLI to contribute to a unified comment store with real-time updates.

Key Features

• Text Anchoring: Comments are directly linked to the quoted text rather than being tied to line or character offsets. This means if the text is modified, comments will automatically follow, maintaining context. If the quoted text is entirely rewritten, the comment will not disappear but instead marked as ⚠ stale, retaining visibility to ensure context is preserved.

Usage

• Within the Editor: Easily select text and use the shortcut ⌥C or click the gutter + to add comments. Users can reply to, edit, resolve, or delete comments directly through an intuitive thread UI.

• Using Claude: The MCP server provides an API with commands such as add_comment, list_comments, reply_to_comment, update_comment, resolve_comment, unresolve_comment, and delete_comment. Comments generated by Claude are tagged appropriately and appear in the active editor within approximately one second.

• Terminal Access: Comments can also be managed via CLI commands:

node dist/cli.mjs --workspace /path/to/project add \
  --file Chapter2.tex --quote "the exact text" --body "your comment"
node dist/cli.mjs --workspace /path/to/project list --all

Project Structure

The project files are organized as follows:

src/anchor.ts     // Handles text quote to range resolution  (pure Node)
src/store.ts      // Manages .comments.json read/write operation (pure Node)
src/extension.ts  // Contains Comments API and commands linked to VS Code
src/mcp.ts        // MCP stdio server implementation
src/cli.ts       // Command-line interface

anchor.ts and store.ts are designed to be independent of the vscode module, which is exclusively utilized in the extension host environment.

Development Commands

To set up and develop the project, execute the following commands:

npm install
npm run build       # Alternatively: npm run watch
npm run typecheck
npm run package     # Produces inline-comments-0.1.0.vsix

Configuration Options

Known Limitation

While reflow re-anchoring is effective, it currently has limitations with whitespace collapsing and line-comment markers. When rewrapping text that has comments marked (for example, in LaTeX with % or //), the comments may become stale rather than re-anchoring properly.