Code Explainer Notes

Code Explainer Notes lets you attach 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 a compact explanation preview with CodeLens actions and read the full text on hover.
• See a gutter marker on annotated lines.
• Preview explanations on hover.
• Read every explanation when multiple notes share a line.
• Browse all workspace comments from the Code Explainer side panel.
• Edit or delete existing explanations.
• Undo a deletion immediately from the notification, restoring the full note and its original anchor.
• Recover unsaved drafts and preview Markdown while editing.
• Choose personal storage outside the repository or shared storage 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. Use the view's search button to match explanation text or file paths. The filter button limits notes to a file or to linked or pending anchors; the clear button restores all notes. Selecting a linked note opens its source location. Search results update after notes are edited, moved, relinked, or deleted. After confirming a deletion, choose Undo in the notification to restore the note. The Undo action is available while that notification is open; dismissing it completes the deletion. If another note has taken the same ID, restoration stops instead of overwriting it. The editor saves unsaved text as a local workspace draft. Closing its tab keeps the draft; reopening an explanation offers to resume or discard it. Cancel asks before discarding changed text. Drafts are cleared only after a successful save or explicit discard. The preview renders Markdown without raw HTML or remote images; it supports the same basic paragraphs, lists, code, and links as the hover.

Display and Shortcuts

The settings codeExplainer.showCodeLens, codeExplainer.showGutterMarkers, and codeExplainer.showHover independently control actions above code, gutter markers, and hover text. All three are enabled by default to preserve the existing experience; turn off CodeLens for the quietest editor view. Settings can be changed per workspace or file and take effect without restarting.

With code selected, press Ctrl+Alt+N (Cmd+Alt+N on macOS) to add a note. Press Ctrl+Alt+O (Cmd+Alt+O on macOS) with the cursor on annotated code to open a note, choosing one when several overlap. These bindings can be remapped in VS Code's Keyboard Shortcuts settings.

Storage and Privacy

Run Code Explainer: Select Storage Mode to choose where notes live. The codeExplainer.storageMode setting offers the same choice. Shared remains the default for compatibility with existing installations.

Both modes keep file paths, ranges, IDs, and timestamps. The selected code and note text remain readable in either mode. Context hashes reduce neighboring code in the shared file; they are not encryption and short lines can be guessed. The shared JSON may be committed to Git. Review it before sharing the repository. By default, the extension does not send code or notes to an external service. Optional AI assistance can send explicitly approved text to a model provider selected in VS Code.

Changing the mode copies and validates notes at the destination before removing the old file. IDs, explanations, creation dates, and anchors are preserved. Previously saved plain context becomes a hash when moved to shared storage and cannot be reconstructed from that hash later. If the extension starts in personal mode and finds an older shared file, it migrates those notes automatically.

In a workspace with multiple folders, each folder has its own file at this path. Notes only appear for files inside their owning folder, and the sidebar groups notes by workspace folder. Adding or removing folders updates the view. Renaming or moving files through VS Code updates their note paths, including moves between workspace folders. If a cross-folder save fails midway, rerunning the move is safe: the destination copy is checked before the source is removed.

The extension reloads the active JSON file before each change and uses a temporary .lock file alongside it to serialize writes across VS Code windows. If another application changes the JSON file during a save, the extension cancels that save and asks you to retry. If a crash leaves the lock behind, close all editors using the workspace before removing the lock file. The extension reads older unversioned and version 1 files and migrates them on the next successful edit. Unknown versions or invalid note fields stop reads and writes with an error; the original JSON remains intact for recovery.

Use Code Explainer: Export Notes to save a versioned JSON archive for one workspace folder. Code Explainer: Import Notes reads an archive, validates every note, and lets you choose the destination folder. Before import, it shows counts of new notes, duplicates, and conflicts. Only new notes are added; duplicates and conflicting IDs are skipped, and existing notes are never overwritten. If notes change between preview and confirmation, import stops and you can retry. Imported paths remain relative to the destination folder; use Relink Explanation if a source file is absent. The archive contains note text, selected code, and anchor context, so review it before sharing.

Optional AI Assistance

codeExplainer.ai.enabled is false by default. Run Generate Explanation with AI on a code selection or Rephrase Explanation with AI on a note to enable it for this workspace. For each request, choose an available VS Code language model and approve the data transfer. VS Code may separately ask for provider access. AI assistance requires VS Code 1.91 or later and an available model; the rest of the extension works without one.

Generation sends only the selected code and its language ID. Rephrasing sends only the chosen explanation. Neither command sends the file path, whole file, neighboring code, other notes, workspace JSON, or local drafts. Input is limited to 20,000 characters. The provider may apply its own usage limits and data policies; review those before approving a request. The extension never starts an AI request automatically or records prompts or responses in logs.

The result opens in the editable Markdown panel. Review and change it before clicking Save; canceling does not create or alter a note. A draft is kept if saving fails or the source changes during review. The extension stores no API key because it uses VS Code's Language Model API.

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.

For performance checks, run corepack pnpm run benchmark:anchors. It measures anchor resolution for 1,000 notes in a 10,000-line document and verifies that the document text is read once per batch.

If a note can no longer be located in its source file, it appears under À rattacher in the Comments view. Open it there to read or edit the explanation. To attach it again, select the new code in an editor and choose Relink Explanation to Selection from the note's context menu. The explanation and its original creation date are kept.

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.
• Notes are local or repository shared. There is no remote sync or encryption layer yet.
• A proposed sync policy and a non-production conflict prototype are documented in docs/collaboration-sync.md.
• The extension is an early MVP and should be tested on non-critical workspaces first.

Development

Install dependencies:

corepack pnpm install --frozen-lockfile

Compile:

corepack pnpm run compile

Compilation type-checks the sources and bundles runtime dependencies into out/extension.js so the installable extension works without node_modules.

Run unit tests with corepack pnpm test. Run the command/provider integration suite with corepack pnpm run test:integration; it starts an isolated VS Code Extension Development Host. The runner downloads VS Code when needed. Set VSCODE_EXECUTABLE_PATH to use an installed executable instead.

Run lint and tests:

corepack pnpm run lint
corepack pnpm test
corepack pnpm run test:integration

The CI runs lint, compilation, unit tests, and the VS Code integration suite on every pull request. It runs the same checks on pushes to develop.

Manual extension test

1. Run corepack pnpm run compile, then open this repository in VS Code and press F5.
2. In the Extension Development Host, open a temporary workspace with two folders.
3. Select several lines of a file and run Code Explainer: Add Comment. Save a multiline explanation. Confirm its CodeLens, gutter marker, hover, and sidebar entry appear.
4. Edit the explanation, hide and show it, then move or rename its file through VS Code. Confirm the note follows the file and remains editable.
5. Change the selected code so the note becomes orphaned. Confirm it appears under À rattacher, then select its new location and relink it.
6. Switch between shared and personal storage with Code Explainer: Select Storage Mode. Confirm notes remain accessible and that shared mode writes .vscode/code-comments.json in the correct workspace folder.
7. Delete a note and confirm it disappears from the editor and sidebar. Close and reopen the Extension Development Host to confirm saved notes persist.