CodeXPlained

Hover over a block of code and CodeXPlained highlights it and shows an AI explanation of what it does — with the entire current file used as context, so the explanation understands how the block fits into the rest of the code.

How it works

• Highlighting: as you move the caret, the enclosing block is highlighted (debounced and cancellable, so fast movement stays smooth).
• Explanation: native VS Code hover. Move your mouse over any code, and the hovered block is highlighted and explained in the hover card.
• Block detection: uses the language's document symbols (function / method / class) for the smallest enclosing block, falling back to an indentation/brace heuristic when no symbol is available.
• Model backend:
  1. GitHub Copilot — if you have Copilot, CodeXPlained uses its language models through VS Code's built-in Language Model API. No API key needed. (The first request shows a one-time consent prompt from VS Code.)
  2. Anthropic API — if no Copilot model is available, it asks once for an Anthropic API key (stored securely in the OS keychain via SecretStorage) and calls the Anthropic API directly.

Run it (development)

npm install

Then press F5 in VS Code (“Run Extension”). This compiles the TypeScript and opens an Extension Development Host window with CodeXPlained loaded. Open any source file in that window and hover over some code.

To iterate, run the watch task (npm: watch) and reload the dev window (Ctrl+R) after changes.

Testing

Manual: press F5 (or run the dev host) and use the checklist in the repo — caret highlighting, hover explanation, backend selection, and the commands below.

Automated: a @vscode/test-cli + Mocha suite runs the deterministic logic inside a real VS Code instance:

npm test

It compiles first (pretest), downloads a VS Code build on first run, then asserts:

• Block detection (indentation fallback): header+body, single line, blank line, empty document.
• Prompt building: whole-file context vs. trimmed context with a marker.
• Whole-line range (toWholeLineRange): partial multi-line and single-line ranges expand to full lines.
• Cache logic: version-keyed cache hit, invalidation on edit, in-flight coalescing, undefined not cached, eviction past the cap, clearCache.

Visual behavior (green fill, popup, spinner) still needs manual eyeballing — VS Code exposes no API to assert rendered decorations.

Tests live in src/test/; the runner config is .vscode-test.mjs.

Commands

Settings

Popup styling

The hover popup is VS Code's shared hover widget — extensions can't paint its background, and that's intentional (it stays readable and follows your theme). To tie it to CodeXPlained's green, this repo's .vscode/settings.json sets a green border on the widget:

"workbench.colorCustomizations": {
  "editorHoverWidget.border": "#3fbf6f",
  "editor.hoverHighlightBackground": "#00000000",
  "[Default Dark Modern][Default Dark+][Visual Studio Dark]": {
    "editorHoverWidget.background": "#18241c"
  },
  "[Default Light Modern][Default Light+][Visual Studio Light]": {
    "editorHoverWidget.background": "#f1faf4"
  }
}

The border and subtle green background tint affect all hovers in the workspace, not just CodeXPlained's. The tints are theme-scoped so light and dark each stay readable; add your theme's exact name if it isn't listed.

Notes

• Explanations are cached per file version and block range, so edits invalidate stale explanations automatically and re-hovering is free.
• LLM calls take a moment; the hover shows a loading spinner until the explanation arrives, and cancels if you move away.
• Requires VS Code 1.95+ (for the stable Language Model API).