Claude Comments

A VS Code extension that adds Google Docs-style commenting to any file, with comments stored in sidecar JSON files that AI assistants (like Claude Code) can read.

Why?

When working with AI coding assistants, you often want to leave notes, questions, or feedback on specific parts of a document. This extension bridges that gap by:

1. Providing a native VS Code commenting UI (like GitHub PR comments)
2. Storing comments in human-readable JSON files alongside your documents
3. Making those comments visible to AI assistants that can read the sidecar files

Features

Core Functionality

• Inline comments: Select text and add comments that appear as collapsible threads in the editor gutter
• Reply threads: Add follow-up notes to existing comments
• Resolve/Unresolve: Mark comments as resolved (they collapse and are deprioritized)
• Delete comments: Remove comments you no longer need

Storage

• Comments stored in .{filename}.comments.json sidecar files
• Human-readable JSON format
• Git-friendly (can be tracked or ignored)
• Survives file moves if you move the sidecar file too

Keyboard Shortcuts

• Cmd+Shift+M (Mac) / Ctrl+Shift+M (Windows): Add comment on selected text

Installation

From Source (Development)

git clone https://github.com/SwordShieldMouse/claude-comments.git
cd claude-comments
npm install
npm run compile

Then press F5 in VS Code to launch the Extension Development Host.

Package as VSIX

npm install -g @vscode/vsce
vsce package
code --install-extension claude-comments-0.1.0.vsix

Usage

Adding a Comment

1. Select text in any file
2. Either:
   • Right-click → "Add Comment for Claude"
   • Press Cmd+Shift+M / Ctrl+Shift+M
   • Click the + icon in the gutter
3. Type your comment and click "Comment"

Replying to a Comment

1. Click on an existing comment thread
2. Type in the reply box
3. Click "Reply"

Resolving Comments

• Click the "Resolve/Unresolve" button in the comment thread header
• Resolved comments collapse and show "(Resolved)" in the label

Viewing All Comments

• Use VS Code's Comments panel: View → Comments
• Shows all comments across open files in a sidebar list

For AI Assistants

Add this to your project's CLAUDE.md or similar instruction file:

## User Comments

When reading any document, check for a companion comment file at `.{filename}.comments.json`.

Example: Reading `draft.md` → also check `.draft.md.comments.json`

Format:
{
  "comments": [
    {
      "body": "Comment text",
      "startLine": 10,
      "endLine": 12,
      "anchor": "selected text...",
      "resolved": false,
      "replies": [
        {"body": "Follow-up note", "author": "You"}
      ]
    }
  ]
}

Focus on unresolved comments. Resolved comments are for reference only.

File Format

{
  "version": 1,
  "comments": [
    {
      "id": "comment-1704312600000-abc123def",
      "body": "Is this claim accurate?",
      "startLine": 10,
      "startChar": 0,
      "endLine": 12,
      "endChar": 50,
      "createdAt": "2024-01-03T18:30:00.000Z",
      "anchor": "The first 100 characters of selected text...",
      "resolved": false,
      "resolvedAt": null,
      "replies": [
        {
          "id": "comment-1704312700000-xyz789",
          "body": "Verified - adding citation",
          "author": "You",
          "createdAt": "2024-01-03T18:31:40.000Z"
        }
      ]
    }
  ]
}

Known Issues & Limitations

No Cmd+Enter to Submit

VS Code's Comments API doesn't support custom keyboard shortcuts for submitting comments. The CommentReply context object is only passed when clicking UI buttons, not through keybindings. You must click the "Comment" or "Reply" button to submit.

Workaround: After typing, press Tab to focus the button, then Enter.

Comment Width

The comment widget takes significant horizontal space. This is VS Code's default behavior and cannot be customized through the extension API.

Workaround: Use the Comments sidebar (View → Comments) for a more compact view.

Line Anchoring

Comments are anchored to line numbers. If you edit the file significantly, comments may become misaligned with their original context. The anchor field stores the original selected text to help identify what the comment referred to.

No Real-time Sync

If you edit the .comments.json file directly, you need to reload the window for changes to appear in the UI.

Development

npm install
npm run watch    # Compile in watch mode
# Press F5 to launch Extension Development Host

Project Structure

claude-comments/
├── src/
│   ├── extension.ts        # Entry point, command registration
│   ├── commentController.ts # VS Code Comments API integration
│   └── storage.ts          # Sidecar file read/write
├── package.json            # Extension manifest
└── tsconfig.json

License

MIT