Code Explainer Notes

Code Explainer Notes lets you attach private explanations to code selections in VS Code without changing the source files.

Use it to document tricky code, leave review notes for yourself, onboard into an unfamiliar project, or keep temporary explanations next to the code while you work.

Features

• Attach an explanation to a selected block of code.
• Write multiline explanations in a dedicated editor panel.
• Show or hide explanations with CodeLens actions.
• See a gutter marker on annotated lines.
• Preview explanations on hover.
• Browse all workspace comments from the Code Explainer side panel.
• Edit or delete existing explanations.
• Store comments locally in .vscode/code-comments.json.

Usage

1. Open a workspace in VS Code.
2. Select a block of code.
3. Run Code Explainer: Add Comment from the Command Palette or editor context menu.
4. Write the explanation in the Code Explainer editor.
5. Click Save.
6. Use Show explanation, Edit, or Delete from the CodeLens above the annotated code.

You can also open the Code Explainer activity bar view to browse comments grouped by file.

Storage and Privacy

Comments are stored locally in the current workspace:

.vscode/code-comments.json

The extension does not send code or comments to any external service. The stored JSON file is part of your workspace, so decide whether it should be committed or ignored for each project.

Explanation Format

Explanations are stored as plain text. You can write Markdown-style text such as:

• paragraphs across multiple lines;
• lists with - item;
• inline code with `value`;
• links like [label](https://example.com).

Hover rendering uses VS Code Markdown support. CodeLens display remains line-based.

Current Limits

• The gutter marker is visual only; VS Code does not expose direct click handling for gutter icons.
• Anchor matching is heuristic. If the selected code and its surrounding context change heavily, a comment may become stale or disappear from the active file view.
• Comments are workspace-local. There is no sync, conflict resolution, or encryption layer yet.
• The extension is an early MVP and should be tested on non-critical workspaces first.

Development

Install dependencies:

pnpm install

Compile:

npm run compile

Run tests:

npm run test

Launch the extension from VS Code with F5.